乐于分享
好东西不私藏

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

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 的第一层差异

维度
OpenClaw
Hermes Agent
Claude Code
语言
TypeScript (Node.js)
Python
TypeScript (Node.js)
架构模型
Gateway hub-and-spoke
单进程直接循环
主进程 + 子进程树
入口
Gateway 进程绑定端口
run_conversation()claude
 CLI 命令
多会话
Lane Queue 原生并发
单会话,多次调用
单会话,可 resume
通道
25+ 内置(Telegram/Discord…)
Telegram + WebUI
终端 TUI + ACP

关键差异:OpenClaw 的 Gateway 是持久化服务,7×24 运行;Claude Code 和 Hermes 都是一次性会话——执行完退出,无需守护进程。


二、子进程模型:为什么 Claude Code 不用单循环?

2.1 Node.js child_process 四大原语

Claude Code 的进程管理全部建立在 Node.js child_process 模块之上:

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 三角对照:进程隔离哲学

OpenClaw CLI Runner
Hermes delegate_task
Claude Code
子任务执行方式
独立子进程,ACP 协议
独立子进程,Hermes 内部调度
独立子进程,ACP 协议
进程隔离
✅ 完全隔离
✅ 完全隔离
✅ 完全隔离
通信协议
ACP (JSON-RPC over stdio)
Hermes 内部 RPC
ACP (JSON-RPC over stdio)
子进程管理
Gateway 负责 spawn + 生命周期
delegate_task
 工具负责
主进程直接 spawn
崩溃恢复
Gateway 检测 + 重启
超时 + 重试
父进程捕获 exit code

共同点:三者都选择了子进程隔离执行高风险任务——没有人让 Agent 在同一个进程里跑 rm -rf。

差异:OpenClaw 把子进程管理抽象为 Gateway 层,Hermes 抽象为工具层,Claude Code 直接在 CLI 层 spawn——抽象层级逐级下移。


三、ACP 协议:Agent 与 IDE 的标准通信层

3.1 ACP 是什么

ACP(Agent Client Protocol)由 Zed Industries 主导,2025 年 9 月发布。它是一个开放标准,定义了编辑器(Client)与 AI Agent(Server)之间的 JSON-RPC 通信规范

理解 ACP 最好的类比是LSP(Language Server Protocol)——LSP 让所有编辑器都能接入任何语言的智能提示,ACP 让所有编辑器都能接入任何 AI Agent。

3.2 ACP 角色:Client / Server(命名与直觉相反)

编辑器(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:两个协议的分工

MCP (Model Context Protocol)
ACP (Agent Client Protocol)
解决什么问题
Model ↔ Tool 通信
Editor ↔ Agent 通信
谁定义的
Anthropic
Zed Industries
谁调用谁
Agent 调用 MCP Server
Editor 连接 Agent(ACP Server)
通信方向
Agent → MCP Server(单向)
Editor ↔ Agent(双向)
类比
工具注册表
IDE 插件协议

ACP 和 MCP 在协议层面相互独立——ACP Agent 可以同时是 MCP Host(调用 MCP 工具),但 ACP 协议本身不感知 MCP。

3.5 三角对照:通信协议设计

OpenClaw
Hermes Agent
Claude Code
主通信协议
ACP(CLI Runner)+ Channel Plugin
无标准协议,直接工具调用
ACP(原生支持)
MCP 支持
✅ MCP Client
❌ 无内置
✅ MCP Client
协议标准化
高(ACP + MCP 双协议)
低(自研工具注册表)
高(ACP + MCP 双协议)
编辑器集成
ACP 可接入 Zed/VS Code
无标准编辑器集成
ACP 可接入 Zed/VS Code

Claude Code 和 OpenClaw 都选了 ACP + MCP 双协议——ACP 负责 Agent ↔ 编辑器通信,MCP 负责 Agent ↔ 工具通信。Hermes 走自研路线,所有通信都在同一个 Python 进程内通过 ToolRegistry 完成。


四、Session 模型:JSON 文件 vs 数据库

4.1 Claude Code 的 Session 持久化

Claude Code 的会话以JSON 文件形式持久化在 ~/.claude/projects// 下:

~/.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//memory/。限制 25KB / 200 行——这意味着 Agent 必须做选择性记忆,不是全量日志。

这与 Hermes 的 Hindsight 自动 retain 理念类似,但实现方式完全不同:Claude Code 靠 Agent 自己判断,Hermes 靠独立的记忆引擎(SQL 模板 + pgvector)。

4.3 三角对照:Session 与记忆

OpenClaw
Hermes Agent
Claude Code
Session 存储
JSONL 按行追加文件
Session DB (SQLite) + Hindsight PG
JSON 文件
语义搜索
❌ 无(靠 grep)
✅ pgvector 472ms 召回
❌ 无
跨会话记忆
Daily Markdown(Agent 自管理)
Hindsight PG(独立引擎)
Auto-Memory(Agent 自管理)
记忆上限
无硬限制(文件系统)
PG 无上限
25KB / 200 行

Claude Code 和 OpenClaw 都选择了Agent 自管理记忆——让 Agent 决定记什么。Hermes 选择了独立记忆引擎——Hindsight 在 Agent Loop 之外运行,不受 Agent 的判断力限制。这是三个框架在记忆哲学上最根本的分歧。


五、多 Agent 协作:子 Agent 与 Task Tool

5.1 Claude Code 的子 Agent 模型

Claude Code 支持三种子 Agent 创建方式:

方式 1:静态定义(.claude/agents/)

.claude/agents/security-reviewer.md---name: security-reviewerdescription: Security-focused code reviewmodel: opustools: [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 实现

OpenClaw
Hermes Agent
Claude Code
创建方式sessions_spawn
 工具
delegate_task
 工具
@agent-name
 + Task Tool
进程模型
CLI Runner(子进程)
子进程
子进程(fork/spawn)
配置独立性
✅ 独立 SOUL.md + 模型
✅ 独立 toolsets + 模型
✅ 独立 prompt + 模型 + 工具
通信方式
ACP
Hermes 内部 RPC
IPC / stdio
并行上限
无硬限制
5(delegate_task)
无硬限制
编排复杂度
高(需自己设计 Agent 协作)
中(Kanban 模式)
中(@agent-name 简单直观)

Claude Code 的独特优势:@agent-name 语法极其简洁——在对话中像 @某人一样调用子 Agent,不需要写工具调用代码。这是三个框架中对开发者最友好的多 Agent 接口。


六、安全模型:Permission 分级 + Hooks 拦截

6.1 五级 Permission Mode

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 三角对照:安全模型

OpenClaw
Hermes Agent
Claude Code
权限模型
ToolPolicy(confirm + sandbox)
四层防御(Prompt→Policy→Terminal→Vault)
五级 Permission Mode + 工具白名单
用户确认
✅ 危险操作弹确认
❌ 靠 Prompt 规则约束
✅ 按 Permission Mode 分级
Prompt Injection 防御
❌ 无内置
✅ threat_patterns.py
❌ 无内置
凭据管理
环境变量
AES-256-CBC Vault
环境变量 / apiKeyHelper
沙箱
Docker(CLI Runner)
execute_code 沙箱
子进程隔离(非沙箱)
Hook/拦截点
❌ 无
❌ 无
✅ 8 种 Hook 类型

核心差异:Claude Code 把安全防线设在用户交互层——通过 Permission Mode 让用户控制 Agent 能做多危险的事。Hermes 把防线设在系统层——Prompt Injection 检测 + Vault 加密 + 爆炸半径评估。OpenClaw 居中——ToolPolicy 精细但无自动拦截。


七、Settings 层级:四层配置覆盖

Claude Code 的配置层级设计值得单独一节——它比 OpenClaw 和 Hermes 都更精细:

优先级从高到低: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 追踪导致冲突。

三角对照:配置管理

OpenClaw
Hermes Agent
Claude Code
配置文件openclaw.json
 + SOUL.md
config.yaml
 + SOUL.md + skills/
settings.json
 ×3 + CLAUDE.md ×3
层级
2 层(全局 + 项目)
2 层(全局 + Profile)
4 层(CLI > local > project > global)
团队协作
❌ 单一项目文件
❌ 无团队共享机制
✅ .local 分离团队/个人
热加载
需重启
需重启
需重启

八、终局对照:五维选型矩阵

维度
OpenClaw
Hermes Agent
Claude Code
最佳场景
多通道 AI 助手平台
深度定制 Agent 运行时
终端编程助手
进程模型
Gateway 持久化服务
Python 单循环
Node.js 子进程树
通信标准
ACP + MCP ✅
自研 ✅
ACP + MCP ✅
多 Agent
sessions_spawn(第一公民)
delegate_task(工具层)
@agent-name(对话层)
语义记忆
❌ grep 文件
✅ pgvector 472ms
❌ Agent 自管理
安全防线
用户确认
系统拦截
分级权限
配置管理
2 层
2 层
4 层
编辑器集成
ACP → Zed/VS Code
ACP → Zed/VS Code
学习曲线
高(Gateway + Channel Plugin)
中(Python 生态)
低(npm install 即用)
社区规模
380K GitHub Stars
快速增长

九、总结:三条路线,一个趋势

OpenClaw:平台路线。Gateway 是内核,Channel Plugin 是驱动,ACP + MCP 双协议让 Agent 融入开发生态。380K Star 的社区飞轮驱动生态繁荣。代价是复杂度高、调试门槛高。

Hermes Agent:深度路线。Python 单循环 + Hindsight PG 语义记忆 + 四层安全防御。不做平台做深度——当需要从近万条历史事实中 472ms 语义召回时,只有 Hermes 能做到。代价是通道少、多 Agent 是后来者。

Claude Code:务实路线。Node.js 子进程模型 + 最友好的多 Agent 接口(@agent-name)+ 最精细的权限分级。不追求平台效应,专注做好一件事:让开发者在终端里用 AI 写代码。代价是记忆系统薄弱(无语义搜索)、无多通道支持。

共同趋势:三个框架都选择了子进程隔离执行高风险任务——没有人让 Agent 在同一进程里跑不可信代码。ACP 协议正在成为 Agent ↔ 编辑器的标准通信层,Claude Code 和 OpenClaw 都已接入。

下一篇预告:Codex CLI 源码拆解——OpenAI 的 Python Agent 框架如何用子进程模型与 Claude Code 正面对标,以及与 Hermes 的 delegate_task 形成三角对照。