Claw Code 实战指南：从源码构建与运行 Rust 版 claw CLI Agent Harness

Claw Code 实战指南：从源码构建与运行 Rust 版 claw CLI Agent Harness

【免费下载链接】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

Claw Code 是一个以 Rust 实现的clawCLI Agent Harness 公开仓库，官方定位是"由 Agent 托管维护的博物馆级展品"（agent-managed museum exhibit）：harness 负责规划、执行、验证、打标签并持续维护这个工件。本文以仓库根目录 README.md 为主体，完整梳理其源码构建、环境认证、健康检查、首次运行、Windows 适配、二进制定位与排查流程，并结合 rust/ 工作区源码（provider 路由、doctor 诊断、权限体系、模型别名表）进行实现级解读。读完本文，你将掌握：从零构建claw二进制并在 Anthropic / OpenAI 兼容 / 本地 Ollama 等后端之间正确切换的完整实操能力，以及基于claw doctor与 JSON 输出做自动化健康检查的工程方法。

项目定位：先理解它"不是普通产品仓库"

README 开篇用> [!IMPORTANT]给出了一个非常明确的定位声明，这是理解整个仓库的前提：

• Claw Code 不是严肃的生产项目，更接近"博物馆展品"——一个由"螃蟹"（gajaes）驱动的工件，由 Agent 清扫、贴标签、并按上述 harness 的规则自动维护。
• 它不打算像普通产品仓库一样被手工操作。如果你想真正跑任务，上游入口是LazyCodex与Gajae-Code这两个 harness；想观察 Claw Code 这个"化石"则继续向下读。
• 仓库不声称拥有原始 Claude Code 源码材料的所有权，也与 Anthropic 无关联、未经其背书或维护（见文末 Ownership / affiliation disclaimer）。

从工程实践角度看，这个定位意味着：仓库形态以"给 Agent 消费"为第一优先级，因此大量命令（doctor、status、mcp、skills、init）都提供机器可读的--output-format json输出，方便 Agent 或脚本做条件化处理。

仓库形态总览（Current repository shape）

README 给出了仓库顶层结构，与仓库实际文件一致：

• rust/— 规范 Rust 工作区与clawCLI 二进制（9 个 crate：api、commands、compat-harness、mock-anthropic-service、plugins、runtime、rusty-claude-cli、telemetry、tools，详见 rust/README.md）
• USAGE.md— 面向任务的使用指南（构建、认证、CLI、会话、parity-harness 工作流）
• PARITY.md— Rust 移植对等性（parity）状态与迁移说明
• ROADMAP.md— 活跃路线图与清理积压
• PHILOSOPHY.md— 项目意图与系统设计框架
• src/+tests/— 伴随的 Python/参考工作区与审计辅助脚本，不是主要运行时表面

规范的实现位于 rust/，当前仓库的真相来源（source of truth）是ultraworkers/claw-code镜像。所有新手流程都应从 USAGE.md 开始；文件提交/导航问题看 docs/navigation-file-context.md；本地 OpenAI 兼容模型与离线 skill 安装看 docs/local-openai-compatible-providers.md；Windows 用户直接跳到 docs/windows-install-release.md。

ACP / Zed 状态提示：claw-code目前尚未附带 ACP/Zed 守护进程或 JSON-RPC 入口。运行claw acp（或claw --acp）查看当前状态即可；claw acp serve目前只是一个可发现性别名，返回状态并以退出码 0 结束。真实的 ACP 支持仍在 ROADMAP.md 中单独跟踪，公开 JSON 契约见 docs/g011-acp-json-rpc-status-contract.md。

快速开始：五步跑通 claw

README 的 Quick start 是构建-认证-验证-运行的完整闭环，全部命令基于源码构建（本仓库仅支持从源码构建）：

# 1. Clone and build git clone https://gitcode.com/gh_mirrors/claudeco/claw-code cd claw-code/rust cargo build --workspace # 2. Set your API key（Anthropic API key，不是 Claude 订阅） export ANTHROPIC_API_KEY="sk-ant-..." # 3. Verify everything is wired correctly ./target/debug/claw doctor # 4. Run a prompt ./target/debug/claw prompt "say hello" # 5. Start an interactive session ./target/debug/claw

重要警告：cargo install claw-code装的是错误的东西。crates.io 上的claw-codecrate 是一个已废弃的 stub，它只会安装claw-code-deprecated.exe（而不是claw），运行后仅打印"claw-code has been renamed to agent-code"。不要使用cargo install claw-code。要么从本仓库源码构建，要么安装上游二进制：

cargo install agent-code # upstream binary — installs 'agent.exe' (Windows) / 'agent' (Unix)

认证前提：claw要求API key（ANTHROPIC_API_KEY、OPENAI_API_KEY等），Claude 订阅登录不是受支持的认证路径。这一点在源码层面也得到印证：apicrate 的认证解析只读取ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN等环境凭证，不存在订阅 OAuth 的默认路径（见 rust/crates/api/src/providers/mod.rs）。

首跑健康检查：claw doctor

构建后的第一件事是健康检查。README 明确："claw doctoris your first health check — it validates your API key, model access, and tool configuration."

从 rust/crates/rusty-claude-cli/src/main.rs 的源码看，doctor实际上会串行执行12 项检查：

1. check_auth_health— 认证凭证
2. check_base_url_health— base URL
3. check_config_health— 配置文件
4. check_mcp_validation_health— MCP 服务配置
5. check_hook_validation_health— hook 配置
6. check_install_source_health— 安装来源
7. check_workspace_health— 工作区
8. check_memory_health— 项目记忆文件
9. check_boot_preflight_health— 启动预检
10. check_sandbox_health— sandbox 能力
11. check_permission_health— 权限模式
12. check_system_health— 系统环境

任何一项失败都会让claw doctor以非零退出码结束（run_doctor中if report.has_failures() { return Err("doctor found failing checks") }）。这意味着 doctor 可以直接用作 CI/脚本里的前置门禁，而不只是给人看的彩印报告。

Windows 环境搭建（PowerShell 优先）

README 明确PowerShell 是受支持的 Windows 路径，常见 onboarding 问题按以下顺序解决：

1. 先装 Rust— 从 rustup 安装器下载并运行，完成后关闭并重开终端。
2. 验证 Rust 在 PATH 上：

   cargo --version

   若失败，重开终端或按安装器输出配置 PATH 后重试。

3. 克隆并构建（PowerShell、Git Bash、WSL 均可用）：

   git clone https://gitcode.com/gh_mirrors/claudeco/claw-code cd claw-code/rust cargo build --workspace

4. 运行（注意.exe后缀与反斜杠路径）：

   $env:ANTHROPIC_API_KEY = "sk-ant-..." .\target\debug\claw.exe prompt "say hello"

Git Bash / WSL 是可选项而非必需。若偏好 bash 风格路径（/c/Users/you/...），Git Bash（随 Git for Windows 附带）很好用——其MINGW64提示符是正常现象，不是安装损坏。

Windows 的 release ZIP、PATH 设置、provider 切换与通知冒烟测试详见 docs/windows-install-release.md。

构建后：定位二进制并验证

cargo build --workspace之后，claw二进制不会自动安装到系统。按构建模式区分位置：

直接验证构建产物

# macOS/Linux（debug 构建） ./rust/target/debug/claw --help ./rust/target/debug/claw doctor # Windows PowerShell（debug 构建） .\rust\target\debug\claw.exe --help .\rust\target\debug\claw.exe doctor

PowerShell 下还提供一组不需要真实凭证的冒烟命令：

$env:CLAW_CONFIG_HOME = Join-Path $env:TEMP "claw config home" New-Item -ItemType Directory -Force -Path $env:CLAW_CONFIG_HOME | Out-Null Remove-Item Env:\ANTHROPIC_API_KEY, Env:\ANTHROPIC_AUTH_TOKEN, Env:\OPENAI_API_KEY -ErrorAction SilentlyContinue .\rust\target\debug\claw.exe help .\rust\target\debug\claw.exe status .\rust\target\debug\claw.exe config env .\rust\target\debug\claw.exe doctor

这些命令全部成功即代表构建可用。随后运行整个工作区测试套件：

cd rust cargo test --workspace

三种方式把 claw 加入 PATH

方式一：符号链接（macOS/Linux）

ln -s $(pwd)/rust/target/debug/claw /usr/local/bin/claw claw --help

方式二：cargo install（跨平台）——安装到 Cargo 默认目录~/.cargo/bin/（通常在 PATH 上）：

# 在 claw-code/rust/ 目录下执行 cargo install --path . --force claw --help

方式三：更新 shell profile（bash/zsh）

export PATH="$(pwd)/rust/target/debug:$PATH" source ~/.bashrc # 或 source ~/.zshrc claw --help

排查要点

• "command not found: claw"— 二进制在rust/target/debug/claw但不在 PATH 上。用完整路径./rust/target/debug/claw，或按上面方式 symlink/安装。
• "permission denied"— macOS/Linux 上若可执行位未设置，可能需要chmod +x rust/target/debug/claw（很少见）。
• Debug vs. release— 默认是 debug 模式（编译慢、运行稍慢）。加--release可加快运行，但构建本身需要 5–10 分钟。

认证与环境变量：最常见的 401 来自哪里

README 明确指出claw接受两类 Anthropic 凭证环境变量，且二者不可互换——HTTP 头不同，放错位置是最常见的 401 来源：

为什么这很重要：如果把sk-ant-*粘贴进ANTHROPIC_AUTH_TOKEN，Anthropic API 会因 Bearer 头拒绝 API key 而返回401 Invalid bearer token。修复只需一行环境变量调换。新版claw会检测这一具体形态（401 + Bearer 槽位中的sk-ant-*），并在错误信息末尾附加修复提示。

如果你其实想用别的 provider：当claw报告缺少 Anthropic 凭证、但你已导出OPENAI_API_KEY/XAI_API_KEY/DASHSCOPE_API_KEY时，多半是忘了给模型名加 provider 路由前缀。用--model openai/gpt-4.1-mini（OpenAI 兼容 / OpenRouter / Ollama）、--model grok（xAI）或--model qwen-plus（DashScope），前缀路由会自动选择正确的后端——无需清空已有的其他凭证。

模型别名与 Provider 路由机制

README 提到--model sonnet这类别名。其实现位于 rust/crates/api/src/providers/mod.rs：

• 内建别名表（MODEL_REGISTRY+resolve_model_alias）：opus→claude-opus-4-7、sonnet→claude-sonnet-4-6、haiku→claude-haiku-4-5-20251213；以及grok/grok-mini/grok-2（xAI）、kimi（DashScope）。
• Provider 元数据表（metadata_for_model）：claude*/anthropic/→ Anthropic；grok*→ xAI；openai/、local/、gpt-→ OpenAI 兼容；qwen/、qwen-、kimi/、kimi-→ DashScope compatible-mode。
• 检测顺序（detect_provider_kind）：OLLAMA_HOST优先 → 模型名前缀 → 本地形态探测（含:或.的未知模型名 +OPENAI_BASE_URL）→ 按环境凭证嗅探（Anthropic → OpenAI → xAI）→ 兜底 Anthropic。
• 请求预检（preflight_message_request）：对已知 token 上限的模型做上下文窗口预检，估算输入 token 超过 context window 时直接返回类型化错误ContextWindowExceeded。

需要更深模型能力映射时，可调用api::provider_diagnostics_for_model(model)拿到结构化诊断（provider、auth/base-url 环境变量、默认 base URL、是否 OpenAI 兼容线格式、是否剥离推理调参、是否保留 DeepSeek V4 推理历史、代理支持、extra_body 支持、斜杠模型 ID 是否透传等）。

模型别名速查表（内建）

未命中别名的模型名在完成 provider 路由后原样透传——这正是使用 OpenRouter slug（openai/gpt-4.1-mini）、Ollama tag（llama3.2、qwen2.5-coder:7b）、斜杠本地 ID（local/Qwen/Qwen3.6-27B-FP8）或完整 Anthropic 模型 ID 的方式。

用户还可以在任何 settings 文件中定义自定义别名（~/.claw/settings.json、.claw/settings.json或.claw/settings.local.json）：

{ "aliases": { "fast": "claude-haiku-4-5-20251213", "smart": "claude-opus-4-7", "cheap": "grok-3-mini" } }

项目级设置覆盖用户级设置；别名解析经由内建表，因此"fast": "haiku"也能生效。模型选择优先级为 CLI flag > 环境变量 > 配置 > 默认。

权限模式：默认安全，显式升级

claw的默认权限模式是workspace-write（见 rust/crates/runtime/src/permissions.rs 中PermissionMode定义）。三种模式的能力边界：

• read-only— 仅允许检查类本地工具：文件读取、glob/grep 搜索、本地 skills、状态类报告。不允许工作区变更、网络抓取/搜索工具、任意命令执行。
• workspace-write（安全默认）— 在读取基础上，允许当前工作区内的直接文件编辑工具（write/edit/notebook/config/plan-mode 更新），但仍然把网络抓取/搜索、任意 shell 执行、子 Agent 启动、REPL 子进程等全权工具挡在显式升级之后。
• danger-full-access— 放开所有已注册工具的需求，包括任意命令执行、web fetch/search、子 Agent 启动、子进程 REPL 与无限制工具访问。只有通过显式--permission-mode danger-full-access、--dangerously-skip-permissions、--skip-permissions、环境变量或配置 opt-in 才会生效。

日常用法示例：

cd rust ./target/debug/claw --model sonnet prompt "review this diff" ./target/debug/claw --permission-mode read-only prompt "summarize Cargo.toml" ./target/debug/claw --permission-mode workspace-write prompt "update README.md" ./target/debug/claw --allowedTools read,glob "inspect the runtime crate" ./target/debug/claw --cwd ../other-workspace status --output-format json

--allowedTools接受规范 snake_case 工具名（read_file、glob_search、web_fetch）及文档化别名（read、glob、Read、WebFetch）。--cwd PATH/-C PATH/--directory PATH是全局工作区覆盖 flag，在命令分发前校验，非法路径在 JSON 模式下返回类型化invalid_cwd错误（实现见 rust/crates/rusty-claude-cli/src/main.rs 的split_global_cwd_args与validate_global_cwd）。

JSON 输出与机器可读错误契约

面向 Agent/脚本的设计贯穿整个 CLI：--output-format接受text或json（大小写不敏感，归一化为小写）；CLAW_OUTPUT_FORMAT=json设置脚本默认格式，显式 flag 优先。

• 诊断类命令（doctor、status、sandbox、version）均支持--output-format json。
• 错误也走 JSON：main中的run()在 JSON 模式下把错误序列化为带type/kind/status/error_kind/action/hint/exit_code的稳定信封，并输出到stdout（机器消费者可从 stdout 第 0 字节开始解析失败）。错误种类由classify_error_kind归类，如invalid_cwd、invalid_output_format、invalid_tool_name、missing_argument、api_auth_error、api_rate_limit_error、config_parse_error、session_load_failed等，下游无需正则刮取散文文本。
• init --output-format json返回project_path、created[]、updated[]、partial[]、deferred[]、skipped[]状态数组——Agent 可以据此做条件化后续逻辑（例如只有文件真的被创建才 commit）。
• status --output-format json暴露workspace.memory_files[]（每个加载的记忆文件带path、source、origin、scope_path、outside_project、chars、contributes）与mcp_validation、hook_validation、allowed_tools等审计字段。
• version --output-format json是构建溯源探针：报告git_sha、git_sha_short、is_dirty、branch、commit_date、commit_timestamp、rustc_version、executable_path、binary_provenance。

配置文件解析顺序

运行时配置按以下顺序加载，后者覆盖前者：

1. ~/.claw.json
2. ~/.config/claw/settings.json
3. <repo>/.claw.json
4. <repo>/.claw/settings.json
5. <repo>/.claw/settings.local.json

claw config --output-format json会报告每个被发现文件的precedence_rank、wins_for_keys、shadowed_keys，自动化无需重新实现合并顺序即可知道哪个文件控制哪个生效键。

会话、技能与本地 Agent

• 会话持久化：REPL 轮次持久化在当前工作区的.claw/sessions/下。恢复用claw --resume latest，可附加 slash 命令：claw --resume latest /status /diff。
• 技能（Skills）：REPL 内/skills list或直接 CLIclaw skills --output-format json查看已装技能；skills install <path>接受包含SKILL.md的本地目录或独立 markdown 文件。skills install/uninstall与agents create是本地文件系统生命周期命令，不需要 provider 凭证。若安装成功但调用时出现 provider HTTP 错误，先把 provider 设置单独排查：跑claw doctor+ 一次性 prompt 冒烟，再重装 skill（完整清单见 docs/local-openai-compatible-providers.md）。
• 本地 Agent：claw agents create <name>在当前工作区脚手架出.claw/agents/<name>.toml，刻意保持最小，便于你在列出/调用前编辑 description、model 与 reasoning effort。

项目规则与指令文件

除了CLAUDE.md、CLAW.md、AGENTS.md、.claw/CLAUDE.md、.claude/CLAUDE.md、.claw/instructions.md等根指令文件外，claw还会按排序加载：

• <repo>/.claw/rules/（.md、.txt、.mdc）— 共享项目规则
• <repo>/.claw/rules.local/— 个人本地规则（gitignore 掉）

根指令文件优先级为CLAUDE.md→CLAW.md→AGENTS.md；发现范围限定在当前 git root（有 git 时），否则仅当前目录，避免项目外的过期父级文件悄悄混入提示词。此外默认还会导入 Cursor（.cursorrules、.cursor/rules/）、GitHub Copilot（.github/copilot-instructions.md）、Windsurf、Plandex、Crush 等常见 AI 编码工具的规则，可通过任何 settings 文件里的rulesImport控制（"auto"默认全导入、"none"只加载 Claw 自身文件、或数组如["cursor", "copilot"]选择性导入）。

MCP 与 Hook 的部分成功语义

MCP 校验：claw mcp --output-format json在兄弟条目畸形时仍能加载合法mcpServers条目，JSON 信封用total_configured、valid_count、invalid_count区分，畸形条目进入invalid_servers[]并带error_field与reason（例如missing string field command）。status镜像为mcp_validation，doctor含mcp validation检查——自动化可以在不丢失可用 MCP 服务的前提下逐个修复被拒条目。

Hook 配置：hooks.PreToolUse、hooks.PostToolUse、hooks.PostToolUseFailure既接受传统命令字符串，也接受带matcher与嵌套命令的对象风格条目：

{ "hooks": { "PreToolUse": [ "echo legacy hook", { "matcher": "Bash", "hooks": [ { "type": "command", "command": "scripts/audit-bash.sh" } ] } ] } }

matcher可选，按工具名大小写不敏感匹配，支持*通配符与逗号/管道分隔的备选；嵌套命令按配置顺序执行。传统字符串条目仍向后兼容加载，但会输出建议迁移到对象风格的弃用警告。未知 hook 事件名（如Stop、Notification）记录为 invalid 但不拒绝合法 hooks。

文档地图：继续深入的正确入口

README 末尾的文档地图是完整的导航索引，按主题归档如下：

• USAGE.md — 快速命令、认证、会话、配置、parity harness
• docs/navigation-file-context.md — 终端导航、回滚、@path文件上下文、附件与密钥安全指导
• docs/local-openai-compatible-providers.md — Ollama / llama.cpp / vLLM 设置、多 provider 定位、本地 skills 安装检查
• docs/windows-install-release.md — PowerShell 优先安装、release 工件、provider 切换、Windows/WSL 通知冒烟路径
• rust/README.md — crate 地图、CLI 表面、feature、工作区布局
• PARITY.md — Rust 移植对等性状态
• rust/MOCK_PARITY_HARNESS.md — 确定性 mock 服务 harness 细节
• ROADMAP.md — 活跃路线图与待清理工作
• docs/g004-events-reports-contract.md — Stream 2 lane event/report 契约指引
• PHILOSOPHY.md — 项目存在的原因与运营方式
• CONTRIBUTING.md、SECURITY.md、SUPPORT.md、CODE_OF_CONDUCT.md — 贡献、漏洞上报、支持与社区规范
• LICENSE — 本仓库的 MIT 许可证
• docs/container.md — 容器优先工作流
• docs/g011-acp-json-rpc-status-contract.md — ACP JSON-RPC 状态公开契约

质量验证：Mock Parity Harness 与测试套件

README 的验证路径在源码中有完整支撑。仓库包含一个确定性的 Anthropic 兼容 mock 服务与干净环境 CLI harness，用于端到端 parity 检查：

cd rust ./scripts/run_mock_parity_harness.sh

手动启动 mock 服务（用于临时 CLI 运行）：

cd rust cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0

相关工件：mock 服务本体在 rust/crates/mock-anthropic-service/，CLI harness 在 rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs，脚本化场景清单在 rust/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等。按 PARITY.md 的记载，parity 检查点还确认了路径穿越防护（symlink 跟随、../逃逸）、读写大小限制、二进制文件检测、权限模式强制与配置合并优先级等安全边界。

完整验证命令：

cd rust cargo test --workspace

生态与归属声明

Claw Code 与更广泛的 UltraWorkers 工具链在开源生态中并行构建（clawhip、oh-my-openagent、oh-my-claudecode、oh-my-codex、gajae-code等，均在各自独立仓库维护）。关于名字 "codex" 的澄清见 USAGE.md：它不指 OpenAI Codex 代码生成模型，而是指oh-my-codex（OmX，叠加在claw之上的工作流与插件层）以及.codex/遗留查找路径。

所有权/关联声明（与 README 一致）：

• 本仓库不声称拥有原始 Claude Code 源码材料的所有权。
• 本仓库与 Anthropic 无关联、未经其背书、也非其维护。

理解这个边界后，Claw Code 更值得被当作"观察 Agent 如何自主维护一个真实 Rust 工程"的实践样本：从源码构建、claw doctor健康门禁、provider 前缀路由，到 JSON 错误信封与 mock parity harness，它展示了一套围绕 Agent 自动化设计的 CLI 工程形态，值得作为研究与参考对象深入阅读。

【免费下载链接】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