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-codeClaw Code 是一个以 Rust 实现的clawCLI Agent Harness 公开仓库官方定位是由 Agent 托管维护的博物馆级展品agent-managed museum exhibitharness 负责规划、执行、验证、打标签并持续维护这个工件。本文以仓库根目录 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 shapeREADME 给出了仓库顶层结构与仓库实际文件一致rust/— 规范 Rust 工作区与clawCLI 二进制9 个 crateapi、commands、compat-harness、mock-anthropic-service、plugins、runtime、rusty-claude-cli、telemetry、tools详见 rust/README.mdUSAGE.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.mdWindows 用户直接跳到 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。快速开始五步跑通 clawREADME 的 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 keyAnthropic API key不是 Claude 订阅 export ANTHROPIC_API_KEYsk-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 keyANTHROPIC_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 项检查check_auth_health— 认证凭证check_base_url_health— base URLcheck_config_health— 配置文件check_mcp_validation_health— MCP 服务配置check_hook_validation_health— hook 配置check_install_source_health— 安装来源check_workspace_health— 工作区check_memory_health— 项目记忆文件check_boot_preflight_health— 启动预检check_sandbox_health— sandbox 能力check_permission_health— 权限模式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 问题按以下顺序解决先装 Rust— 从 rustup 安装器下载并运行完成后关闭并重开终端。验证 Rust 在 PATH 上cargo --version若失败重开终端或按安装器输出配置 PATH 后重试。克隆并构建PowerShell、Git Bash、WSL 均可用git clone https://gitcode.com/gh_mirrors/claudeco/claw-code cd claw-code/rust cargo build --workspace运行注意.exe后缀与反斜杠路径$env:ANTHROPIC_API_KEY sk-ant-... .\target\debug\claw.exe prompt say helloGit 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/LinuxWindowsDebug默认编译更快rust/target/debug/clawrust\target\debug\claw.exeRelease--release运行更快rust/target/release/clawrust\target\release\claw.exe直接验证构建产物# macOS/Linuxdebug 构建 ./rust/target/debug/claw --help ./rust/target/debug/claw doctor # Windows PowerShelldebug 构建 .\rust\target\debug\claw.exe --help .\rust\target\debug\claw.exe doctorPowerShell 下还提供一组不需要真实凭证的冒烟命令$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/Linuxln -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 profilebash/zshexport 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 来源凭证形态环境变量HTTP 头典型来源sk-ant-*API keyANTHROPIC_API_KEYx-api-key: sk-ant-...Anthropic 控制台OAuth 访问令牌不透明ANTHROPIC_AUTH_TOKENAuthorization: Bearer ...Anthropic 兼容代理或 OAuth 流程OpenRouter keysk-or-v1-*OPENAI_API_KEYOPENAI_BASE_URLhttps://openrouter.ai/api/v1Authorization: Bearer ...OpenRouterOllama 本地实例OLLAMA_HOST无认证头本地http://127.0.0.1:11434为什么这很重要如果把sk-ant-*粘贴进ANTHROPIC_AUTH_TOKENAnthropic 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-miniOpenAI 兼容 / OpenRouter / Ollama、--model grokxAI或--model qwen-plusDashScope前缀路由会自动选择正确的后端——无需清空已有的其他凭证。模型别名与 Provider 路由机制README 提到--model sonnet这类别名。其实现位于 rust/crates/api/src/providers/mod.rs内建别名表MODEL_REGISTRYresolve_model_aliasopus→claude-opus-4-7、sonnet→claude-sonnet-4-6、haiku→claude-haiku-4-5-20251213以及grok/grok-mini/grok-2xAI、kimiDashScope。Provider 元数据表metadata_for_modelclaude*/anthropic/→ Anthropicgrok*→ xAIopenai/、local/、gpt-→ OpenAI 兼容qwen/、qwen-、kimi/、kimi-→ DashScope compatible-mode。检测顺序detect_provider_kindOLLAMA_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最大输出 tokens上下文窗口opusclaude-opus-4-7Anthropic32 000200 000sonnetclaude-sonnet-4-6Anthropic64 000200 000haikuclaude-haiku-4-5-20251213Anthropic64 000200 000grok/grok-3grok-3xAI64 000131 072grok-mini/grok-3-minigrok-3-minixAI64 000131 072kimikimi-k2.5DashScope16 384256 000qwen-max/qwen-plus同名DashScope8 192131 072gpt-4.1系列同名OpenAI 兼容32 7681 047 576未命中别名的模型名在完成 provider 路由后原样透传——这正是使用 OpenRouter slugopenai/gpt-4.1-mini、Ollama tagllama3.2、qwen2.5-coder:7b、斜杠本地 IDlocal/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_FORMATjson设置脚本默认格式显式 flag 优先。诊断类命令doctor、status、sandbox、version均支持--output-format json。错误也走 JSONmain中的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。配置文件解析顺序运行时配置按以下顺序加载后者覆盖前者~/.claw.json~/.config/claw/settings.jsonrepo/.claw.jsonrepo/.claw/settings.jsonrepo/.claw/settings.local.jsonclaw config --output-format json会报告每个被发现文件的precedence_rank、wins_for_keys、shadowed_keys自动化无需重新实现合并顺序即可知道哪个文件控制哪个生效键。会话、技能与本地 Agent会话持久化REPL 轮次持久化在当前工作区的.claw/sessions/下。恢复用claw --resume latest可附加 slash 命令claw --resume latest /status /diff。技能SkillsREPL 内/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。本地 Agentclaw 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_validationdoctor含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 harnessdocs/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-codexOmX叠加在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考