你的第一次 claw 会话

当你运行 claw prompt "说你好"，从终端到 Claude API，发生了什么？

claw-code：把 Claude 变成真正的命令行 Agent

claw-code 是一个用 Rust 构建的 AI 编码 Agent CLI。你用它和 Claude 对话，但不只是聊天 —— claw 给 Claude 提供了真实操作代码库的能力：读写文件、执行终端命令、搜索代码、管理 Git 提交。

它的哲学来自 PHILOSOPHY.md 里的一句话："人类设置方向，Claw 执行劳动"。你描述想要什么，claw 负责把它做出来。

🦀

为什么用 Rust 重写？

Rust 带来的不只是性能，更重要的是内存安全和并发安全。在 AI Agent 这种长时间运行、处理用户文件的场景里，内存泄漏或竞争条件会导致数据丢失。Rust 的编译器在编译时就排除了这类问题。

从终端命令到 Claude 回复 —— 完整链路

⌨️

终端 CLI

⚙️

Runtime

🌐

API Layer

🔧

Tools

点击"下一步"追踪一次 prompt 请求

Step 0 / 8

第一行 Rust 代码：CLI 入口

这是 claw-code 的主入口，也是理解系统的第一块拼图：

rust/crates/rusty-claude-cli/src/main.rs


const DEFAULT_MODEL: &str =
  "claude-opus-4-6";

enum ModelSource {
  Flag,    // --model 参数
  Env,     // ANTHROPIC_MODEL 环境变量
  Config,  // .claw.json 配置文件
  Default, // 内置默认值
}

白话翻译

DEFAULT_MODEL 是内置的"兜底"模型，如果你没有任何配置就用这个

ModelSource 枚举记录模型名称是从哪里来的，方便调试"为什么用了这个模型"

Flag 优先级最高：--model 参数直接指定，覆盖一切

Env 次之：设置 ANTHROPIC_MODEL 环境变量可以全局指定

Config 再次：.claw.json 里的 model 字段，项目级配置

Default 兜底：都没有时用 claude-opus-4-6

测验：快速上手

你刚编译好了 claw-code（cargo build --workspace），下一步应该做什么？

你设置了 ANTHROPIC_MODEL=claude-haiku-3，但运行时加了 --model claude-opus-4-6。实际使用哪个模型？

02

Rust Workspace 架构

10 个 Crate，各司其职 —— 为什么这样设计？

把大项目拆成小模块：Cargo Workspace

claw-code 不是一个单体的 main.rs，而是由 10 个独立的 Crate（模块）组成，每个模块只负责一件事，通过明确定义的接口与其他模块交互。

这种设计的好处：修改 API 层不影响工具层；测试权限系统不需要启动完整 CLI；将来想替换 Mock 服务只需换一个 Crate。

用户交互层

⌨️ rusty-claude-cli

核心能力层

⚙️ runtime

🌐 api

🔧 tools

扩展与测试层

🔌 plugins

🧪 mock-anthropic-service

✅ compat-harness

点击任意 Crate 查看详情

Runtime Crate：系统大脑

runtime crate 是整个项目最复杂的部分，包含 40+ 子模块。这是它里面最重要的几个：

💾

session.rs

对话历史的持久化存储。每次会话保存到磁盘，支持 --resume 继续上次未完成的任务。

🛡️

permission_enforcer.rs

权限策略执行引擎。检查每个工具调用是否被允许，防止 AI 越权操作。

🗜️

summary_compression.rs

当对话历史太长时，智能压缩历史内容，保留关键信息，节省 Token 开销。

🌐

mcp.rs / mcp_client.rs

Model Context Protocol 客户端，连接外部 MCP 服务器，扩展 AI 的工具能力。

🔄

conversation.rs

核心对话循环：接收用户输入 → 调用 API → 处理工具调用 → 返回结果 → 循环。

🌿

branch_lock.rs

防止多个 claw 会话同时修改同一个 git 分支，避免代码冲突。

Workspace 的组织方式

rust/Cargo.toml（工作区定义）


[workspace]
members = [
  "crates/rusty-claude-cli",
  "crates/runtime",
  "crates/api",
  "crates/tools",
  "crates/commands",
  "crates/plugins",
  "crates/mock-anthropic-service",
]

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }

白话翻译

[workspace] 告诉 Cargo：这些目录都是同一个工程的成员

members 列表：每个子目录都有自己的 Cargo.toml 和代码

cargo build --workspace 一条命令编译所有成员，共享构建缓存

[workspace.dependencies] 统一管理公共依赖版本，所有 Crate 用同一版本的 serde，避免版本冲突

这种设计让你可以 cargo test -p runtime 只测试 runtime，不需要重新编译整个项目

测验：Workspace 理解

claw-code 里有一个 mock-anthropic-service crate，它的主要用途是？

03

会话与状态管理

AI 如何"记住"你们的对话？claw 的会话持久化设计

为什么 AI 会话需要"存档"？

如果你花了 2 小时和 AI 一起调试一个复杂 Bug，中途电脑关机了 —— 没有会话持久化，你就得从头开始。

claw-code 的 Session 系统把每一轮对话（消息、工具调用、工具结果）持久化到磁盘。用 --resume 标志，你可以回到上次离开的地方，就像保存游戏后继续。

💡

会话 ID 是什么

每次新会话，claw 生成一个唯一 ID（比如 abc123def456）。这个 ID 是你的"存档槽"。claw --resume latest 找最近的存档，claw --resume <id> 找特定存档。会话数据保存在 ~/.claw/sessions/ 目录。

恢复中断的会话：真实场景演示

0 / 6 messages

当对话太长时：上下文压缩

每次 API 调用都要发送完整的对话历史，Token 费用随对话长度线性增长。claw-code 有一个 summary_compression 模块自动处理这个问题。

runtime/src/summary_compression.rs


pub fn should_compact(
  session: &Session,
  config: &CompactionConfig,
) -> bool {
  let tokens = estimate_session_tokens(session);
  tokens > config.compaction_threshold
}

pub async fn compact_session(
  session: &mut Session,
  api: &dyn ApiClient,
) -> Result<CompactionResult> {
  // 调用 LLM 生成历史摘要
  // 用摘要替换旧消息
}

白话翻译

should_compact：一个检查函数，回答"现在是否需要压缩？"

estimate_session_tokens：估算当前会话用了多少 Token

如果超过 compaction_threshold（压缩阈值），返回 true，触发压缩

compact_session：真正的压缩逻辑，用 LLM 把早期对话总结成简短摘要

压缩后把摘要替换掉那些占 Token 的详细对话，腾出空间继续工作

测验：会话管理

claw 的上下文压缩功能最需要注意的潜在问题是？

04

工具系统与权限

AI 可以做什么、不能做什么 —— 权限引擎的设计哲学

Claude 能调用哪些工具？

claw-code 给 Claude 提供了一套标准工具集（通过 mvp_tool_specs 定义），每个工具有精确的输入输出类型。Claude 不是自由生成代码执行 —— 而是选择工具、提供参数，由 claw 的工具引擎执行。

bash 在沙箱里运行 Shell 命令。受 permission_enforcer 控制，某些命令需要用户确认。

read_file 读取文件内容，支持行范围参数（start_line, end_line）节省 Token。

write_file 写入或创建文件。写操作会记录到审计日志，支持回滚。

search_files 在代码库里搜索模式（类似 grep），返回文件名和匹配行。

list_directory 列出目录结构，帮助 Claude 快速了解项目布局。

git_* 一系列 Git 工具：status、diff、add、commit、push。每个操作都有独立权限控制。

权限策略：三种模式

claw-code 的 PermissionPolicy 控制 AI 的自主程度，可以在安全和便捷之间调节：

Auto（全自动）

AI 可以自主执行所有被授权的工具调用，无需每次确认。适合你信任的任务，比如"自动化测试运行"或"格式化所有文件"。风险：如果任务描述不精确，AI 可能做出你不期望的修改。

不同模式适合不同任务类型，可以在对话中随时切换。

权限检查的实际代码

runtime/src/permission_enforcer.rs


pub fn check_permission(
  tool: &ToolCall,
  policy: &PermissionPolicy,
) -> PermissionResult {
  match policy {
    PermissionPolicy::Readonly => {
      if tool.is_write_op() {
        PermissionResult::Denied
      } else {
        PermissionResult::Allowed
      }
    }
    PermissionPolicy::AskFirst if
      tool.is_destructive() =>
        PermissionResult::NeedsConfirmation,
    _ => PermissionResult::Allowed,
  }
}

白话翻译

check_permission 在每次工具调用前运行，决定是允许、拒绝还是先问用户

match 是 Rust 的模式匹配，根据权限模式进入不同分支

Readonly 模式：如果是写操作（is_write_op），直接 Denied，否则 Allowed

AskFirst 模式：如果是破坏性操作（is_destructive，比如删除文件），返回 NeedsConfirmation

_ 是"其他所有情况"，Auto 模式会走到这里，直接 Allowed

测验：权限策略选择

你想让 AI 帮你审查一段代码，可以自动读取文件和分析，但修改代码前必须经过你确认。应该用哪个权限模式？

05

人机协作哲学

Discord 是人机接口，代码只是副产品

真正的创新不是代码，而是协作模式

claw-code 的 PHILOSOPHY.md 有一段话让人印象深刻：

"如果你只看这个仓库里生成的文件，你看的是错误的层次。Python 重写是副产品，Rust 重写也是副产品。真正值得研究的是产生它们的系统：一个以人类提供方向、自主 Agent 执行工作为核心的协调循环。"

这不只是一个 CLI 工具 —— 它是一种工作模式的宣言：人类通过自然语言设置方向，AI Agent 并行执行，人类从"写代码"变成"指挥代码被写出来"。

claw-code 生态系统的三个层次

PHILOSOPHY.md 描述了一个完整的三部分协调系统，claw-code 只是其中的执行层：

📐

OmX（oh-my-codex）：工作流层

把简短的自然语言指令转化为结构化的执行协议：规划关键词、执行模式、持久化验证循环、并行多 Agent 工作流。

🔔

clawhip：通知路由层

监控 git commits、tmux 会话、GitHub issues、Agent 生命周期事件。把监控和通知推到 Agent 的上下文窗口之外，让 Agent 专注于实现。

🤝

OmO（oh-my-openagent）：多 Agent 协调层

处理 Architect（架构师）、Executor（执行者）、Reviewer（审查者）多个 Agent 角色之间的规划、交接和分歧解决。

📱

Discord 作为人机接口

这个系统真正的人机接口是 Discord 频道，不是终端。你从手机上打一句话，走开，睡觉，去做其他事。Claw 读取指令，拆解任务，分配角色，写代码，运行测试，解决失败，在代码通过后推送。你回来看结果。

把这些知识变成你的工作方式

🎯

精确描述，不猜测

告诉 claw 确切的文件路径、期望的输入输出、成功标准。越精确，AI 越少猜测，结果越好。

🔄

会话恢复，不重复

长任务使用 --resume，保留上下文，不需要重新解释背景。claw 会记住上次学到的项目知识。

🛡️

AskFirst 作为默认

对新项目或不熟悉的操作，用 AskFirst 模式。理解 AI 意图后，在你信任的范围内切换到 Auto。

🧪

Mock 先行，真实其次

用 mock-anthropic-service 写测试，不依赖真实 API，速度快且可复现。调试确认后再用真实 API。

综合测验：终极挑战

根据 claw-code 的设计哲学，作为使用者，你的核心职责是什么？

claw-code 里的 compat-harness crate 的主要价值是什么？

🦀

课程完成！

你现在理解了 claw-code 的完整架构：Cargo Workspace 模块设计、Runtime/API/Tools 三层分工、会话持久化与上下文压缩、权限引擎的三种模式，以及"人类设置方向、AI 执行劳动"的核心哲学。这些知识让你能更有效地使用和定制这套工具。