MD 分类：AI与Agent 更新：2026/5/12

Claw Code 架构分析

1. 项目定位

Claw Code 是 Claude Code（Anthropic 官方 CLI 工具）的 Rust 重写版本，属于 UltraWorkers 工具链生态的一部分。目标是以 Rust 的性能和安全性重新实现 Claude Code 的全部功能，同时保持与上游 TypeScript 版本的功能对等（parity）。

核心数据：

~20K 行 Rust 代码
9 个 crate 的 Cargo workspace
二进制名：claw
默认模型：claude-opus-4-6
默认权限：danger-full-access

生态伙伴：

oh-my-openagent — 多 Agent 协调（规划、交接、分歧解决）
oh-my-claudecode — Claude Code 增强
oh-my-codex — 构建基础
clawhip — 配套工具

2. 设计哲学

瓶颈不再是打字速度。当 Agent 系统能在数小时内重建一个代码库时，稀缺资源变成了：架构清晰度、任务分解能力、判断力、品味、对什么值得构建的信念、以及知道哪些部分可以并行哪些必须串行。

Claw Code 的哲学核心：

快速 Agent 团队不消除思考需求，而是让清晰思考更有价值
仓库可以被公开构建 — 完全开放的开发过程
功能对等优先 — 先追平上游，再做差异化
Rust 带来的确定性 — 内存安全、零成本抽象、编译时保证

3. 技术栈

层次	技术选型
语言	Rust（Cargo workspace）
构建系统	Cargo（9 crate workspace）
API 客户端	自研 Anthropic Messages API client（流式、重试、token 计数）
LLM 支持	Claude API + OpenAI 兼容 API（DeepSeek 等）
CLI 框架	自研 REPL + 直接 CLI 子命令
配置	分层 JSON 配置（`.claw.json` + `settings.json`）
测试	确定性 mock 服务 + parity harness
容器	Containerfile（OCI 兼容）

4. 系统架构

graph TB
    subgraph CLI["入口层 rusty-claude-cli"]
        REPL["REPL 交互模式"]
        ONE["One-shot 单次模式"]
        SUB["直接子命令<br/>status / sandbox / agents / mcp / skills / doctor"]
        SLASH["斜杠命令<br/>/help /status /cost /config /model /permissions"]
    end

    subgraph Runtime["运行时层 runtime"]
        CR["ConversationRuntime<br/>对话运行时"]
        CFG["Config Loader<br/>分层配置加载"]
        SP["System Prompt Assembly<br/>系统提示组装"]
        PERM["Permission Policy<br/>权限策略"]
        SESS["Session Persistence<br/>会话持久化"]
        MCP_L["MCP Client Lifecycle<br/>MCP 客户端生命周期"]
        USAGE["Usage Tracking<br/>用量追踪"]
        BASH["Bash Execution<br/>沙箱执行"]
    end

    subgraph API["API 层 api"]
        ANT["Anthropic Messages Client"]
        OAI["OpenAI 兼容 Client"]
        STREAM["流式处理"]
        RETRY["重试策略"]
        TOKEN["Token 计数"]
        PREF["Request Profiles"]
    end

    subgraph Tools["工具层 tools"]
        BASH_T["bash"]
        READ["read"]
        WRITE["write"]
        EDIT["edit"]
        GREP["grep"]
        GLOB["glob"]
        WEB["web search/fetch"]
        AGENT["Sub-agent 运行时"]
        SKILL["Skill 解析"]
        TSEARCH["Tool Search"]
    end

    subgraph Plugins["插件层 plugins"]
        META["Plugin Metadata"]
        INSTALL["Install/Enable/Disable"]
        PTOOLS["Plugin Tool Definitions"]
        HOOK["Hook Integration"]
    end

    subgraph Commands["命令层 commands"]
        PARSE["命令解析"]
        HELP["帮助文本生成"]
        RENDER["JSON/Text 渲染"]
    end

    subgraph Telemetry["遥测层 telemetry"]
        TRACE["Session Trace Events"]
        PAYLOAD["Telemetry Payloads"]
    end

    subgraph Compat["兼容层 compat-harness"]
        EXTRACT["从上游 TS 源码提取<br/>tool/prompt manifests"]
    end

    subgraph Mock["测试层 mock-anthropic-service"]
        MOCK_SVC["确定性 /v1/messages Mock"]
        PARITY["Parity Harness<br/>10 个脚本化场景"]
    end

    CLI --> Runtime
    Runtime --> API
    Runtime --> Tools
    Runtime --> Plugins
    CLI --> Commands
    Runtime --> Telemetry
    Compat -.-> |"提取上游 manifest"| Runtime
    Mock -.-> |"确定性测试"| API

    style CLI fill:#4a9eff,color:#fff
    style Runtime fill:#ff6b6b,color:#fff
    style API fill:#ffd93d,color:#333
    style Tools fill:#6bcb77,color:#fff

5. Crate 职责详解

5.1 `rusty-claude-cli` — 入口与交互

职责：REPL、单次提示、直接 CLI 子命令、流式显示、工具调用渲染、CLI 参数解析

这是整个应用的入口 crate，包含：

交互式 REPL 模式（默认）
一次性 prompt 模式（claw "your prompt"）
直接子命令（claw status、claw doctor、claw sandbox 等）
流式 token 渲染到终端
工具调用的可视化展示

5.2 `runtime` — 核心运行时

职责：ConversationRuntime、配置加载、会话持久化、权限策略、MCP 客户端生命周期、系统提示组装、用量追踪

这是最核心的 crate，承担：

ConversationRuntime：对话状态管理、消息历史、上下文窗口控制
Config Loader：5 层配置文件解析（~/.claw.json → ~/.config/claw/settings.json → .claw.json → .claw/settings.json → .claw/settings.local.json）
Permission Policy：权限检查与执行控制
Session Persistence：会话保存与恢复（--resume latest）
System Prompt Assembly：动态组装系统提示（注入 CLAUDE.md、项目上下文等）
MCP Client：MCP 服务器连接管理
Sandbox：基于 unshare 的沙箱隔离

5.3 `api` — LLM API 客户端

职责：Anthropic Messages API 客户端（流式、重试、token 计数、请求预检）

支持 Anthropic 原生 API
支持 OpenAI 兼容 API（DeepSeek 等推理模型）
流式 SSE 解析
重试策略与错误处理
Token 计数与上下文窗口预检
Request profiles 管理
Provider-aware 模型身份（ModelFamilyIdentity：Claude vs Generic）

5.4 `tools` — 工具系统

职责：内置工具、Skill 解析、工具搜索、Agent 运行时表面

内置工具集：

工具	功能
`bash`	Shell 执行（支持沙箱、超时、后台）
`read`	文件读取
`write`	文件写入
`edit`	行级编辑（hash-anchored）
`grep`	内容搜索
`glob`	文件模式匹配
`web_search` / `web_fetch`	Web 工具
`sub-agent`	子 Agent 运行时

Hash-anchored Edit：使用 LINE#ID 引用在应用更改前验证内容，确保手术式精确编辑，零过时行错误。

5.5 `commands` — 命令系统

职责：斜杠命令定义、解析、帮助文本生成、JSON/Text 命令渲染

支持的斜杠命令：

/skills — Skill 管理
/agents — Agent 管理
/mcp — MCP 服务器管理
/doctor — 健康检查
/plugin — 插件管理
/subagent — 子 Agent 管理
/hooks — 生命周期钩子

5.6 `plugins` — 插件系统

职责：插件元数据、安装/启用/禁用/更新流程、插件工具定义、Hook 集成

5.7 `telemetry` — 遥测

职责：会话追踪事件和遥测 payload

5.8 `compat-harness` — 兼容性工具

职责：从上游 TypeScript 源码提取 tool/prompt manifests，确保 Rust 版本与上游行为一致

5.9 `mock-anthropic-service` — 测试 Mock

职责：确定性 /v1/messages mock 服务，用于 CLI parity 测试和本地 harness 运行

6. 数据流

flowchart LR
    User["用户输入"] --> CLI["rusty-claude-cli<br/>REPL / One-shot"]
    CLI --> RT["runtime<br/>ConversationRuntime"]
    RT --> |"组装 messages + tools"| API["api<br/>Anthropic Client"]
    API --> |"SSE 流式"| LLM["Claude / OpenAI API"]
    LLM --> |"tool_use"| API
    API --> RT
    RT --> |"dispatch tool_call"| TOOLS["tools<br/>bash/read/edit/..."]
    TOOLS --> |"执行结果"| RT
    RT --> |"流式 token"| CLI
    CLI --> |"渲染输出"| User

    subgraph Config["配置层"]
        C1["~/.claw.json"]
        C2["~/.config/claw/settings.json"]
        C3[".claw.json"]
        C4[".claw/settings.json"]
        C5[".claw/settings.local.json"]
    end

    Config --> |"合并覆盖"| RT

    subgraph Memory["持久化"]
        SESS["Session 存档"]
        CLAUDE_MD["CLAUDE.md<br/>项目记忆"]
    end

    RT <--> SESS
    RT --> CLAUDE_MD

7. 请求链路

sequenceDiagram
    participant U as 用户
    participant CLI as CLI (REPL)
    participant RT as Runtime
    participant API as API Client
    participant LLM as Claude API
    participant TOOLS as Tools

    U->>CLI: "重构这个函数"
    CLI->>RT: run_turn(prompt)
    RT->>RT: 组装 System Prompt<br/>(CLAUDE.md + 项目上下文 + 配置)
    RT->>API: POST /v1/messages<br/>(messages + tools + stream)
    API->>LLM: SSE 流式请求

    loop Tool Use 循环
        LLM-->>API: tool_use: bash("cargo test")
        API-->>RT: ToolCall
        RT->>RT: Permission Policy 检查
        RT->>TOOLS: dispatch(bash, args)
        TOOLS->>TOOLS: 沙箱执行
        TOOLS-->>RT: ToolResult
        RT->>API: POST /v1/messages<br/>(+ tool_result)
        API->>LLM: 继续
    end

    LLM-->>API: end_turn
    API-->>RT: 完成
    RT-->>CLI: 最终响应
    CLI-->>U: 渲染输出
    RT->>RT: Session 持久化

8. 核心设计思想

8.1 功能对等（Parity-First）

Claw Code 不是”受 Claude Code 启发”的新项目，而是严格的功能重写：

compat-harness crate 从上游 TypeScript 源码自动提取 tool/prompt manifests
mock-anthropic-service 提供确定性测试环境
PARITY.md 逐 feature 跟踪对等状态
10 个脚本化 parity 场景，19 个捕获的 /v1/messages 请求

为什么这样做：确保重写不丢失上游任何行为，同时利用 Rust 的类型系统发现上游的隐含假设。

8.2 Cargo Workspace 多 Crate 架构

9 个 crate 的拆分遵循单一职责原则：

编译隔离 — 修改一个 crate 不需要重编译全部
测试隔离 — 每个 crate 可独立测试
依赖控制 — crate 间的依赖关系显式声明
代码组织 — 约 20K 行分布在 9 个 crate 中，每个 crate 保持精简

为什么这样做：Rust 的模块系统比 TypeScript 更严格，workspace 提供了类似微服务的隔离效果但在编译时就完成。

8.3 分层配置合并

5 层配置文件，后加载的覆盖先加载的：

~/.claw.json (全局)
  → ~/.config/claw/settings.json (XDG)
    → .claw.json (项目根)
      → .claw/settings.json (项目)
        → .claw/settings.local.json (本地覆盖)

为什么这样做：支持全局默认 → 项目共享 → 个人覆盖的配置模式，适合团队协作。

8.4 Provider-Aware 身份

ModelFamilyIdentity 枚举区分 Claude 和通用模型：

Claude 模型使用 Claude 身份
非 Anthropic 模型（DeepSeek 等）不再声称”我是 Claude”

为什么这样做：当接入 OpenAI 兼容 API 时，避免模型身份泄露。

8.5 Hash-Anchored 编辑

LINE#ID 引用系统确保编辑的精确性：

每行有唯一标识
编辑前验证内容未变化
避免过时行号导致的错误编辑

为什么这样做：纯行号编辑在并发修改时容易出错，hash 锚定提供了内容级别的安全保障。

9. Tradeoff

决策	收益	代价
Rust 重写	内存安全、性能、编译时保证	开发速度慢、生态不如 TS 丰富
功能对等优先	不丢失上游功能	受上游设计约束，难以自由创新
9 crate workspace	编译隔离、职责清晰	初始理解成本高、跨 crate 修改需同步
5 层配置	灵活的团队协作	配置优先级复杂、调试困难
默认 `danger-full-access`	开箱即用、减少摩擦	安全风险高
自研 API client	完全控制流式/重试逻辑	需要自己维护 API 兼容性
Mock parity harness	确定性测试、防止回归	维护 mock 本身的成本
多 provider 支持	灵活性	身份管理复杂度增加

10. 与上游 Claude Code 的对比

维度	Claude Code (TypeScript)	Claw Code (Rust)
语言	TypeScript / Node.js	Rust
代码量	较大（未开源全部）	~20K 行
启动速度	Node.js 冷启动	原生二进制，即时启动
内存占用	Node.js GC	无 GC，确定性释放
认证	Claude 订阅 + API Key	仅 API Key
工具系统	相同工具集	对等实现
插件系统	支持	支持
MCP	支持	支持（`claw acp serve` 为别名）
测试	上游测试套件	Mock parity harness

11. 可复用模式

11.1 Parity-First 重写策略

上游功能 manifest 提取 → 确定性 mock 服务 → 脚本化 parity 场景 → 逐 feature 对等验证

11.2 Cargo Workspace 分层

入口层 (cli) → 运行时层 (runtime) → API 层 (api) → 工具层 (tools)
                                              ↕
                                    插件层 (plugins) + 遥测层 (telemetry)

11.3 分层配置合并

// 5 层配置，后覆盖前
let config = merge([
    load("~/.claw.json"),
    load("~/.config/claw/settings.json"),
    load(".claw.json"),
    load(".claw/settings.json"),
    load(".claw/settings.local.json"),
]);

11.4 Provider-Aware 模型路由

enum ModelFamilyIdentity {
    Claude,
    Generic,
}
// 根据 provider 选择身份和行为

12. 值得学习的重点

Rust 重写大型 TypeScript 项目的实践 — 如何保持功能对等同时利用 Rust 优势
Cargo Workspace 多 Crate 架构 — 大型 Rust 项目的模块化组织方式
Parity Harness 设计 — 确定性 mock 服务 + 脚本化场景的测试策略
分层配置合并 — 支持全局/项目/个人的配置覆盖模式
Provider-Aware 设计 — 多 LLM 后端的统一抽象与身份管理
Hash-Anchored Edit — 比行号更可靠的编辑定位方案
兼容性提取工具 — 从上游源码自动提取行为 manifest 的工程方法
“瓶颈不再是打字速度”的哲学 — Agent 时代架构师的核心能力转变

关联知识

Claude Code — 上游 TypeScript 版本
Rust — 实现语言
Cargo Workspace — Rust 多 crate 工作区
Anthropic API — LLM API 接口
OpenAI Compatible API — 多 provider 支持
MCP Protocol — Model Context Protocol
Agent Framework — Agent 框架设计
CLI Design — 命令行工具设计
Parity Testing — 功能对等测试
oh-my-openagent — 多 Agent 协调层
oh-my-codex — 构建基础框架
Sandbox Isolation — 沙箱隔离技术
Streaming SSE — 流式服务端推送