claw-code Rust 实现详解：claw CLI 的架构、模型路由与 Mock 一致性测试体系

本文基于仓库中 rust/README.md 的完整内容展开，讲解 claw-code 的 Rust 工作区如何构建、配置认证、路由到不同模型提供商，以及如何通过一套确定性的 Anthropic Mock 服务在干净环境中做端到端一致性（parity）验证。读完后你可以直接复制命令在 rust/ 目录下编译运行 claw 二进制，理解其 9+ 个 crate 的职责划分，并掌握模型别名解析、JSON 输出契约与 mock 测试场景的底层实现位置。

一、项目定位：高性能的 Rust 重写

rust/ 目录承载了 Claw Code CLI agent harness 的 Rust 重写版本，目标是速度、安全与原生工具执行。整个工作区是一个标准的 Cargo workspace（resolver 2、edition 2021），版本 0.1.3、MIT 许可、publish = false，且在工作区级把 unsafe_code 设为 forbid（见 rust/Cargo.toml 与 rust/AGENTS.md）。

任务导向的使用示例请参见仓库根目录的 USAGE.md；本文聚焦 rust/ 工作区本身的技术细节。

二、快速上手（Quick Start）

以下命令均从 rust/ 目录执行：

# 查看可用命令
cd rust/
cargo run -p rusty-claude-cli -- --help

# 构建整个工作区
cargo build --workspace

# 启动交互式 REPL
cargo run -p rusty-claude-cli -- --model claude-opus-4-7

# 一次性提示（one-shot prompt）
cargo run -p rusty-claude-cli -- prompt "explain this codebase"

# 面向自动化的 JSON 输出
cargo run -p rusty-claude-cli -- --output-format json prompt "summarize src/main.rs"

注意包名与二进制名并不相同：CLI 包叫 rusty-claude-cli，但产出物二进制名为 claw（见 rust/AGENTS.md 中的 "Package name ≠ binary name" 约定）。

三、认证配置与凭据解析

3.1 环境变量配置

Anthropic 官方渠道：

export ANTHROPIC_API_KEY="sk-ant-..."
# 或者走代理
export ANTHROPIC_BASE_URL="https://your-proxy.com"

直接提供 OAuth bearer token：

export ANTHROPIC_AUTH_TOKEN="anthropic-oauth-or-proxy-bearer-token"

对于 Ollama 等本地 OpenAI 兼容服务（含 Qwen 推理模型），参见 local-openai-compatible-providers 文档。要点是使用服务端暴露的精确模型标签（例如 qwen3:latest），并优先用 OLLAMA_HOST 做 Ollama 本地路由。

3.2 源码中的认证与路由逻辑

从源码结构看，认证解析并不止于"读两个环境变量"。在 rust/crates/api/src/providers/mod.rs 中可以看到：

• .env 文件软回退：dotenv_value / load_dotenv_file 会解析工作目录下的 .env（支持注释、引号剥离、export 前缀），因此把密钥写在 .env 里同样生效；
• 跨提供商凭据嗅探：当 Anthropic 认证解析失败时，anthropic_missing_credentials_hint 会检测环境中是否存在 OPENAI_API_KEY、XAI_API_KEY、DASHSCOPE_API_KEY，并在报错中附带针对性的修复建议（例如提示用 --model openai/... 前缀路由）；
• OAuth token 生命周期：anthropic 模块还导出 resolve_saved_oauth_token、oauth_token_is_expired 等函数，说明存在保存/过期检查的 OAuth 凭据路径。

四、提供商路由：从模型名到 wire protocol

claw 同时支持 Anthropic 原生协议与 OpenAI 兼容协议。核心分发表在 rust/crates/api/src/client.rs 的 ProviderClient::from_model_with_anthropic_auth 中：

let resolved_model = providers::resolve_model_alias(model);
match providers::detect_provider_kind(&resolved_model) {
    ProviderKind::Anthropic => Ok(Self::Anthropic(...)),
    ProviderKind::Xai => Ok(Self::Xai(OpenAiCompatClient::from_env(OpenAiCompatConfig::xai())?)),
    ProviderKind::OpenAi => {
        // OLLAMA_HOST takes priority: local Ollama needs no API key
        if std::env::var_os("OLLAMA_HOST").is_some() {
            Ok(Self::OpenAi(openai_compat::OpenAiCompatClient::from_ollama_env()...))
        } else {
            // qwen-* 需要 DashScope 配置（读 DASHSCOPE_API_KEY）
            let config = match providers::metadata_for_model(&resolved_model) {
                Some(meta) if meta.auth_env == "DASHSCOPE_API_KEY" => OpenAiCompatConfig::dashscope(),
                _ => OpenAiCompatConfig::openai(),
            };
            Ok(Self::OpenAi(OpenAiCompatClient::from_env(config)?))
        }
    }
}

detect_provider_kind 的判定顺序（providers/mod.rs）为：

1. OLLAMA_HOST 已设置 → 一律走本地 OpenAI 兼容端点；
2. 模型别名/前缀命中内置注册表（claude* → Anthropic，grok* → xAI，qwen*/kimi* → DashScope，openai/、gpt-*、local/ → OpenAI 兼容）；
3. OPENAI_BASE_URL 已设置且模型名形如本地服务标签（含 : 或 .）→ OpenAI 兼容；
4. 按 ANTHROPIC_API_KEY → OPENAI_API_KEY → XAI_API_KEY 的环境凭据嗅探顺序回退；
5. 兜底为 Anthropic。

此外该模块还实现了上下文窗口 preflight：preflight_message_request 按模型注册表（如 claude-opus-4-7 为 200K 上下文 / 32K 输出）估算输入 token（序列化为 JSON 后 bytes/4+1 的粗估），超限直接抛 ContextWindowExceeded，避免把明显超窗的请求发给服务端。

五、模型别名（Model Aliases）

短名解析到最新版本，定义在 resolve_model_alias：

别名	解析为
opus	claude-opus-4-7
sonnet	claude-sonnet-4-6
haiku	claude-haiku-4-5-20251213

除 Anthropic 三家之外，源码注册表还包含 xAI 的 grok / grok-3 / grok-mini / grok-2 / grok-3-mini 与 DashScope 的 kimi（→ kimi-k2.5）等别名，测试用例 client.rs 中的 resolves_existing_and_grok_aliases 验证了 opus → claude-opus-4-7、grok → grok-3 的解析结果。

六、CLI 标志与命令面

rust/README.md 给出的代表性命令面（以 --help 输出为准）：

claw [OPTIONS] [COMMAND]

Flags:
  --model MODEL
  --output-format text|json  (大小写不敏感; CLAW_OUTPUT_FORMAT 提供默认值, 标志覆盖环境变量)
  --permission-mode MODE
  --cwd PATH, -C PATH, --directory PATH
  --dangerously-skip-permissions, --skip-permissions
  --allowedTools TOOLS        snake_case 规范名或别名; status JSON 暴露 allowed_tools.available/aliases
  --resume [SESSION.jsonl|session-id|latest]
  --version, -V

Top-level commands:
  prompt <text>
  help
  version
  status
  sandbox
  acp [serve]
  dump-manifests
  bootstrap-plan
  agents
  mcp
  skills
  system-prompt
  init

关键行为细节（均来自 README 的命令面章节）：

• 输出格式优先级：--output-format 接受 text/json 任意大小写；CLAW_OUTPUT_FORMAT=json 为非交互命令选择 JSON 默认值，显式标志覆盖环境变量，重复传标志会在 stderr 告警；status JSON 暴露 format_source、format_raw、format_overridden 三个字段用于审计格式来源。Help 与 doctor 输出同时展示 CLAW_LOG / RUST_LOG 作为日志开关。
• claw version --output-format json 是自动化溯源探针：报告完整 git_sha、派生的 git_sha_short、is_dirty、branch、commit_date、commit_timestamp、rustc_version、运行时 executable_path 与 binary_provenance；文本报告放在 human_readable 字段而非重复的 message 字段。
• claw acp 是面向编辑器优先用户的本地可发现性入口：只报告当前 ACP/Zed 状态、不启动运行时。截至 2026-04-16，claw-code 尚未提供 ACP/Zed daemon 或 JSON-RPC 入口，claw acp serve 只是状态别名；状态查询退出码 0，畸形调用退出码 1 且 kind: unsupported_acp_invocation。
• 项目记忆文件：status --output-format json 在 workspace.memory_files[] 下报告加载的记忆文件，每个条目含 path、source（claude_md/claw_md/agents_md 或作用域规则源）、origin、scope_path、outside_project、chars、contributes。根目录指令文件优先级为 CLAUDE.md → CLAW.md → AGENTS.md；发现范围限定在当前 git 根内（否则仅 cwd），所有非重复文件都参与系统提示渲染。claw doctor --output-format json 含专门的 memory 检查。
• MCP 部分成功契约：claw mcp --output-format json 中有效服务器留在 servers[]，畸形条目进 invalid_servers[]，并以 total_configured、valid_count、invalid_count 供自动化消费；status 侧镜像为 mcp_validation，doctor 含 mcp validation 检查。
• Hooks 部分成功契约：status --output-format json 在 hook_validation 下保留合法 hook、将畸形/未知事件条目放入 invalid_hooks[]，带 valid_count、invalid_count 与类型化 kind（invalid_hooks_config 或 unknown_hook_event）；config --output-format json 在存在无效条目时给出降级状态。
• POSIX -- 语义：短提示模式遵守 -- 标志终止符，claw -- "-prompt-with-dash" 与未知破折号开头的非标志文本都会留在 prompt 路径上，而不是被当作 CLI 选项。
• claw dump-manifests 自包含：为选定工作区输出 Rust resolver 清单（commands、tools、agents、skills、bootstrap 阶段），无需上游 Claude Code TypeScript checkout；--manifests-dir PATH 仅用于把 resolver 发现范围限定到另一个目录。

命令面迭代很快，权威列表以 cargo run -p rusty-claude-cli -- --help 的输出为准。

七、REPL 斜杠命令

Tab 补全会展开斜杠命令、模型别名、权限模式与最近会话 ID。REPL 的命令面远超最初的极简 shell，按功能分组：

• 会话/可见性：/help、/status、/sandbox、/cost、/resume、/session、/version、/usage、/stats
• 工作区/git：/compact、/clear、/config、/memory、/init、/diff、/commit、/pr、/issue、/export、/hooks、/files、/release-notes
• 发现/调试：/mcp、/agents、/skills、/doctor、/tasks、/context、/desktop
• 自动化/分析：/review、/advisor、/insights、/security-review、/subagent、/team、/telemetry、/providers、/cron 等
• 插件管理：/plugin（别名 /plugins、/marketplace）

claw 特有的直达斜杠面：

• /skills [list|show <name>|install <path>|uninstall <name>|help]
• /agents [list|show <name>|create <name>|help]
• /mcp [list|show <server>|help]
• /doctor
• /plugin [list|install <path>|enable <name>|disable <name>|uninstall <id>|update <id>]
• /subagent [list|steer <target> <msg>|kill <id>]

从 rust/AGENTS.md 可以看到 commands crate 承载了 120+ 斜杠命令，tools crate 提供 55 个工具，依赖方向为 tools → commands（禁止反向依赖）。

八、功能状态总览

README 中的功能矩阵（全部标为 ✅ 已实现）：

功能	状态
Anthropic / OpenAI 兼容提供商流 + 流式	✅
ANTHROPIC_AUTH_TOKEN 直接 bearer-token 认证	✅
交互式 REPL（rustyline）	✅
工具系统（bash, read, write, edit, grep, glob）	✅
Web 工具（search, fetch）	✅
Sub-agent / agent 面	✅
Todo 跟踪	✅
Notebook 编辑	✅
CLAUDE.md / CLAW.md / AGENTS.md 项目记忆	✅
配置文件层级（.claw.json + 合并配置段）	✅
权限系统	✅
MCP 服务器生命周期 + 检查	✅
会话持久化 + 恢复	✅
Cost / usage / stats 面	✅
Git 集成	✅
Markdown 终端渲染（ANSI）	✅
模型别名（opus/sonnet/haiku）	✅
直接 CLI 子命令（status、sandbox、agents、mcp、skills、doctor）	✅
斜杠命令（含 /skills、/agents、/mcp、/doctor、/plugin、/subagent）	✅
Hooks（/hooks、配置驱动的 lifecycle hooks）	✅
插件管理面	✅
Skills 清单 / 安装 / 卸载面	✅
核心 CLI 面的机器可读 JSON 输出	✅

九、Mock 一致性测试体系（Mock Parity Harness）

这是 rust/ 工作区最有特色的一部分：一个确定性的 Anthropic 兼容 Mock 服务 + 一个干净环境 CLI 测试 harness，用于端到端 parity 检查。

9.1 运行方式

cd rust/

# 运行脚本化的干净环境 harness
./scripts/run_mock_parity_harness.sh

# 或手动启动 mock 服务做临时 CLI 验证
cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0

harness 脚本本体极薄（rust/scripts/run_mock_parity_harness.sh），核心就是一行 cargo test -p rusty-claude-cli --test mock_parity_harness -- --nocapture——所有编排逻辑在 Rust 测试里完成。手动启动的 mock 服务（main.rs）支持 --bind HOST:PORT / --bind=...，启动后打印 MOCK_ANTHROPIC_BASE_URL=... 供 CLI 通过 ANTHROPIC_BASE_URL 指向它。

9.2 Mock 服务的实现要点

从 mock-anthropic-service 的 lib.rs 可以看到其设计：

• 手写 HTTP：基于 tokio::net::TcpListener，自己解析请求行、头部与 content-length 定长的 body，不引入 Web 框架；
• 场景驱动：请求消息中若出现 PARITY_SCENARIO:<name> 前缀文本（SCENARIO_PREFIX），detect_scenario 从最后一条消息中定位场景，决定响应内容；
• 两阶段工具回环：例如 read_file_roundtrip 场景，第一轮无工具结果时返回 tool_use（stop_reason: "tool_use"）让 CLI 执行 read_file，第二轮收到 tool_result 后返回最终文本 read_file roundtrip complete: ...，从而验证 CLI 的"模型调用工具 → 执行 → 回填结果 → 综合答复"完整链路；
• SSE 流式：build_stream_body 按 Anthropic 事件序列（message_start → content_block_start → content_block_delta（含 input_json_delta 部分 JSON 分块）→ content_block_stop → message_delta → message_stop）拼装 text/event-stream 响应，其中 grep_chunk_assembly 场景故意把工具入参 JSON 切成 "{\"pattern\":\"par" + "ity\",\"path\":..." 两半，验证客户端能否正确拼装分块 JSON；
• 请求捕获：每个请求以 CapturedRequest（method/path/headers/scenario/stream/raw_body）记录，便于测试断言 CLI 发出的线上行为。

9.3 Harness 覆盖场景

README 列出的主覆盖（与 mock_parity_scenarios.json 的场景清单一致）：

• streaming_text
• read_file_roundtrip
• grep_chunk_assembly
• write_file_allowed
• write_file_denied
• multi_tool_turn_roundtrip
• bash_stdout_roundtrip
• bash_permission_prompt_approved
• bash_permission_prompt_denied
• plugin_tool_roundtrip

场景 JSON 中还有两个补充场景：auto_compact_triggered（验证累计输入 token 超过阈值时自动压缩触发）与 token_cost_reporting（验证 usage 计数与 estimated_cost 出现在 JSON 输出中），源码的 Scenario 枚举同样实现了这两者。

每个场景在 JSON 中都带 parity_refs，把测试场景映射回 PARITY.md 中的里程碑与行为条目，run_mock_parity_diff.py 负责运行这份"场景 → PARITY"清单映射。

主要工件：

• rust/crates/mock-anthropic-service/ — 可复用的 mock Anthropic 兼容服务
• rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs — 干净环境 CLI harness
• rust/scripts/run_mock_parity_harness.sh — 可复现包装脚本
• rust/scripts/run_mock_parity_diff.py — 场景清单 + PARITY 映射运行器
• rust/mock_parity_scenarios.json — 场景到 PARITY 的清单

十、工作区结构与 Crate 职责

README 给出的布局：

rust/
├── Cargo.toml              # Workspace root
├── Cargo.lock
└── crates/
    ├── api/                # Provider clients + streaming + request preflight
    ├── commands/           # Shared slash-command registry + help rendering
    ├── compat-harness/     # Compatibility/parity harness utilities
    ├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
    ├── plugins/            # Plugin metadata, manager, install/enable/disable surfaces
    ├── runtime/            # Session, config, permissions, MCP, prompts, auth/runtime loop
    ├── rusty-claude-cli/   # Main CLI binary (`claw`)
    ├── telemetry/          # Session tracing and usage telemetry types
    └── tools/              # Built-in tools, skill resolution, tool search, agent runtime surfaces

各 crate 职责（README 原文）：

• api — 提供商客户端、SSE 流式、请求/响应类型、认证（ANTHROPIC_API_KEY + bearer-token）、请求大小/上下文窗口 preflight
• commands — 斜杠命令定义、解析、help 文本生成、JSON/text 命令渲染
• compat-harness — 与上游 fixture 对比行为的兼容性/一致性辅助工具
• mock-anthropic-service — 面向 CLI parity 测试与本地 harness 的确定性 /v1/messages mock
• plugins — 插件元数据、安装/启用/禁用/更新流程、插件工具定义、hook 集成面
• runtime — ConversationRuntime、配置加载、会话持久化、权限策略、MCP 客户端生命周期、系统提示组装、用量跟踪
• rusty-claude-cli — REPL、一次性 prompt、直接 CLI 子命令、流式展示、工具调用渲染、CLI 参数解析
• telemetry — 会话 trace 事件与配套遥测 payload
• tools — 工具规格 + 执行：Bash、ReadFile、WriteFile、EditFile、GlobSearch、GrepSearch、WebSearch、WebFetch、Agent、TodoWrite、NotebookEdit、Skill、ToolSearch 及面向运行时的工具发现

需要注意的是，rust/AGENTS.md 记录的成员 crate 实为 11 个：除上述 9 个外，crates 目录中还存在 claw-analog（备用入口，仅依赖 api + runtime）与 claw-rag-service（RAG 服务，是唯一带 [features]（qdrant-index）的 crate），README 的布局图与 "9 crates" 统计相对它们是较早的版本。

十一、统计与默认值

README 给出的统计与默认配置：

• ~20K 行 Rust 代码
• 工作区 9 crates（按 README 口径；实际成员 crate 已增至 11 个）
• 二进制名： claw
• 默认模型： claude-opus-4-7
• 默认权限： workspace-write

开发规约方面，rust/AGENTS.md 补充了若干可执行的约定：格式化统一走 ../scripts/fmt.sh（不要直接对 rust/Cargo.toml 跑 cargo fmt）；推送前应通过 cargo clippy --workspace --all-targets -- -D warnings（比 CI 更严，CI 不加 -D warnings）；TUI 格式化函数只接收 &mut impl Write，不得直接写 stdout 或混用裸 ANSI 与 crossterm。

十二、小结

rust/ 工作区把 claw-code 的 agent harness 落成了"一个二进制 + 分层 crate + 可复现测试"的结构：api 负责多提供商路由与请求 preflight，runtime 承载会话/权限/MCP 等核心状态，rusty-claude-cli 提供 REPL 与全部 CLI 面，而 mock-anthropic-service 与 parity harness 则用确定性场景把流式解析、分块 JSON 拼装、权限拒绝、bash 回环、插件工具等关键链路固化为可重复运行的回归测试。默认模型 claude-opus-4-7、默认权限 workspace-write、unsafe_code = forbid 等设置，共同定义了这套实现"安全优先、可验证"的工程基线。进一步的任务化示例可查 USAGE.md，行为对齐里程碑可查 rust/PARITY.md。