当前位置：首页 > news >正文

【 Claw-Code】技术深度解析：Claude Code Agent Harness 的开源重实现

news 2026/8/11 0:49:37

文章目录

Claw-Code 技术深度解析：Claude Code Agent Harness 的开源重实现
- 一、引言
- 二、项目背景与定位
- - 2.1 为什么是"洁室重实现"
  - 2.2 项目核心目标
- 三、双语言架构设计
- - 3.1 双语言实现对比
  - 3.2 Rust Workspace 模块划分
- 四、核心组件解析
- - 4.1 运行时（Runtime）
  - 4.2 工具系统（Tools）
  - 4.3 插件系统（Plugins）
  - 4.4 MCP（Model Context Protocol）集成
- 五、交互层设计
- - 5.1 REPL 与 CLI 体验
  - 5.2 编辑器兼容层（compat-harness）
- 六、AI 辅助开发工作流
- 七、与同类项目横向对比
- 八、总结与展望

Claw-Code 技术深度解析：Claude Code Agent Harness 的开源重实现

一、引言

2026年3月31日，Claude Code 的核心源码意外曝光，迅速在 AI 开发者社区引发轰动。随即，Claw-Code（by instructkr）以"洁室重实现（Cleanroom Reimplementation）"的方式出现——项目发布后2小时内突破50,000 Star，刷新了 GitHub 历史增速记录。

Claw-Code 并非对泄露代码的简单归档，而是作者在深入理解原始 Agent Harness 架构模式后，以 Python + Rust 双语言从零重写的工程实现。本文将从架构设计、核心组件、工作流与技术亮点四个维度对 Claw-Code 进行系统解析。

二、项目背景与定位

2.1 为什么是"洁室重实现"

维度	泄露代码归档	Claw-Code 洁室重实现
法律风险	高（直接分发私有代码）	低（独立重写，不含原始代码）
工程价值	仅为存档，无法持续演进	可独立迭代维护
学习价值	直接复制，缺乏理解	深度重构，架构可读性强
社区贡献	被动传播	主动开源，推动生态发展

洁室方法的核心原则：在不接触原始代码的前提下，仅凭对其行为模式与接口规范的理解进行独立实现，从根本上规避知识产权风险。

2.2 项目核心目标

Claw-Code 的目标定位是“Better Harness Tools”——不仅复现已有能力，更希望以更优雅的工程设计提供可扩展、可维护的 Agent Harness 基础设施。

三、双语言架构设计

Claw-Code 同时维护Rust和Python两套实现，分别面向不同目标用户与场景。

3.1 双语言实现对比

维度	Rust 实现（claw-cli）	Python 实现（src/）
主要目标	高性能生产运行时	快速验证与原型开发
内存安全	编译时保障	运行时检查
启动延迟	极低（毫秒级）	较高（解释器开销）
生态集成	系统级工具链	AI/ML 库生态丰富
开发进度	进行中（合并主干）	已完成核心功能
适用人群	系统工程师、性能敏感场景	AI 开发者、二次开发

3.2 Rust Workspace 模块划分

claw-cli（Rust Workspace） ├── crates/api-client # API 客户端：Provider 抽象、OAuth、流式输出 ├── crates/runtime # 核心运行时：Session 状态、上下文压缩、MCP 编排 ├── crates/tools # 工具清单定义与执行框架 ├── crates/commands # Slash 命令、Skills 发现、配置检视 ├── crates/plugins # 插件模型：Hook Pipeline + 内置插件 ├── crates/compat-harness # 编辑器集成兼容层（IDE Extension） └── crates/claw-cli # 交互式 REPL、Markdown 渲染、项目引导流程

各模块职责清晰，层级依赖严格，核心运行时（runtime）作为中枢，协调 API、工具、MCP 三个执行子系统。

四、核心组件解析

4.1 运行时（Runtime）

Runtime 是整个 Harness 的调度核心，负责管理 Agent 会话的全生命周期：

子系统	功能	关键设计
Session State	维护对话上下文与工具调用历史	持久化存储，跨会话恢复
Context Compaction	超长上下文自动压缩	保留关键信息，降低 Token 消耗
Prompt Construction	动态组装系统提示与工具描述	模块化 Prompt 工厂模式
MCP Orchestration	外部工具编排与结果聚合	标准化协议接入

4.2 工具系统（Tools）

工具系统是 Agent 与外部环境交互的核心通道，采用清单式声明管理所有可用工具：

工具类别	典型工具	能力说明
文件操作	Read / Write / Edit / Glob	精准读写，支持差量编辑
代码执行	Bash / 沙箱执行器	安全隔离的命令执行环境
搜索检索	Grep / WebSearch / WebFetch	代码内容搜索与网络信息获取
任务管理	TodoWrite / TaskOutput	结构化任务规划与进度跟踪
Agent 调度	Agent（子 Agent 派发）	支持并行多 Agent 协同

工具清单（Tool Manifest）以声明式配置驱动，新增工具无需修改核心运行时，实现真正的插件化扩展。

4.3 插件系统（Plugins）

Claw-Code 的插件架构基于Hook Pipeline模型，允许在 Agent 执行的关键节点注入自定义逻辑：

Hook 类型	触发时机	典型用途
PreToolCall	工具调用前	权限校验、参数审计
PostToolCall	工具调用后	结果后处理、日志记录
PrePromptSubmit	提示词提交前	上下文注入、内容过滤
OnSessionEnd	会话结束时	资源清理、摘要生成

4.4 MCP（Model Context Protocol）集成

MCP 是 Claw-Code 对外扩展能力的标准协议层：

对比项	传统工具调用	MCP 集成方式
接入方式	硬编码在运行时内	标准协议动态注册
扩展成本	需修改核心代码	实现 MCP Server 即可接入
多工具编排	顺序调用	支持并行编排与结果聚合
生态兼容性	局限于内置工具	对接任意 MCP 兼容服务

五、交互层设计

5.1 REPL 与 CLI 体验

claw-cli提供了完整的交互式命令行体验，与原版 Claude Code 高度对标：

功能模块	技术实现	用户体验提升点
Markdown 渲染	终端内富文本渲染	代码块、表格直接在 CLI 呈现
Slash 命令	命令路由 + Skills 发现	`/help`、`/commit`、自定义 Skill 一键调用
项目引导流程	Bootstrap 向导	首次使用自动检测项目类型并配置
配置检视	实时配置查询	权限、模型、Hook 状态可视化

5.2 编辑器兼容层（compat-harness）

compat-harnesscrate 抽象了与 IDE 扩展（VS Code、JetBrains 等）通信的协议层，使得 Claw-Code 可作为 IDE AI 扩展的底层运行时被集成，而无需插件开发者感知底层实现差异。

六、AI 辅助开发工作流

Claw-Code 本身的开发过程也是 AI Harness 工具链实战验证的绝佳案例：

工具	角色定位	主要贡献
oh-my-codex（OmX）	主编排层	项目脚手架、工作流调度
oh-my-opencode（OmO）	实现加速层	代码生成与逻辑验证
`$team`模式	并行评审	架构级代码 Review，多视角反馈
`$ralph`模式	持续执行	架构师级持久循环验证

整个洁室重实现的开发周期（从理解原始架构到产出带测试的 Python 实现）完全通过上述工具链编排完成，验证了 AI Harness 工具在复杂工程任务中的实际效能。

七、与同类项目横向对比

对比维度	Claw-Code	OpenHands	Aider	Cursor/Windsurf
定位	Claude Code Harness 重实现	通用 AI 软件工程师	CLI 代码辅助	IDE AI 集成
开源协议	开源（洁室）	Apache 2.0	MIT	闭源
运行时语言	Rust + Python	Python	Python	Electron + Node
MCP 支持	✓ 原生	部分支持	✗	✓
多 Agent	✓（子 Agent 派发）	✓	✗	有限支持
Hook 插件系统	✓ Pipeline 模型	有限	✗	插件市场
离线/本地部署	✓	✓	✓	✗