Claude Code CLI 源码拆解：Node.js 子进程模型与 ACP 协议设计

三角对照：OpenClaw Gateway → Hermes 单循环 → Claude Code 子进程

TL;DR

Claude Code 是 Anthropic 官方推出的 CLI Agent，npm 全局安装后通过 claude 命令运行。它与 OpenClaw 和 Hermes Agent 解决同一个问题——让 AI 自主执行编程任务——但架构哲学走出了第三条路：子进程隔离模型。 OpenClaw 用 Gateway hub-and-spoke 把 25+ 通道和 14+ 子 Agent 串在一起；Hermes 用 Python 单循环 run_conversation() 在进程内完成一切；Claude Code 则把 Agent Runtime、MCP Server、子 Agent 全部跑在独立子进程里，通过 Node.js child_process.spawn() 和 ACP 协议（JSON-RPC over stdio）通信。 本文从源码级拆解 Claude Code 的子进程架构、ACP 协议实现、Session 模型、多 Agent 协作和安全机制，并在每个维度与 OpenClaw CLI Runner 和 Hermes delegate_task 做三角对照。

一、先看全貌：Claude Code 的进程模型

1.1 启动链路

用户执行 claude 命令
  → npm global bin: claude.cmd / claude
    → Node.js 主进程启动
      → 加载 CLI 参数（--print / --model / --allowedTools…）
        → 初始化 Session（新会话或 --continue/--resume）
          → 进入 Agent Loop

Claude Code 本身是一个 Node.js CLI 应用（npm 包 @anthropic-ai/claude-code），没有独立的 Gateway 进程。主进程承担三个角色： | 角色 | 说明 | |------|------| | CLI 入口 | 解析命令行参数、环境变量、Settings 文件 | | Agent Runtime | 执行 Agent Loop：组装 System Prompt → 模型调用 → 工具分发 | | 进程管理器 | 通过 child_process.spawn() 管理 MCP Server、子 Agent、浏览器 Daemon |

1.2 与 OpenClaw / Hermes 的第一层差异

child_process.spawn()    → 创建 MCP Server 子进程（stdio pipe 通信）
child_process.fork()     → 创建子 Agent（IPC 通道 + 独立 V8 实例）
child_process.exec()     → 执行一次性 Shell 命令（Bash 工具）
child_process.execFile() → 执行指定二进制文件

spawn vs fork 的区别： - spawn：启动任意可执行文件，通过 stdin/stdout/stderr pipe 通信。用于 MCP Server（外部进程）。 - fork：启动新的 Node.js 进程，带 IPC 通道（process.send() / process.on('message')）。用于子 Agent（同语言、需要结构化消息）。

2.2 实际运行的进程树

一个典型 Claude Code 会话启动后的进程树：

claude (主进程, PID 12345)
  ├── node mcp-server-filesystem (MCP Server, PID 12346)
  ├── node mcp-server-github (MCP Server, PID 12347)
  ├── chrome-headless-shell (浏览器 Daemon, PID 12348)
  ├── claude --print (子 Agent "reviewer", PID 12349)
  └── claude --print (子 Agent "tester", PID 12350)

每个子进程完全独立——独立的内存空间、独立的 V8 实例、独立的错误边界。一个 MCP Server 崩溃不会影响主 Agent Loop。

2.3 三角对照：进程隔离哲学

编辑器（ACP Client）           Agent（ACP Server）
     │                              │
     │  session/new ───────────────→│  创建会话
     │  session/load ──────────────→│  恢复会话
     │  session/set_mode ──────────→│  切换模式
     │                              │
     │←─ terminal/create ──────────│  请求执行命令
     │←─ terminal/wait_for_exit ───│  等待命令完成
     │←─ session/request_permission│  请求用户授权
     │←─ session/update ──────────│  流式输出进度

关键理解：Agent 是 Server，编辑器是 Client。Agent 主动向编辑器请求权限、创建终端、推送更新——不是编辑器"调用"Agent，而是 Agent"驱动"编辑器。

3.3 Claude Code 的 ACP 实现

Claude Code 通过 --acp 模式启动为 ACP Server：

# 以 ACP Server 模式启动，通过 stdio 与编辑器通信
claude --acp

通信方式：JSON-RPC over stdio——Agent 进程的 stdin/stdout 承载所有协议消息。这与 LSP 完全一致，不需要网络端口、不需要 HTTP Server。

3.4 ACP vs MCP：两个协议的分工

~/.claude/projects/
  └── a1b2c3d4/          # 项目 hash
      ├── sessions/
      │   ├── abc-123.json  # 会话 1
      │   └── def-456.json  # 会话 2
      └── memory/           # Auto-memory（≤25KB / ≤200行）

每个 Session JSON 包含完整对话历史、工具调用记录、token 用量。恢复机制：

claude --continue           # 恢复当前目录最近会话
claude --resume <session-id> # 恢复指定会话
claude -c                   # 简写，等同 --continue

4.2 Auto-Memory：Agent 自管理记忆

Claude Code 有一个独特的自动记忆机制：Agent 在会话中自主判断哪些信息值得跨会话保留，写入 ~/.claude/projects/<hash>/memory/。限制 25KB / 200 行——这意味着 Agent 必须做选择性记忆，不是全量日志。 这与 Hermes 的 Hindsight 自动 retain 理念类似，但实现方式完全不同：Claude Code 靠 Agent 自己判断，Hermes 靠独立的记忆引擎（SQL 模板 + pgvector）。

4.3 三角对照：Session 与记忆

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Security-focused code review
model: opus
tools: [Read, Bash]
---
你是一个资深安全工程师。审查代码中的注入漏洞、认证缺陷、密钥泄露。

使用时在对话中 @security-reviewer review the auth module。 方式 2：动态 CLI flag

claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' -p 'Use @reviewer to check auth.py'

方式 3：Task Tool 自动 spawn Agent 在 Agent Loop 中自主判断任务复杂度，需要并行处理时通过 Task Tool 创建子 Agent——与 OpenClaw 的 sessions_spawn 理念一致。

5.2 子 Agent 的进程模型

每个子 Agent 通过 child_process.fork() 或 child_process.spawn() 启动——完全独立的 Node.js 进程。这意味着： - 独立的内存空间（不会污染主 Agent 的上下文） - 独立的模型调用（可以指定不同 model） - 独立的工具权限（可以 restrict 工具列表） - 崩溃不传播（子 Agent OOM 不影响主 Agent）

5.3 三角对照：多 Agent 实现

default       → 标准模式：危险操作弹确认
acceptEdits   → 自动接受编辑，其他弹确认
plan          → 只读规划模式，不允许写
auto          → 自动批准（谨慎使用）
bypassPermissions → 完全跳过权限检查

通过 Shift+Tab 在 TUI 中实时切换，或通过 --permission-mode CLI 参数指定。

6.2 工具白名单/黑名单

# 只允许读文件和 git 操作
claude --allowedTools "Read,Bash(git *)" -p "review the code"
# 禁止读写 .env 文件
claude --disallowedTools "Read(.env),Write(.env)" -p "refactor"

工具名支持 glob 模式：Bash(npm run lint:*) 只允许特定 npm 脚本。

6.3 Hooks 系统：8 种拦截点

Hooks 是 Claude Code 安全模型的核心创新——在 8 个关键时刻执行自定义脚本： | Hook | 触发时机 | 典型用途 | |------|---------|---------| | UserPromptSubmit | 用户发送消息前 | 输入验证 | | PreToolUse | 工具执行前 | 拦截危险命令（exit 2 = 阻止） | | PostToolUse | 工具执行后 | 自动格式化代码 | | Notification | 权限请求时 | 桌面通知 | | Stop | Agent 响应完成 | 完成日志 | | SubagentStop | 子 Agent 完成 | 编排逻辑 | | PreCompact | 上下文压缩前 | 备份会话 | | SessionStart | 会话开始时 | 加载开发环境 | 安全 Hook 示例：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force'; then echo 'Blocked!' && exit 2; fi"
      }]
    }]
  }
}

6.4 三角对照：安全模型

优先级从高到低：
1. CLI flags               → 覆盖一切
2. .claude/settings.local.json  → 个人项目配置（gitignored）
3. .claude/settings.json        → 团队共享项目配置（git-tracked）
4. ~/.claude/settings.json      → 全局用户配置

对应的 Context 文件也分三层：

~/.claude/CLAUDE.md              → 全局（所有项目生效）
./CLAUDE.md                      → 项目级（git-tracked）
.claude/CLAUDE.local.md          → 个人项目覆盖（gitignored）

设计理念：团队共享 settings.json + CLAUDE.md，个人通过 .local 文件覆盖，不会被 git 追踪导致冲突。

三角对照：配置管理

本文由 admin 原创，转载请注明出处。