ultraworkers/claw-code · 上手攻略

  • 仓库：ultraworkers/claw-code
  • 链接：https://github.com/ultraworkers/claw-code
  • 分类：AI · Agent 工具 / Rust CLI
  • 作者：Tom
  • 更新：2026-08-04

这是什么

claw-code 是 UltraWorkers 工具链中的 Rust 版 CLI Agent 运行框架（claw CLI）的 canonical 实现。它是 LazyCodex 和 Gajae-Code 的底层基础设施，提供一个本地运行的 AI 编码 Agent，支持 Anthropic API（Claude 系列）等多 Provider，可通过 REPL 交互或一次性 prompt 命令使用。

⚠️ 项目定位声明：该项目自述为"博物馆展品"（museum exhibit）——由 Agent 管理维护的 Rust 实现演示，核心工作实际在 LazyCodex 和 Gajae-Code 上推进。如果你想真正跑 AI 任务，从 LazyCodex 开始。

解决什么问题

为 Rust 生态提供一个原生编译的、跨平台（macOS/Linux/Windows）的 CLI 编码 Agent 工具，不依赖 Electron/Node.js 生态，提供持久会话、文件导航、代码审查、医生诊断等完整功能，同时保持 Rust 性能与可移植性。

快速安装

⚠️ 不要用 cargo install claw-code（crates.io 上是废弃桩，只打印"已重命名"）。正确方式是源码编译或从上游安装 agent-code。

方式一：源码编译（推荐）

# 1. 确保有 Rust 工具链
cargo --version   # 若无，访问 https://rustup.rs/ 安装

# 2. 克隆并编译
git clone https://github.com/ultraworkers/claw-code
cd claw-code/rust
cargo build --workspace

# 3. 设置 API Key（Anthropic，直接 API 访问）
export ANTHROPIC_API_KEY="sk-ant-..."

# 4. 运行健康检查
./target/debug/claw doctor

方式二：从上游安装 agent-code（非本仓库）

cargo install agent-code
# 安装后命令为 agent（非 claw）

Windows 额外注意

PowerShell 下二进制名为 claw.exe，路径使用反斜杠：

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

WSL 和 Git Bash 也支持。

核心用法

首次健康检查（必做）

cd claw-code/rust
cargo build --workspace
./target/debug/claw
# 进入 REPL 后运行：
/doctor

REPL 交互模式

# 启动交互式会话
./target/debug/claw

# 在 REPL 中使用内置命令
/ultraplan <任务>     # 分解复杂任务为结构化步骤
/teleport <符号/文件> # 快速跳转到符号或文件
/bughunter           # 扫描代码问题、反模式、潜在 Bug

单次 prompt 模式

# 直接运行一次性 prompt
./target/debug/claw prompt "summarize this repository"
./target/debug/claw -- "say hello with emojis"

# 从 stdin 读取
printf 'summarize this repository\n' | ./target/debug/claw prompt --output-format json

初始化项目

# 为仓库创建 .claw/ 配置
claw init

# JSON 模式（脚本使用）
claw init --output-format json

模型与权限控制

# 指定模型
claw --model sonnet prompt "review this diff"

# 权限模式
claw --permission-mode read-only prompt "read README"
claw --permission-mode workspace-write prompt "update README.md"

# 限制可用工具
claw --allowedTools read,glob "inspect the runtime crate"

# 切换工作目录
claw --cwd ../other-workspace status --output-format json

状态查询

# 查看当前 worker 状态（需先运行过会话）
claw state

# JSON 格式
claw state --output-format json

# doctor 诊断（JSON 格式）
claw doctor --output-format json

典型适用场景

  • Rust 生态中的 AI 编码助手：原生 Rust，不需要 Node.js 运行时
  • 多 Provider 切换：Anthropic、OpenAI、OpenAI 兼容接口（本地模型）
  • 会话持久化：通过 .claw/ 目录管理会话历史
  • 自动化工作流：JSON 输出格式适合脚本集成
  • 本地模型推理：支持 Ollama、llama.cpp、vLLM 等本地 OpenAI 兼容 Provider

坑与注意

  1. ⚠️ cargo install claw-code 是废弃桩：不要用，会装错！正确做法是 cargo install agent-code（上游）或源码编译本仓库
  2. 二进制路径：编译后二进制在 rust/target/debug/claw（macOS/Linux）或 rust\target\debug\claw.exe（Windows），不在 PATH 中，需要用完整路径或做 symlink
  3. API Key 要求：claw 需要 API Key（ANTHROPIC_API_KEY 等），Claude 订阅登录不是有效的认证方式
  4. Windows 路径：PowerShell 中使用 .\claw.exe，不要漏 .exe
  5. ACP 支持状态：项目明确说明 ACP/Zed daemon 和 JSON-RPC 入口尚未实现，claw acp serve 目前只是 discoverability alias
  6. 首次运行 doctor：建议作为第一个命令运行，验证 API key、模型权限、工具配置
  7. release vs debug：cargo build 默认 debug 模式；若嫌慢，加 --release（首次完整编译需 5-10 分钟）
  8. Python 参考实现：src/ 下的 Python 代码是参考/审计辅助，非主运行时

与同类对比

工具 语言 生态 特点
claw-code（本项目） Rust 多 Provider 原生编译、持久会话、博物馆项目
Claude Code Node.js Anthropic 官方桌面集成、成熟生态
LazyCodex Python OpenAI兼容 实际生产力工具，claw-code 的上层封装
Gajae-Code 多语言 多 Agent 联动 UltraWorkers 生态
agent-code Rust Anthropic claw-code 的上游二进制

claw-code 的 Rust 实现相较于 Node.js 版 Claude Code 提供更好的启动速度和跨平台一致性，但其上层封装（LazyCodex/Gajae-Code）才是实际干活的工具。

一句话推荐结论

claw-code 是 Rust 生态中 AI 编码 Agent 的底层基础设施——如果你想用 Rust 原生工具驱动 AI 编码任务，这是正确入口；如果你要实际干活，从 LazyCodex 开始。