claw-code Rust 实现详解claw CLI 的架构、模型路由与 Mock 一致性测试体系【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code本文基于仓库中 rust/README.md 的完整内容展开讲解 claw-code 的 Rust 工作区如何构建、配置认证、路由到不同模型提供商以及如何通过一套确定性的 Anthropic Mock 服务在干净环境中做端到端一致性parity验证。读完后你可以直接复制命令在rust/目录下编译运行claw二进制理解其 9 个 crate 的职责划分并掌握模型别名解析、JSON 输出契约与 mock 测试场景的底层实现位置。一、项目定位高性能的 Rust 重写rust/目录承载了 Claw Code CLI agent harness 的 Rust 重写版本目标是速度、安全与原生工具执行。整个工作区是一个标准的 Cargo workspaceresolver 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_KEYsk-ant-... # 或者走代理 export ANTHROPIC_BASE_URLhttps://your-proxy.com直接提供 OAuth bearer tokenexport ANTHROPIC_AUTH_TOKENanthropic-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 protocolclaw同时支持 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为OLLAMA_HOST已设置 → 一律走本地 OpenAI 兼容端点模型别名/前缀命中内置注册表claude*→ Anthropicgrok*→ xAIqwen*/kimi*→ DashScopeopenai/、gpt-*、local/→ OpenAI 兼容OPENAI_BASE_URL已设置且模型名形如本地服务标签含:或.→ OpenAI 兼容按ANTHROPIC_API_KEY→OPENAI_API_KEY→XAI_API_KEY的环境凭据嗅探顺序回退兜底为 Anthropic。此外该模块还实现了上下文窗口 preflightpreflight_message_request按模型注册表如claude-opus-4-7为 200K 上下文 / 32K 输出估算输入 token序列化为 JSON 后bytes/41的粗估超限直接抛ContextWindowExceeded避免把明显超窗的请求发给服务端。五、模型别名Model Aliases短名解析到最新版本定义在 resolve_model_alias别名解析为opusclaude-opus-4-7sonnetclaude-sonnet-4-6haikuclaude-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_FORMATjson为非交互命令选择 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-16claw-code 尚未提供 ACP/Zed daemon 或 JSON-RPC 入口claw acp serve只是状态别名状态查询退出码 0畸形调用退出码 1 且kind: unsupported_acp_invocation。项目记忆文件status --output-format json在workspace.memory_files[]下报告加载的记忆文件每个条目含path、sourceclaude_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_validationdoctor 含mcp validation检查。Hooks 部分成功契约status --output-format json在hook_validation下保留合法 hook、将畸形/未知事件条目放入invalid_hooks[]带valid_count、invalid_count与类型化kindinvalid_hooks_config或unknown_hook_eventconfig --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、/marketplaceclaw 特有的直达斜杠面/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 可以看到commandscrate 承载了 120 斜杠命令toolscrate 提供 55 个工具依赖方向为tools→commands禁止反向依赖。八、功能状态总览README 中的功能矩阵全部标为 ✅ 已实现功能状态Anthropic / OpenAI 兼容提供商流 流式✅ANTHROPIC_AUTH_TOKEN直接 bearer-token 认证✅交互式 REPLrustyline✅工具系统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:0harness 脚本本体极薄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_PREFIXdetect_scenario从最后一条消息中定位场景决定响应内容两阶段工具回环例如read_file_roundtrip场景第一轮无工具结果时返回tool_usestop_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\:\parity\,\path\:...两半验证客户端能否正确拼装分块 JSON请求捕获每个请求以CapturedRequestmethod/path/headers/scenario/stream/raw_body记录便于测试断言 CLI 发出的线上行为。9.3 Harness 覆盖场景README 列出的主覆盖与 mock_parity_scenarios.json 的场景清单一致streaming_textread_file_roundtripgrep_chunk_assemblywrite_file_allowedwrite_file_deniedmulti_tool_turn_roundtripbash_stdout_roundtripbash_permission_prompt_approvedbash_permission_prompt_deniedplugin_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 harnessrust/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、请求大小/上下文窗口 preflightcommands— 斜杠命令定义、解析、help 文本生成、JSON/text 命令渲染compat-harness— 与上游 fixture 对比行为的兼容性/一致性辅助工具mock-anthropic-service— 面向 CLI parity 测试与本地 harness 的确定性/v1/messagesmockplugins— 插件元数据、安装/启用/禁用/更新流程、插件工具定义、hook 集成面runtime—ConversationRuntime、配置加载、会话持久化、权限策略、MCP 客户端生命周期、系统提示组装、用量跟踪rusty-claude-cli— REPL、一次性 prompt、直接 CLI 子命令、流式展示、工具调用渲染、CLI 参数解析telemetry— 会话 trace 事件与配套遥测 payloadtools— 工具规格 执行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-serviceRAG 服务是唯一带[features]qdrant-index的 crateREADME 的布局图与 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 warningsTUI 格式化函数只接收mut impl Write不得直接写 stdout 或混用裸 ANSI 与 crossterm。十二、小结rust/工作区把 claw-code 的 agent harness 落成了一个二进制 分层 crate 可复现测试的结构api负责多提供商路由与请求 preflightruntime承载会话/权限/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。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考