Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

ultraworkers-claw-code/README.md

人可何

docs: add npx -y flag and @latest tag to zcf-claw commands

e719665d

0 commits

PreviewCode viewBlame

Claw Code 施工教程与配置指南

本文档提供 Claw Code 项目从零开始的构建、配置和使用说明。

项目简介

Claw Code 是 Claude Code CLI agent harness 的 Rust 高性能重写实现，二进制文件名为 claw-code。项目使用 Cargo workspace 组织为 9 个 crate：

Crate	职责
`api`	Provider 客户端、SSE 流式传输、请求/响应类型、认证
`commands`	斜杠命令注册表、解析、帮助文本生成
`compat-harness`	从上游 TS 源码提取工具/提示清单
`mock-anthropic-service`	确定性 `/v1/messages` mock 服务
`plugins`	插件元数据、安装/启用/禁用、工具定义、钩子
`runtime`	会话、配置、权限、MCP、系统提示词组装
`rusty-claude-cli`	主二进制 (`claw-code`) —— REPL、一次性命令、CLI 子命令
`telemetry`	会话追踪事件、遥测载荷
`tools`	内置工具规范 + 执行（bash、read、write、edit、grep 等）

Crate 依赖关系


telemetry (叶子节点)
plugins (叶子节点)
runtime → plugins, telemetry
api → runtime, telemetry
commands → plugins, runtime
tools → api, commands, plugins, runtime
compat-harness → commands, tools, runtime
rusty-claude-cli → 所有 crate (产出 claw-code 二进制)
mock-anthropic-service → api

快速开始 (一条命令)

安装并启动 (推荐)

使用 @cup2cup/zcf-claw npm 包，一条命令完成安装 + 配置 + 启动：


npx -y @cup2cup/zcf-claw@latest i --skip-prompt --all-lang zh-CN \
  --api-type api_key --api-key "your-api-key" \
  --api-url "https://open.bigmodel.cn/api/anthropic" \
  -M "glm-5.1" \
  --output-styles "nekomata-engineer" \
  --default-output-style "nekomata-engineer"

注意：npx -y 参数用于自动确认 npm 包安装，避免交互提示导致命令中断。

zcf-claw 会自动完成以下操作：

安装二进制 — 将 claw-code 安装到 ~/.claw/bin/
写入配置 — 生成 .claw/settings.json 和 .claw/settings.local.json
设置环境变量 — ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL
启动 claw-code — 自动启动并连接到指定的第三方模型

支持的第三方提供商

提供商	API URL	模型示例
智谱 (ZhiPu)	`https://open.bigmodel.cn/api/anthropic`	`glm-5.1`
OpenRouter	`https://openrouter.ai/api/v1`	`anthropic/claude-sonnet-4`
硅基流动 (SiliconFlow)	`https://api.siliconflow.cn/v1`	`deepseek-ai/DeepSeek-V3`
自定义	任何 Anthropic 兼容端点	任意模型名

zcf-claw 命令参考


# 安装 + 配置 + 启动
npx -y @cup2cup/zcf-claw@latest i --api-key "key" --api-url "url" -M "model"

# 仅安装和配置，不启动
npx -y @cup2cup/zcf-claw@latest i --no-launch --api-key "key" --api-url "url" -M "model"

# 使用已安装的配置直接启动
npx -y @cup2cup/zcf-claw@latest run --api-key "key" --api-url "url" -M "model"

# 跳过二进制安装（已有 claw-code）
npx -y @cup2cup/zcf-claw@latest i --no-install --api-key "key" --api-url "url" -M "model"

所有参数

参数	说明
`i` / `init`	初始化命令（安装 + 配置 + 启动）
`run`	直接启动
`--api-key <key>`	API 密钥
`--api-url <url>`	API 基础 URL
`--api-type <type>`	认证类型：`api_key`（默认）或 `oauth`
`-M, --model <model>`	模型名称
`--all-lang <lang>`	语言偏好（`zh-CN`、`en-US` 等）
`--output-styles <style>`	输出风格
`--default-output-style <s>`	默认输出风格（写入 settings.json）
`--skip-prompt`	跳过交互式提示
`--no-install`	跳过二进制安装
`--no-launch`	仅写配置，不启动
`--claw-bin <path>`	指定 claw-code 二进制路径
`-- <ARGS>`	传递剩余参数给 claw-code

环境要求

Rust 工具链：cargo（推荐 stable channel）
或直接安装：使用 zcf-claw 免编译安装
认证方式（二选一）：
- ANTHROPIC_API_KEY 直接 API 访问
- claw-code login OAuth 认证
可选：ANTHROPIC_BASE_URL（指向代理或本地服务时需要）

构建项目

基本构建


cd rust/
cargo build --workspace

构建完成后，二进制文件位于 rust/target/debug/claw-code。

优化构建 (Release)


cd rust/
cargo build --release -p rusty-claude-cli
# 产物位于 rust/target/release/claw-code

首次运行健康检查

构建后务必先运行 /doctor 检查环境状态：


cd rust/
./target/debug/claw-code
# 进入 REPL 后输入：
/doctor

认证配置

方式一：API Key


export ANTHROPIC_API_KEY="sk-ant-..."

方式二：OAuth 登录


cd rust/
./target/debug/claw-code login    # 登录
./target/debug/claw-code logout   # 登出

方式三：代理/本地服务认证


# Anthropic 兼容端点
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
export ANTHROPIC_AUTH_TOKEN="local-dev-token"

# OpenAI 兼容端点
export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
export OPENAI_API_KEY="local-dev-token"

模型与提供商配置

内置模型别名

别名	解析为	提供商	上下文窗口
`opus`	`claude-opus-4-6`	Anthropic	200K
`sonnet`	`claude-sonnet-4-6`	Anthropic	200K
`haiku`	`claude-haiku-4-5-20251213`	Anthropic	200K
`grok` / `grok-3`	`grok-3`	xAI	131K
`grok-mini` / `grok-3-mini`	`grok-3-mini`	xAI	131K

默认模型：claude-opus-4-6

提供商矩阵

提供商	协议	认证环境变量	Base URL 环境变量
Anthropic	Anthropic Messages API	`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / OAuth	`ANTHROPIC_BASE_URL`
xAI	OpenAI 兼容	`XAI_API_KEY`	`XAI_BASE_URL`
OpenAI 兼容	OpenAI Chat Completions	`OPENAI_API_KEY`	`OPENAI_BASE_URL`

提供商自动检测逻辑

模型名以 claude 开头 → Anthropic
模型名以 grok 开头 → xAI
否则按环境变量检查顺序：ANTHROPIC_API_KEY → OPENAI_API_KEY → XAI_API_KEY
均不匹配时默认 Anthropic

本地模型接入

Ollama


export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
unset OPENAI_API_KEY

cd rust/
./target/debug/claw-code --model "llama3.2" prompt "总结这个仓库"

OpenRouter


export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="sk-or-v1-..."

cd rust/
./target/debug/claw-code --model "openai/gpt-4.1-mini" prompt "一句话总结"

自定义模型别名

在任意配置文件（~/.claw/settings.json、.claw/settings.json、.claw/settings.local.json）中添加：


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

别名支持链式解析，如 "fast": "haiku" 也会生效。项目级配置覆盖用户级配置。

CLI 使用方式

交互式 REPL


cd rust/
./target/debug/claw-code

一次性提示 (One-shot)


./target/debug/claw-code prompt "解释这个仓库的架构"

简写模式


./target/debug/claw-code "解释 rust/crates/runtime/src/lib.rs"

指定模型与权限


./target/debug/claw-code --model sonnet prompt "审查这个 diff"
./target/debug/claw-code --permission-mode read-only prompt "总结 Cargo.toml"
./target/debug/claw-code --permission-mode workspace-write prompt "更新 README.md"
./target/debug/claw-code --allowedTools read,glob "检查 runtime crate"

权限模式：

read-only — 只读
workspace-write — 工作区写入
danger-full-access — 完全访问（默认）

JSON 输出（用于脚本集成）


./target/debug/claw-code --output-format json prompt "status"
./target/debug/claw-code --output-format json status
./target/debug/claw-code --output-format json sandbox

常用直接子命令


./target/debug/claw-code status          # 状态概览
./target/debug/claw-code sandbox         # 沙箱/容器检测
./target/debug/claw-code agents          # 列出 agent
./target/debug/claw-code mcp             # MCP 服务列表
./target/debug/claw-code skills          # 技能清单
./target/debug/claw-code doctor          # 健康检查
./target/debug/claw-code system-prompt --cwd .. --date 2026-04-08  # 查看系统提示词

REPL 内斜杠命令

类别	命令
会话/状态	`/help`, `/status`, `/sandbox`, `/cost`, `/resume`, `/session`, `/version`, `/usage`
工作区/Git	`/compact`, `/clear`, `/config`, `/memory`, `/init`, `/diff`, `/commit`, `/pr`, `/branch`
调试/诊断	`/mcp`, `/agents`, `/skills`, `/doctor`, `/tasks`, `/context`
插件管理	`/plugin [list\|install\|enable\|disable\|uninstall\|update]`
子 Agent	`/subagent [list\|steer\|kill]`

会话管理

会话以 .jsonl 格式持久化在 .claw/sessions/ 目录下。


# 恢复最近会话
./target/debug/claw-code --resume latest

# 恢复会话并执行命令
./target/debug/claw-code --resume latest /status /diff

配置文件体系

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

~/.claw.json
~/.config/claw/settings.json
<仓库>/.claw.json
<仓库>/.claw/settings.json
<仓库>/.claw/settings.local.json

环境变量覆盖：

CLAW_CONFIG_HOME — 自定义配置根目录
CLAUDE_CONFIG_DIR — 兼容旧路径

代理 (Proxy) 配置

claw-code 支持标准代理环境变量（大小写均可）：


export HTTPS_PROXY="http://proxy.example.com:3128"
export HTTP_PROXY="http://proxy.example.com:3128"
export NO_PROXY="localhost,127.0.0.1,.example.com"

注意事项：

HTTPS_PROXY 用于 https:// 请求，HTTP_PROXY 用于 http:// 请求
NO_PROXY 接受逗号分隔的主机后缀列表
空值视为未设置（不会启用代理）
代理 URL 解析失败时回退到直连

容器化工作流

构建镜像


# Docker
docker build -t claw-code-dev -f Containerfile .

# Podman
podman build -t claw-code-dev -f Containerfile .

在容器中运行测试


# Docker
docker run --rm -it \
  -v "$PWD":/workspace \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev \
  cargo test --workspace

# Podman (注意 :Z 后缀用于 SELinux)
podman run --rm -it \
  -v "$PWD":/workspace:Z \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev \
  cargo test --workspace

挂载多个仓库


docker run --rm -it \
  -v "$PWD":/workspace \
  -v "$HOME/src/other-repo":/repo \
  -e CARGO_TARGET_DIR=/tmp/claw-target \
  -w /workspace/rust \
  claw-code-dev

# 在容器内：
cargo run -p rusty-claude-cli -- prompt "summarize /repo"

CARGO_TARGET_DIR=/tmp/claw-target 避免在宿主仓库中留下容器所有的构建产物。

测试与验证

完整验证三件套（CI 同款）


cd rust/

# 1. 格式检查
cargo fmt --all --check

# 2. Clippy lint（workspace 强制 clippy pedantic + 禁止 unsafe）
cargo clippy --workspace --all-targets

# 3. 运行全部测试（约 866 个测试函数，分布在 71 个文件中）
cargo test --workspace

运行特定测试


# 按名称运行单个测试
cargo test -p runtime <test_name>

# 运行某个 crate 的所有测试
cargo test -p api
cargo test -p commands
cargo test -p tools

# 运行单个文件的测试（通过过滤名称）
cargo test -p rusty-claude-cli render_diff_report -- --nocapture

测试结构说明

单元测试：#[cfg(test)] mod tests 块位于各源文件内
集成测试：crates/api/tests/、crates/runtime/tests/、crates/rusty-claude-cli/tests/
环境变量锁定测试：涉及环境变量的测试使用全局 Mutex 锁（test_env_lock 或 env_lock）避免跨测试干扰
需要网络的测试：crates/api/tests/ 下的集成测试需要 mock-anthropic-service 或真实网络

CI/CD 流水线

CI 触发条件

Push 到 main、gaebal/**、omx-issue-* 分支
针对上述分支的 Pull Request
手动触发 (workflow_dispatch)

CI 检查项

Job	说明
`doc-source-of-truth`	检查文档和元数据中的过期品牌/引用
`cargo fmt`	代码格式检查
`cargo test --workspace`	全量测试
`cargo clippy --workspace`	Lint 检查

Release 构建

当推送 v* 格式的 tag 时触发，构建平台：

linux-x64 (ubuntu-latest)
macos-arm64 (macos-14)

产物上传至 GitHub Release。

Mock 对等性测试

Workspace 包含确定性 Anthropic 兼容 mock 服务，用于端到端对等性验证。


cd rust/

# 运行脚本化对等性测试
./scripts/run_mock_parity_harness.sh

# 手动启动 mock 服务
cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0

覆盖场景：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。

故障排查

首先运行 `/doctor`


cd rust/
./target/debug/claw-code
/doctor

/doctor 是内置的预诊断工具，会检查环境、配置、认证状态等。

常见问题

问题	解决方案
`cargo test` 某些测试在并行执行时失败	尝试单独运行：`cargo test -p <crate> <test_name>`
代理不生效	检查 `HTTPS_PROXY` 是否为空字符串（空字符串视为未设置）
OAuth 登录失败	使用 API Key 方式：`export ANTHROPIC_API_KEY="sk-ant-..."`
找不到模型	确认模型别名拼写，或直接使用完整模型 ID
JSON 输出格式异常	确保使用 `--output-format json` 标志
第三方模型连接失败	使用 `zcf-claw --no-launch` 检查配置，确认 API URL 和 Key 正确

查看完整帮助


cd rust/
cargo run -p rusty-claude-cli -- --help

生态系统

Claw Code 与 UltraWorkers 工具链紧密协作：

clawhip — 事件与通知路由器
oh-my-openagent — 多 Agent 协调层
oh-my-claudecode — Claude Code 增强工具
oh-my-codex — 工作流与插件层 (OmX)

声明

本仓库不声明对原始 Claude Code 源材料的所有权
本仓库不隶属于、不由 Anthropic 认可或维护

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111