Clawd Code 是一个独立且开源的 Python 项目，旨在将意外泄露的著名 AI 编程助手 Claude Code 的核心交互与工具调度机制进行 Python 开源移植与复现。该项目最初由开发者基于 oh-my-codex (OmX) 框架紧急研发，重点聚焦于前沿的“Harness Engineering”（智能体调度工程）——即深度探索 AI 智能体系统如何高效地调度外部工具、编排复杂任务以及管理超长运行时上下文。该工具不仅仅是一个代码库的备份或概念验证，而是一个真正能够“完成实际工作”的自动化终端编程助手。通过在本地运行，它可以自主读取文件系统、执行代码、运行测试，并内置了多种高级协同模式，帮助开发者深入理解下一代自动化 AI 开发智能体的工作原理和底层架构设计。
功能列表
- 复刻 Claude Code 的终端原生体验：直接在终端环境中与大语言模型对话，AI 可以根据自然语言指令自主浏览目录、读取代码文件、编写及修改代码，并触发本地测试。
- 并行代码审查（$team 模式）：项目独创的高级多线程模式，支持唤起多个 AI 实例以并行方式对代码库进行深度 Review，实现多视角的代码质量验证和安全排查。
- 架构级持久化执行（$ralph 模式）：支持开启持续的执行循环，AI 智能体会站在“架构师”的视角，对复杂重构和开发任务进行多阶段的逻辑推理、代码生成与多轮验证，直到任务完全符合要求。
- OmX 底层工作流引擎支持：基于 oh-my-codex 架构进行流程编排，提供极具弹性的底层调度逻辑，使得大语言模型在多步任务规划中不易丢失上下文。
- 灵活的外部工具链集成：支持通过配置系统环境变量或 Token，直接让智能体调用 GitHub、Linear 等第三方外部工具，完成从编写代码到提交 PR 的全自动化工作流。
- 自定义工作区与智能体身份管理：使用 Markdown 文本文件管理智能体的系统指令和记忆上下文，用户可随时通过编辑本地文本来改变 AI 的性格、编码规范与工作流习惯。
使用帮助
欢迎使用 Clawd Code。作为一款基于 Claude Code 泄露版本进行 Python 开源移植的强大终端 AI 编程智能体，本工具能够接管繁琐的编码、审查和测试任务。为了确保您能充分发挥本工具的潜力并实现 100% 的效率提升，请仔细阅读以下详尽的安装与操作指南。
一、 安装与前置环境准备
1. 系统与环境要求
- 操作系统：支持 macOS、Linux 以及 Windows（推荐使用 WSL2 以获得最佳的终端环境兼容性）。
- Python 版本：要求系统已安装 Python 3.10 或更高版本。
- 包管理工具：推荐使用
pip，为避免依赖冲突，强烈建议配合virtualenv或conda创建隔离的 Python 虚拟环境。
2. 获取源码与依赖安装
打开您的命令行终端，执行以下命令将 Clawd Code 项目克隆到本地并安装必要的运行依赖项：
# 克隆开源仓库到本地
git clone https://github.com/instructkr/clawd-code.git
cd clawd-code
# 创建并激活 Python 虚拟环境（推荐操作）
python3 -m venv venv
source venv/bin/activate # Windows 用户请使用 venv\Scripts\activate
# 安装项目的核心依赖包
pip install -r requirements.txt
3. 环境变量与 API 密钥配置
由于 Clawd Code 是基于大语言模型驱动的智能体系统，您必须配置相应的模型 API 密钥才能使其具备思考和编码能力。项目根目录下提供了一个基础的环境变量模板文件 .env.example。
cp .env.example .env
使用文本编辑器（如 vim、nano 或 VS Code）打开新生成的 .env 文件，填入您的 API Key：
# 必填：配置 Anthropic 的 API 密钥（推荐使用 Claude 3.5 Sonnet）
ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxx"
# 选填：如果需要智能体执行 GitHub 自动化提交流程，建议配置 Personal Access Token
GITHUB_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxx"
二、 核心功能与基础操作流程
1. 启动并进入智能体交互模式
在确保环境变量配置无误且虚拟环境已激活后，通过以下命令启动智能体主程序：
python main.py
启动后，终端将进入一个交互式的命令提示符（Prompt）界面。此时 Clawd Code 已经接管了当前目录的上下文。您可以直接使用自然语言向它发布开发任务。
基础操作示例：
👤 User: “请分析当前目录下的 src/utils.py 文件，找出可能导致内存泄漏的函数，并给出重构建议。”
🤖 Agent: (Clawd Code 开始调度本地文件读取工具 -> 分析代码内容 -> 在终端输出分析报告 -> 询问您是否需要它直接修改该文件)
2. 使用 $team 模式：并行代码审查
在日常开发中，如果您正在处理一个大型的 Pull Request 或者完成了一次涉及多个模块的重大重构，单线思考的 AI 可能会产生遗漏。此时，您可以调用 Clawd Code 特色的 $team 模式。
操作方式：
在终端交互模式下，输入带有 $team 前缀的指令：
$team 审查当前 Git 分支中所有的修改，重点检查 SQL 注入漏洞和多线程安全问题。
工作原理：底层的 OmX 调度引擎会同时派生出多个独立评估的 AI 实例（例如：分配一个专注于网络安全，一个专注于运行性能，一个专注于代码规范）。这些智能体将在终端后台并行读取您的代码，随后将多维度的审查意见汇总并输出给您，极大提高了 Code Review 的严谨度和效率。
3. 使用 $ralph 模式：架构级持久验证执行
常规的代码生成工具往往只会“写出片段代码”，但不能保证“这些代码在整个项目架构中能完美运行”。$ralph 模式是 Clawd Code 专为此设计的高级功能，它赋予了 AI 持久循环执行和多步试错验证的权限。
操作方式：
$ralph 将项目底层的 SQLite 数据库操作逻辑整体迁移到 PostgreSQL，请自行修改代码、编写单元测试并运行验证，直到测试全部通过为止。
工作原理：启动该模式后，Clawd Code 会进入“思考 -> 计划 -> 编码 -> 运行本地测试 -> 捕捉终端报错 -> 自我修正代码 -> 重新测试”的全自动闭环。屏幕终端会出现分步的状态日志，您可以观察它的试错过程，并随时按 Ctrl+C 手动介入或终止。这种模式特别适合处理棘手的、需要反复调试的系统级重构任务。
三、 进阶配置：定制工作区与外部工具集成
1. 管理智能体记忆与工作区 (.workspace)
当您在某个项目目录下首次运行 Clawd Code 时，它会自动在当前目录生成一个类似于 .clawd-workspace/ 的隐藏配置文件夹。这个文件夹相当于当前项目中智能体的“大脑”，里面存放着若干 Markdown 格式的配置文件：
identity.md：定义智能体的角色和性格。您可以将其修改为“你是一个极其严苛的 Linux 内核资深开发者，请以这种口吻和我对话”。rules.md：设定项目专属的编码规范。例如写入：“本项目所有 Python 函数必须严格使用 Type Hints，不准使用全局变量，必须编写 Docstring”。
通过直接使用文本编辑器修改这些本地 Markdown 文件，您可以在不修改任何 Python 底层源码的情况下，完美定制出符合自己团队习惯的专属 AI 助手。
2. 外部工具调度配置 (Tools & Integrations)
Clawd Code 的强大之处在于其“工具链”的扩展能力。通过向系统环境暴露特定的 Token，智能体可以直接操作第三方工具：
- 对接 GitHub 流水线：在
.env文件中配置了GITHUB_ACCESS_TOKEN的情况下，您可以直接对终端说：“把目前的修改提交到一个新的 Git 分支，并创建一个名为feat-update的 PR，将 Reviewer 分配给我”。Clawd Code 会自动调用底层的 Git 命令与 GitHub API 完成一连串操作。 - 调用本地 CLI 工具：如果您系统上安装了代码格式化或静态分析工具（如
black、mypy或ruff），您可以直接命令 AI：“在代码修改完毕后，请运行 ruff 格式化所有修改过的文件”。AI 会像一个真实的程序员一样，在终端中敲打出对应的命令行指令并执行清理工作。
四、 注意事项与最佳实践
- 安全与权限隔离：Clawd Code 具有读取、写入甚至删除您本地系统文件的真实权限。在运行未知来源的自动化任务，或在包含核心生产数据的环境中操作时，强烈建议您使用 Docker 容器或专用的沙盒虚拟机环境来运行 Clawd Code，以防止大语言模型产生“幻觉”导致重要文件被误删或覆盖。
- Token 开销与成本监控：频繁使用
$team（多重 AI 实例并行）和$ralph（持续试错循环）模式会向大模型 API 发送大量请求，消耗大量 Token。建议在进行复杂大任务前，先让 AI 输出简单的执行计划，确认逻辑无误后再授权其执行完整闭环。 - 学术研究与二次开发：本项目（Harness Engineering）的设计初衷是让开发者透明地了解大模型工具调度的原理。建议您仔细阅读项目的底层源码，学习 Clawd Code 是如何通过解析大模型的输出 JSON 格式，将其映射转化为本地 Python 函数执行的，这对于开发您自己的 Agent 系统大有裨益。
应用场景
- 本地自动化编程与代码重构
在处理陈旧的遗留代码库时，开发者可利用 Clawd Code 自动分析复杂的函数依赖关系，并在本地环境直接应用重构补丁，免去了在浏览器（如 ChatGPT 网页版）和本地代码编辑器之间来回复制粘贴的繁琐过程。 - 多维度的代码库并行审查
研发团队在代码合入主干分支前，可以使用$team模式对本地代码库进行快速且并行的自动化排查。Clawd Code 会同时从网络安全性、执行性能、代码格式规范等不同视角给出审查建议，相当于瞬间雇佣了一个资深的架构师评审团。 - 智能体架构研究与二次开发
对于从事 AI Agent 开发的工程师而言，本项目提供了一个极佳的“干净架构”参考源码。开发者可以通过阅读该项目的开源代码，学习如何使用纯 Python 构建任务持久化队列、如何截获并处理 LLM 的幻觉输出，以及如何安全地将本地函数暴露给大语言模型作为工具调用。 - 复杂问题的闭环修复 (Bug Fixing)
面对深层逻辑 Bug，使用$ralph模式挂载任务，让 Clawd Code 自主阅读终端的报错日志、定位源代码文件、修改业务逻辑并反复运行本地测试用例，直至系统不再抛出异常，极大减轻开发者的心智负担和排错时间。
QA
- 这个项目和原版的 Claude Code 有什么关系？
Clawd Code 是基于意外泄露的 Claude Code 版本进行的一个独立、开源的 Python 移植重写版本。开发者基于 oh-my-codex 框架迅速编写了这个功能克隆版，精准复现了其核心的工具调度与终端代理机制。 - 为什么要做这个 Python 开源移植版？
本工具主要用于教育和学习目的（Educational Purpose only）。原版 Claude Code 代码闭源且结构复杂，而这个 Python 开源移植版本去除了商业成分，为开发者提供了一个透明学习 AI 智能体“Harness Engineering”（调度工程）和工作流编排的绝佳研究材料。 - 运行 Clawd Code 需要什么模型支持？
底层调度框架（OmX）依赖于具备强逻辑推理和原生工具调用（Tool Calling）能力的大型语言模型。为获得最佳的自动化编程体验，建议配置 Anthropic 的 Claude 3.5 Sonnet / Opus，或 OpenAI 的 GPT-4o 等顶级模型 API。用户需自行准备并注册对应的 API Key。 - 项目是否可以用于商业公司的日常开发？
该项目本身开源，但开发者明确标明其主要用于学习和教育。将其直接集成到商业工作流中时，您需自行承担潜在的 API 计费成本以及代码自动修改带来的安全责任，并且应遵循其在 GitHub 上的开源协议。再次强烈建议在沙盒或容器中运行以保障本地业务文件安全。
