Claw-Code：开源AI编程代理框架，干净室重构的高性能Agent Harness

原创 发布日期：
75

一、Claw-Code是什么

Claw-Code是一款开源、跨语言、模型无关的AI智能代理（Agent）框架，核心定位是Claude Code的干净室重写版，专注打造高效、安全、可扩展的Agent Harness（代理工具架）系统。

1.1 项目诞生背景

2026年3月31日凌晨，Anthropic公司旗下AI编程工具Claude Code的51.2万行TypeScript源码意外泄露，引发开源社区震动。面对泄露源码的版权风险与法律隐患，韩国开发者instructkr（sigridjin）没有选择直接复制分发，而是采用干净室工程原则：仅研究Claude Code的架构模式、工具链设计与工作流逻辑，完全不保留、不复制任何原始源码，在数小时内用Python从零实现核心模块，快速发布Claw-Code开源项目。

项目发布后瞬间引爆GitHub：2小时突破5万星、3小时破3万星、24小时超10万星，创下GitHub历史上最快涨星记录，成为AI代理与编程工具领域的现象级开源项目。其核心价值并非“复刻盗版”，而是通过合法重构，为开发者提供可研究、可使用、可扩展的AI代理架构参考，同时规避原始泄露源码的版权风险。

1.2 核心定位与本质区别

  • 与Claude Code的区别：Claw-Code不是Claude Code的副本或镜像，而是独立开发的兼容实现——保留原系统的Agent Harness核心能力（工具编排、任务调度、会话管理），但代码100%原创、技术栈从TypeScript转为Python+Rust、安全性与性能全面优化。

  • 与普通AI助手的区别：普通AI助手仅提供代码生成，Claw-Code是可自主执行的编程代理：能直接读写文件、执行Shell命令、调用Git、管理项目、多智能体协同，具备完整的“理解-规划-执行-反馈”闭环。

  • 开源合规性：项目明确声明与Anthropic无任何关联，不拥有Claude Code原始版权，仅通过公开架构分析实现功能等效，完全符合开源合规要求。

1.3 项目核心目标

  1. 合法复现：通过干净室开发，完整复现Claude Code的核心Agent Harness能力。

  2. 性能升级：从Python原型逐步迁移至Rust，实现内存安全、高并发、低延迟的运行时。

  3. 模型中立：打破Claude Code的模型绑定，支持OpenAI、Gemini、本地LLM等任意模型接入。

  4. 生态开放：插件化架构支持自定义工具、命令、插件，打造可扩展的AI代理生态。

  5. 工程参考：为LLM Agent、工具编排、MCP协议等领域提供可验证、可学习的开源实现。

二、功能特色

Claw-Code围绕“自主执行、智能编排、安全可控、跨模型兼容”四大核心，构建了完善的AI代理功能体系，覆盖编程开发、系统管理、任务自动化全场景。

2.1 全栈式工具集成系统

项目内置40+权限受控的标准化工具，覆盖开发全流程，支持AI代理自主调用完成复杂任务：

  • 文件操作工具：读/写/删/改文件、批量替换、目录遍历、文件搜索、编码转换

  • 系统交互工具：Shell命令执行、脚本运行、进程管理、环境变量读取、系统信息获取

  • 代码开发工具：代码审查、语法检查、格式化、重构、注释生成、测试用例编写

  • 版本控制工具：Git命令封装（commit/push/pull/branch）、提交记录分析、冲突解决

  • 信息获取工具：Web搜索、网页抓取、API调用、数据解析、文档总结

  • 任务管理工具：待办事项创建、进度跟踪、任务拆分、状态同步、超时控制

2.2 多智能体协同编排

支持Swarm模式多智能体集群，可动态创建多个子Agent并行协作，解决复杂开发任务：

  • 角色分工：主Agent负责需求理解与任务规划，子Agent专注代码编写、测试、审查、文档等单一职责。

  • 并行执行：多个Agent同时处理子任务，大幅缩短复杂项目开发周期（如7个Agent可将23小时重构任务压缩至5小时）。

  • 上下文隔离：每个Agent拥有独立会话上下文，避免状态干扰，同时支持全局状态共享。

  • 结果聚合：主Agent自动汇总子Agent执行结果，生成完整报告并处理异常。

2.3 模型无关的LLM适配层

核心设计亮点是解耦模型与执行逻辑，支持任意大语言模型无缝接入：

  • 统一Provider抽象：通过api-client模块封装模型接口，兼容Anthropic Claude、OpenAI GPT、Google Gemini、通义千问、Llama 3等主流模型。

  • 动态切换：运行中可自由切换模型，无需修改业务代码，适配不同场景的精度、速度、成本需求。

  • 本地模型支持：可接入Llama 2、ChatGLM等开源本地模型，实现完全离线、隐私安全的AI代理服务。

  • 流式响应：支持模型输出流式传输，实时查看执行进度，提升交互体验。

2.4 多层级会话与记忆管理

具备长期记忆+短期上下文+项目专属记忆的三层记忆体系，实现连贯的智能交互：

  • 短期上下文：保留当前会话历史，支持对话轮次管理、上下文压缩（减少Token消耗）。

  • 长期记忆：持久化存储用户偏好、代码规范、项目规则、禁忌指令，跨会话复用。

  • 项目记忆：针对单个项目存储架构文档、依赖关系、核心文件清单、开发规范，Agent自动遵循项目规则。

  • 成本追踪：内置cost_tracker模块，实时统计Token消耗、API调用次数、费用估算。

2.5 插件化与可扩展性

采用微内核+插件化架构，支持全方位功能扩展：

  • 工具插件：自定义开发专属工具，注册后即可被AI代理调用，支持权限控制。

  • 命令插件：扩展斜杠命令（/command），新增交互指令与快捷操作。

  • 运行时插件：通过钩子（Hook）机制扩展会话生命周期、工具执行前后逻辑。

  • 编辑器集成：提供compat-harness兼容层，支持VS Code、Vim、Neovim等编辑器无缝集成。

2.6 安全与权限控制

针对AI代理高权限操作，设计多层安全防护机制：

  • 权限沙盒：工具执行默认受限，敏感操作（文件删除、系统命令）需用户授权。

  • 操作审计：完整记录所有工具调用、命令执行、文件修改日志，支持回溯审查。

  • 内存安全：Rust核心模块从编译层杜绝内存泄漏、空指针、数据竞争等安全隐患。

  • 输入校验：严格校验AI生成的执行指令，过滤恶意代码、非法路径、高危命令。

2.7 双语言实现优势

项目同时提供Python版（稳定可用）与Rust版（高性能主力），兼顾易用性与性能：

版本 开发状态 核心优势 适用场景
Python版（src/） 稳定、功能完整 开发快速、易调试、插件丰富、入门简单 原型验证、学习研究、轻量任务、快速开发
Rust版（rust/） 主力开发、逐步合并 内存安全、高并发、低延迟、性能极致 生产环境、大规模任务、高权限场景、长期运行

三、技术细节

Claw-Code采用模块化、分层化、高内聚低耦合的架构设计，核心分为Python基础实现与Rust高性能重构两大体系，技术栈前沿、架构清晰、扩展性极强。

3.1 干净室重实现技术规范

项目严格遵循干净室开发（Clean-room Engineering）标准，确保100%原创与合规：

  1. 信息隔离：开发团队仅通过公开文档、架构图、功能说明了解Claude Code逻辑，不接触原始源码。

  2. 独立编码：所有代码从零编写，无任何复制、粘贴、反编译内容，关键模块通过测试验证功能一致性。

  3. 架构借鉴：仅吸收Agent Harness、工具编排、MCP协议等设计思想，不照搬具体实现。

  4. 合规声明：仓库明确标注“非Anthropic官方项目、无原始版权、仅供学习研究”。

3.2 Python版核心架构（主分支）

Python版是项目的基础参考实现，代码结构清晰、功能完整，适合学习与二次开发：

3.2.1 核心目录结构

claw-code/
├── src/          # 主源码目录
│  ├── main.py       # CLI入口、命令解析、调度核心
│  ├── models.py      # 数据模型（子系统、模块、任务状态）
│  ├── commands.py     # 斜杠命令元数据、注册与执行
│  ├── tools.py       # 工具抽象接口、内置工具实现
│  ├── query_engine.py    # 查询引擎、工作空间摘要生成
│  ├── task.py       # 任务调度、状态管理、异常处理
│  ├── port_manifest.py   # 工作空间清单、模块导出
│  ├── cost_tracker.py   # Token消耗、费用统计
│  └── utils.py       # 工具函数、配置解析、日志
├── tests/         # 单元测试、集成测试
│  ├── test_commands.py
│  ├── test_tools.py
│  └── test_query_engine.py
├── README.md        # 项目说明、快速开始
├── requirements.txt    # Python依赖清单
└── LICENSE         # MIT开源协议

3.2.2 核心模块详解

  1. Main（入口模块）

    • 职责：解析命令行参数、初始化配置、启动REPL交互、分发命令/工具请求。

    • 核心命令：summary（生成项目摘要）、manifest（打印工作空间清单）、commands（列出所有命令）、tools（列出所有工具）。

    • 交互模式：支持直接指令执行（claw "写一个Python爬虫"）与交互式REPL两种模式。

  2. Models（数据模型）

    • 定义核心数据结构：Subsystem（子系统）、Module（功能模块）、Task（任务）、Tool（工具）、Session（会话）。

    • 支持状态序列化/反序列化，实现会话持久化存储。

  3. Commands（命令系统）

    • 采用元数据注册模式，每个命令包含名称、描述、参数、权限、处理函数。

    • 内置命令：/help（帮助）、/status（状态）、/clear（清空上下文）、/save（保存会话）、/load（加载会话）、/model（切换模型）、/cost（查看消耗）。

  4. Tools（工具系统）

    • 抽象基类：BaseTool定义统一接口（execute()、validate()、permission()）。

    • 工具注册：通过装饰器自动注册，支持动态加载、启用/禁用、权限分组。

    • 执行隔离：工具运行在独立上下文，支持超时控制、异常捕获、结果校验。

  5. QueryEngine（查询引擎）

    • 分析工作空间结构、代码依赖、文件关系，生成结构化摘要。

    • 支持自定义模板，输出Markdown、JSON、文本等格式报告。

3.3 Rust版高性能架构（dev/rust分支）

Rust版是项目未来主力版本，将系统拆分为9个独立Crate（子包），实现模块化、高性能、内存安全的运行时：

3.3.1 核心Crate清单

rust/
├── api-client/     # API客户端、模型适配、流式传输、OAuth
├── runtime/       # 核心运行时、会话管理、MCP编排、上下文压缩
├── tools/        # 工具框架、内置工具实现、权限控制
├── commands/      # 斜杠命令、技能发现、配置检查
├── plugins/       # 插件模型、钩子机制、内置插件
├── compat-harness/   # 编辑器集成兼容层（VS Code/Vim）
├── claw-cli/      # 交互式REPL、Markdown渲染、项目引导
├── server/       # HTTP/SSE服务、远程调用、Web界面
└── lsp/         # LSP客户端、代码编辑器智能提示

3.3.2 核心技术亮点

  1. MCP（Model Context Protocol）编排

    • 实现Claude Code核心的模型上下文协议，动态管理Agent与工具、模型、用户的交互流程。

    • 支持上下文压缩、历史截断、关键信息提取，大幅降低Token消耗。

  2. 异步高并发

    • 基于Tokio异步 runtime，支持数千并发任务、非阻塞I/O、低延迟响应。

    • 工具执行、API调用、文件操作全异步化，充分利用多核CPU。

  3. 内存安全设计

    • 利用Rust所有权、生命周期、借用检查，杜绝内存泄漏、空指针、数据竞争。

    • 敏感操作（文件、系统命令）添加严格安全校验，避免越权访问。

  4. 微服务化架构

    • 每个Crate独立编译、测试、部署，支持按需加载、热更新。

    • 提供FFI接口，支持Python、Node.js等语言调用Rust核心能力。

3.4 核心协议与标准

  • MCP协议：Model Context Protocol，Agent与外部系统交互的核心协议，定义上下文传递、工具调用、结果返回规范。

  • OpenAI兼容API：api-client模块兼容OpenAI API格式，支持直接接入OpenAI生态工具。

  • LSP协议：支持语言服务器协议，实现编辑器代码补全、诊断、重构等功能。

  • MIT开源协议：项目完全开源免费，允许商用、修改、分发，无版权限制。

Claw-Code：开源AI编程代理框架，干净室重构的高性能Agent Harness

四、应用场景

Claw-Code凭借自主执行、多Agent协同、跨模型兼容的核心能力，覆盖个人开发、团队协作、自动化运维、AI研究四大领域，适用场景广泛。

4.1 个人开发者：AI编程超级助手

  • 快速项目搭建：自然语言描述需求，Agent自动生成项目架构、代码文件、配置脚本、依赖清单。

  • 代码开发与重构：编写/修改/优化代码、批量替换、注释生成、代码审查、Bug修复。

  • 自动化测试：生成单元测试、集成测试、性能测试用例，自动执行并输出报告。

  • 文档自动生成：从代码生成API文档、README、接口说明、使用教程。

  • 日常开发效率提升：自动处理Git提交、环境配置、部署脚本、日志分析。

4.2 开发团队：协同开发与自动化管理

  • 代码审查自动化：定义团队规范，Agent自动审查代码风格、安全漏洞、性能问题。

  • 多分支并行开发：多Agent协同处理不同功能分支，自动合并、解决冲突。

  • 项目进度管理：跟踪任务进度、生成周报、风险预警、资源分配建议。

  • 标准化开发流程：强制遵循代码规范、测试要求、文档标准，提升团队代码质量。

4.3 运维与自动化：系统管理与任务批处理

  • 服务器自动化运维：执行Shell命令、日志分析、服务监控、故障排查、备份恢复。

  • 数据处理与分析：批量处理文件、数据清洗、格式转换、报表生成、可视化展示。

  • 定时任务与监控：定时执行脚本、监控网站/API状态、库存变动、价格预警。

  • 办公自动化：批量填写表单、生成日报、整理文件、发送邮件、会议纪要总结。

4.4 AI研究与学习：Agent架构实战参考

  • LLM Agent研究：学习Agent Harness、工具编排、多智能体协作、MCP协议的工程实现。

  • 干净室开发实践：参考合规重构、版权规避、架构复现的技术方案。

  • Rust+AI开发学习：掌握Rust在AI领域的高性能应用、内存安全设计、异步编程。

  • 二次开发与定制：基于Claw-Code开发专属AI代理、行业工具、垂直领域助手。

4.5 隐私敏感场景：本地离线部署

  • 企业内部代码：接入本地LLM（Llama 3、ChatGLM），完全离线运行，避免代码泄露风险。

  • 敏感数据处理：处理金融、医疗、政务等敏感数据，数据不离开本地服务器。

  • 内网隔离环境：在内网、无外网环境使用，保障数据安全与合规。

五、使用方法

Claw-Code支持本地部署、命令行交互、模型配置、工具扩展全流程，操作简单、入门门槛低，以下是详细使用步骤。

5.1 环境要求

  • Python版：Python 3.9+、Git、pip（推荐3.10+）

  • Rust版：Rust 1.75+、Cargo、Git（推荐最新稳定版）

  • 模型支持：Anthropic API Key / OpenAI API Key / 本地LLM部署（如Llama 3）

5.2 安装与部署（Python版，推荐新手）

步骤1：克隆仓库

git clone https://github.com/instructkr/claw-code.git
cd claw-code

步骤2：安装依赖

pip install -r requirements.txt

步骤3：配置API密钥（方式一：环境变量，推荐）

# Linux/macOS
export ANTHROPIC_API_KEY="你的Anthropic API密钥"
export OPENAI_API_KEY="你的OpenAI API密钥（可选）"

# Windows（PowerShell）
$env:ANTHROPIC_API_KEY="你的Anthropic API密钥"
$env:OPENAI_API_KEY="你的OpenAI API密钥（可选）"

步骤4：快速验证安装

# 生成项目摘要
python3 -m src.main summary

# 查看所有命令
python3 -m src.main commands --limit 10

# 查看所有工具
python3 -m src.main tools --limit 10

5.3 基本使用方式

5.3.1 直接指令执行（单次命令）

# 基础用法：python3 -m src.main "你的指令"
python3 -m src.main "写一个Python Flask Web服务，包含用户登录接口"
python3 -m src.main "审查当前目录所有Python代码，修复语法错误"
python3 -m src.main "生成当前项目的README文档"

5.3.2 交互式REPL模式（推荐）

# 启动交互式终端
python3 -m src.main

# 进入REPL后，直接输入指令或斜杠命令
>>> 写一个Dockerfile用于Python Flask项目
>>> /help        # 查看帮助
>>> /model claude-3-sonnet # 切换模型
>>> /cost        # 查看Token消耗
>>> /save my_session   # 保存当前会话
>>> /exit        # 退出

5.3.3 Rust版编译与运行（进阶）

# 切换到Rust分支
git checkout dev/rust
cd rust

# 编译（Release模式）
cargo build --release

# 运行
./target/release/claw-cli

# 执行指令
./target/release/claw-cli "分析当前项目代码结构，生成模块依赖图"

5.4 模型配置与切换

5.4.1 支持的模型列表

  • Anthropic：claude-3-opus、claude-3-sonnet、claude-3-haiku

  • OpenAI：gpt-4o、gpt-4、gpt-3.5-turbo

  • 本地模型：Llama 3、Mistral、ChatGLM3、Qwen（需配置本地API地址）

5.4.2 切换模型（REPL模式）

# 切换到Claude 3 Sonnet
>>> /model claude-3-sonnet

# 切换到GPT-4o
>>> /model gpt-4o

# 切换到本地Llama 3
>>> /model http://localhost:8000/v1 llama3

5.5 自定义工具开发（扩展）

步骤1：创建工具文件（src/tools/custom_tool.py）

from src.tools import BaseTool, register_tool

@register_tool
class CustomFileTool(BaseTool):
  name = "custom_file_analyze"
  description = "分析文件内容，统计行数、字符数、单词数"
  parameters = [{"name": "file_path", "type": "string", "description": "文件路径"}]
  permission = "read" # 权限：read/write/execute

  def execute(self, file_path: str) -> dict:
    """执行工具逻辑"""
    try:
      with open(file_path, 'r', encoding='utf-8') as f:
        content = f.read()
        lines = content.count('\n') + 1
        chars = len(content)
        words = len(content.split())
        return {
          "success": True,
          "data": {"lines": lines, "chars": chars, "words": words}
        }
    except Exception as e:
      return {"success": False, "error": str(e)}

步骤2：注册工具（src/tools/init.py）

from .custom_tool import CustomFileTool

步骤3：使用自定义工具

>>> 分析文件 main.py 的行数、字符数和单词数

六、常见问题解答（FAQ）

问题1：Claw-Code与Claude Code有什么区别？可以替代Claude Code吗？

答：两者核心区别在于版权、代码、技术栈：Claw-Code是100%原创的干净室重写版，采用Python+Rust；Claude Code是Anthropic的闭源TypeScript项目。目前Python版已实现架构级等效，但尚未完全复现所有运行时能力；Rust版开发完成后将实现完整替代，且性能、安全性更优。

问题2：使用Claw-Code会有版权风险吗？

答：完全没有。项目严格遵循干净室开发原则，无任何原始泄露源码，仅借鉴公开架构；仓库明确声明与Anthropic无关联，采用MIT开源协议，可合法用于学习、开发、商用。

问题3：必须使用Anthropic API吗？可以用本地模型吗？

答：不是必须。Claw-Code是模型无关框架，支持Anthropic、OpenAI、Google及任意本地LLM（如Llama 3、ChatGLM）。配置本地模型API地址即可完全离线使用，保障数据隐私。

问题4：执行命令时提示“权限不足”怎么办？

答：Claw-Code默认开启权限沙盒，敏感操作（文件删除、系统命令）需授权。

解决方法：

  • 1. 启动时添加--unsafe参数（谨慎使用）；

  • 2. 在工具调用时手动确认授权；

  • 3. 修改配置文件调整默认权限级别。

问题5：Python版和Rust版该选哪个？

答：新手推荐Python版：安装简单、易调试、文档完善、适合日常使用。生产环境推荐Rust版：性能极致、内存安全、高并发、适合长期运行与大规模任务。可先通过Python版熟悉功能，再迁移至Rust版。

问题6：API密钥如何安全存储？

答：推荐三种方式：

  • 1. 环境变量（最安全，避免密钥写入代码）；

  • 2. 配置文件（.claw_config，设置文件权限600）；

  • 3. 密钥管理工具（如1Password、Bitwarden），通过脚本动态读取。绝对不要将密钥硬编码到代码中或提交到Git。

问题7：运行时提示“命令未找到”或“模块缺失”？

答：常见原因是环境变量未配置或依赖未安装。

解决步骤：

  • 1. 确认Python/Rust已添加到系统PATH；

  • 2. 重新执行pip install -r requirements.txt（Python）或cargo build（Rust）；

  • 3. 重启终端，确保环境变量生效。

问题8：如何处理AI生成的代码不符合预期？

答：

  • 1. 优化指令描述：明确编程语言、功能、输入输出、异常处理、格式要求；

  • 2. 分步拆解任务：复杂需求拆分为多个小任务，逐步执行；

  • 3. 反馈修正：指出问题，让Agent重新优化；

  • 4. 切换模型：复杂任务用高精度模型（如GPT-4o、Claude 3 Opus）。

问题9：Rust版编译失败怎么办？

答：

  • 1. 确认Rust版本≥1.75，执行rustup update更新；

  • 2. 安装系统依赖：Ubuntu执行sudo apt-get install libssl-dev libsqlite3-dev，macOS执行brew install openssl sqlite；

  • 3. 清理缓存：cargo clean后重新编译。

问题10：可以将Claw-Code集成到VS Code等编辑器吗？

答：可以。Rust版提供compat-harness兼容层，支持VS Code、Vim、Neovim等编辑器集成；Python版可通过插件或命令行调用实现集成。官方计划推出编辑器插件，实现无缝交互。

七、相关链接

八、总结

Claw-Code作为GitHub史上涨星最快的现象级开源项目，不仅是Claude Code的合规重构版，更是AI代理架构、干净室开发、跨语言高性能实现的标杆工程。它通过原创代码与架构创新，完美平衡了AI代理的功能完整性、运行安全性、开发易用性与扩展灵活性，既为普通开发者提供了高效、安全的AI编程助手，也为AI Agent领域研究者提供了可深度剖析的工程实践参考。项目从Python原型到Rust高性能重构的演进路径，清晰展现了开源AI工具从“可用”到“好用”再到“工业级可靠”的发展方向。无论用于个人开发、团队协作、自动化运维还是AI研究，Claw-Code都凭借其合规性、先进性与实用性，成为当前AI代理工具领域的首选开源方案。

AI编程助手 开源项目
打赏

版权及免责申明：本文由@dotaai原创发布。该文章观点仅代表作者本人，不代表本站立场。本站不承担任何相关法律责任。

如若转载，请注明出处：https://www.aipuzi.cn/ai-news/claw-code.html

THE END
作者头像
dotaai
正在和我的聊天机器人谈恋爱，它很会捧场。