## 项目概述

Claw Code 是一个由智能体自主管理和维护的 Rust 实现的 CLI 智能体工具链，定位为“博物馆展品”而非严肃的生产项目。它基于 Gajae-Code 和 LazyCodex 两个上游 harness 构建，强调无人工干预的自动化开发、验证和维护流程。仓库本身是构建源码的唯一来源，不提供预编译二进制。

## 核心功能

- 提供 `claw` CLI 命令，支持交互式会话、单次提示（prompt）、健康检查（doctor）、状态查询（status）等。
- 支持多种模型提供商，包括 Anthropic、OpenAI 兼容接口、本地模型（Ollama、llama.cpp、vLLM、mlx-lm）以及 DashScope 路由的 Qwen/Kimi 模型。
- 实现工作区会话隔离、权限策略、文件操作边界检查、Bash 命令验证等安全机制。
- 包含插件和 MCP（Model Context Protocol）生命周期管理，支持降级启动和结构化错误报告。
- 提供事件/报告契约、任务策略板、恢复配方等自动化运维基础设施。
- 支持 Windows PowerShell 和容器（Docker/Podman）工作流。

## 适用与不适用场景

**适用场景：**
- 希望体验智能体自主维护代码仓库的“博物馆展品”式项目。
- 需要研究 Rust 实现的 CLI 智能体 harness 架构。
- 需要本地或 OpenAI 兼容模型驱动的开发辅助工具。

**不适用场景：**
- 作为生产级产品直接使用（仓库明确声明非严肃生产项目）。
- 需要预编译二进制或快速安装（必须从源码构建）。
- 需要 ACP/Zed 或 JSON-RPC 服务（当前仅提供状态查询，不提供实际服务）。
- 需要完整桌面集成或剪贴板功能（当前未实现）。

## 技术架构与依赖

- 主要语言：Rust（工作区位于 `rust/`），另有 Python 参考工作区（`src/`、`tests/`）。
- 依赖上游项目：Gajae-Code（red-claw agent harness）和 LazyCodex（codex for no-brainers）。
- 核心 crate：`runtime`（权限、会话、事件、策略）、`tools`（工具 API）、`commands`（斜杠命令）、`rusty-claude-cli`（CLI 入口）、`api`（提供商适配）、`plugins`（插件生命周期）、`mock-anthropic-service`（测试用 mock 服务）。
- 构建工具：Cargo，需要 Rust 工具链。
- 许可证：MIT。

## 安装与快速开始

**注意：** 不要使用 `cargo install claw-code`（已废弃的 stub），应从源码构建。

```bash
# 1. 克隆并构建
git clone https://github.com/ultraworkers/claw-code
cd claw-code/rust
cargo build --workspace

# 2. 设置 API 密钥（Anthropic API key，非订阅）
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. 验证配置
./target/debug/claw doctor

# 4. 运行提示
./target/debug/claw prompt "say hello"

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

Windows PowerShell 用户使用 `claw.exe`，并参考 `docs/windows-install-release.md`。

## 典型使用方法

- 单次提示：`claw prompt "<指令>"`
- 交互式会话：直接运行 `claw`
- 健康检查：`claw doctor`
- 状态查询：`claw status --output-format json`
- 配置查看：`claw config env`
- 会话管理：`/session list`、`/resume latest`、`/compact` 等斜杠命令
- 本地模型路由：设置 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`，使用 `--model` 指定模型 ID
- 技能安装：`/skills install /path/to/skill`

## 配置与部署要点

- 认证：需要 API 密钥（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等），不支持 Claude 订阅登录。
- 环境变量：`OPENAI_BASE_URL`、`OLLAMA_HOST`、`DASHSCOPE_API_KEY` 等用于路由不同提供商。
- 会话存储：按工作区指纹隔离，位于 `.claw/sessions/<workspace_fingerprint>/`。
- 权限模式：支持只读、工作区写入等模式，通过 `PermissionPolicy` 强制执行。
- 容器部署：提供 `Containerfile`，支持 Docker/Podman 绑定挂载工作区。
- 预推送钩子：可配置 `.github/hooks/pre-push` 执行构建门禁。

## 限制、风险与许可证

- **限制：** 非生产项目，功能可能不完整；ACP/Zed 支持仅状态查询；桌面集成未实现；部分模型兼容性可能有限。
- **风险：** 从源码构建可能耗时；依赖上游项目变动；安全边界检查为启发式，可能不完善。
- **许可证：** MIT License（仓库根目录 `LICENSE` 文件）。

## 官方链接

- 仓库：https://github.com/ultraworkers/claw-code
- 上游：https://github.com/code-yeongyu/lazycodex 和 https://github.com/Yeachan-Heo/gajae-code
- Discord：https://discord.gg/GtjhvgjnV 和 https://discord.gg/4Rt79F7dF
- 哲学说明：https://x.com/realsigridjin/status/2039472968624185713

## 信息来源和分析时间

- 信息来源：GitHub 仓库 `ultraworkers/claw-code` 的 README、文档（`docs/` 目录）、`CONTRIBUTING.md` 等。
- 分析时间：2026-05-15（基于文档中的日期）。