Harness 与 Agent 工程 · 运行控制与长任务 · 2026-05-29

OpenClaw与Hermes:源码里的 AI Agent 架构知识大复盘

深入源码剖析OpenClaw与Hermes两大AI Agent架构,从“惊艳”到“理解”再到“取舍”,揭示其核心设计哲学与工程挑战。

核心内容:

  1. 两大架构的演进认知:从惊艳初识到深入源码,理解其设计取舍
  2. 核心设计剖析:OpenClaw的四大设计回答与Hermes的三组启示
  3. 未覆盖的落地难题:协议互通、记忆分层、多Agent协作等七大挑战

2 月上旬我开始开发 QQBot 插件(openclaw-qqbot),到 3 月 31 日正式合入 OpenClaw 主仓。这两个月里为了把插件做好,顺着源码把 Channel 契约、Gateway 路由、记忆系统这些核心模块都摸了一遍。回头看这段经历,对 OpenClaw 的认知恰好经历了完整的"看山三境"—— 看山是山:第一次见 OpenClaw,所有人都被惊艳了——24/7 后台常驻、跨多 IM 通道无缝流转、有人格长期记忆、自主完成开放性复杂任务。"这就是 AI 时代的私人助理操作系统"。

看山不是山:用了一段时间,光环褪色。OpenClaw 这边——费 token(Bootstrap 每轮 push 几万 token)、健忘(Compaction 默认有损 + Dreaming 默认关,长对话中段就断片)、复杂任务交付度低(多步骤任务常丢关键决策——后来才明白这正是 Anthropic 所说的"上下文焦虑症"和"自我评估偏差"的典型表现)。Hermes 这边——多人仍有串扰风险(v0.13 加了多 Profile 隔离,但同 Profile 内 USER.md 还是共享的)、核心仍是单体(拆了不少模块,但 AIAgent 类依然是万事汇聚的枢纽)、记忆管理半自动(有 Memory Nudge 和 Session Search,但没有 Dreaming 那种全自动整理)。两个都还在路上。

看山又是山:踩完坑再回头看源码,反而看懂了每个"不完美"背后的工程取舍。OpenClaw 用 4 个设计回答了 4 个重要问题——多协议可插拔契约(Channel 25+ Adapter)、LLM 上下文资源预算(可插拔 Context Engine + 多级 Compaction)、记忆自动沉淀不退化(Dreaming 三阶段加权晋升)、凭证失败与业务失败分治。Hermes 补充另一组启示——经验自动复用(技能自创建、改进闭环)、安全审批先 LLM 分诊再叫人(Smart Approval 三态)、执行隔离覆盖本地到云端(8 种沙箱后端)。

这篇文章前后断断续续写了三周,是对这一阶段工作的沉淀——把上面这些取舍逐个拆开看清楚,给自己留个笔记,也作为 Agent 架构设计的参考。

Part I, II 分别拆源码,Part III 正面对比,第 22 章(7+1 节)直面两套方案仍未覆盖的落地难题——从协议互通(22.1)、记忆分层(22.2)、上下文工程(22.3,融合 Anthropic"上下文焦虑症"与"上下文重置"理论)、能力管理(22.4)、确定性编排(22.5)、多 Agent 协作(22.6,GAN-like 生成-对抗架构与 Sprint Contract)、Harness 全链路治理(22.7,自我评估偏差的对抗性消除、模型与脚手架的动态平衡)到沙箱安全(22.8),逐一给出演进思路——最后以 Google 新书《Agentic Design Patterns》的 21 个模式作为坐标系,重新审视两套架构的覆盖与空白。

Part I: OpenClaw — TypeScript 微内核架构

Part I 深入剖析 OpenClaw 的设计原理、Gateway 核心、插件系统、Agent 执行引擎、记忆系统、安全机制等完整架构,并以 QQ Bot 插件为实战案例。

版本说明:本文已基于 OpenClaw v2026.5.6更新。

1. 设计原理

1.1 OpenClaw 解决什么问题

传统 AI 助手存在三个核心痛点:

痛点 传统方案 OpenClaw 的解法
平台锁定 每个通道需要独立开发 Bot 一个 Agent 实例,通过 Channel Plugin 接入 20+ 通道
能力割裂 能调工具但缺乏安全管控 Agent 执行 shell、读写文件、调用工具,同时有五层纵深防御 + 审批机制兜底
隐私失控 数据流经第三方服务 控制平面和状态数据留在本地设备,仅 LLM 推理请求出站(本地模型则完全离线)

1.2 核心设计理念

本地优先(Local-First):OpenClaw 不是云服务,而是运行在用户设备上的 Gateway 进程。所有会话数据、配置、媒体文件都存储在 ~/.openclaw/ 目录下。Gateway 是控制平面,Agent 是产品本身。

万物皆插件(Everything is a Plugin):核心代码只负责编排——消息路由、会话管理、安全网关。所有具体能力(Discord 通道、Anthropic 模型、浏览器工具)都以插件形式实现,统一通过 Plugin SDK 注册。

安全纵深(Defense in Depth):不是简单的"开或关",而是五层递进防御——从网络层 TLS 到认证层 Device Identity,从命令执行审批到插件安装扫描,再到沙箱隔离。执行策略默认为 deny,所有 shell 命令需要通过白名单或人工审批。插件安装时进行静态代码扫描,发现危险模式直接阻断:

"Security in OpenClaw is a deliberate tradeoff: strong defaults without killing capability."

记忆驱动(Memory-Driven):Agent 不仅有静态的工作区文件(SOUL.md, USER.md, MEMORY.md)定义人格与记忆,还有向量记忆引擎实现混合搜索、Dreaming 后台整合和 Active Recall 主动召回。需要注意的是,记忆按 Agent 维度隔离——同一个 Agent 下所有用户共享记忆(因为 OpenClaw 定位为个人 AI Agent)。多用户场景下,可通过多 Agent 路由绑定(第 4.3 章)为不同用户分配独立 Agent,从而实现记忆隔离。

配置驱动(Config-Driven):一个 JSON 文件(~/.openclaw/openclaw.json)定义所有行为——Agent 配置、Channel 凭证、模型选择、安全策略、定时任务。支持运行时热重载,改配置不需要重启。

1.3 架构全景

从宏观视角看,OpenClaw 的架构可以分为五层:

2. 整体架构详解

OpenClaw 是一个以 Gateway 为中心 的 AI Agent 平台,采用 TypeScript(ESM)构建。通过插件化架构连接消息通道、LLM 提供商和工具扩展,实现「一个 Agent,多端触达」。

核心数据流

3. Gateway — 系统心脏

Gateway 是整个系统的中枢,默认监听 :18789。它的职责远不止消息收发——聊天、会话、配置热加载、模型目录、执行审批、定时任务、远程节点、语音唤醒等几乎所有功能域都通过它的 RPC 方法暴露和调度,是名副其实的微内核中枢。

3.1 启动流程

3.2 连接认证流程

Gateway 采用 Challenge-Response + Device Identity 认证:

先厘清:这里的 "Client" 指什么

Client 指一切独立于 Gateway 进程、通过 WebSocket 主动连入 Gateway 的"操作端"。

同机 Client 默认走 ws://127.0.0.1(loopback 明文),跨机 Client 强制 wss:// + TLS 指纹 Pinning。下图中的 Client 指 TUI, Control UI, Mobile App, Node-Host 等操作端,不包括 Channel 插件(Channel 是进程内模块,不走 WebSocket 握手)。握手流程对所有 Client 一致:

容易混淆的一组概念:Client vs Channel

简单记:Client 是"谁在操作 Agent",Channel 是"Agent 通过哪条线路收发消息"——两者正交。

两者通过 SessionKey 交汇:同一个用户可以在手机 OpenClaw App(Client)上看到 QQ Channel 产生的对话,也能在 TUI(Client)里继续回复。SessionKey 把"谁在操作"和"哪条线路"绑在一起(格式 agent:{agentId}:{channelId}:...,详见 §4.1)。

安全约束:

3.3 RPC 方法体系

上述职责在源码中通过 server-methods.ts(39 个直接注册)+ server-aux-handlers.ts(3 个懒加载)共计 42 个 RPC handler 模块落地,下图按功能域归纳为十余类:

3.4 方法授权流程

3.5 Gateway 的 5 大角色与"边界 vs 实现"哲学

把 Gateway 定位为"操作系统内核"——它不是一个普通的消息网关,而是 OpenClaw 区别于 Hermes, Claude Code 等单体 Agent 框架的根本架构选择。

Gateway 同时承担 5 大角色:

角色 1:唯一长驻进程(Single Source of Truth)

"A single long-lived Gateway owns all messaging surfaces" "One Gateway per host; it is the only place that opens a WhatsApp session."

避免多进程下的 "WhatsApp 二次扫码、Telegram session 冲突" 等致命问题——channel session 天然是状态强相关的,不能多进程并发持有。

角色 2:消息总线(一切流量必经之路)

所有 channel, client, node 流量都走Gateway或由Gateway分发(默认 127.0.0.1:18789):

设计哲学:不分协议入口 —— HTTP, SSE、私有 RPC 全部统一到 WS Schema。

角色 3:多 Agent 路由的物理边界

通过 Multi-Agent Router 做 Agent 隔离:

这是 OpenClaw 最关键的差异化能力 —— 解决了单 Agent 的三个瓶颈:

对比 Hermes:

没 Gateway 这个上层路由,就做不到。

角色 4:认证 + 信任边界

场景 认证方式
同主机 loopback 自动信任(auto-approve)
Tailnet, LAN 必须 connect.challenge 签名 + 配对审批
Tailscale Serve、反向代理 通过 header 注入身份
私网 ingress 可配 gateway.auth.mode: "none"
公网 ingress 强制 shared-secret + idempotency key

关键设计:

意义:一个 Gateway 同时承担"消息路由 + 认证 + 信任根" —— 不需要再叠 nginx、网关。

角色 5:嵌入式 HTTP Host(不只是 WS)

Gateway HTTP Host(同端口 18789):- /__openclaw__/canvas/ ← Agent 可编辑的 HTML/CSS/JS- /__openclaw__/a2ui/ ← A2UI 主机界面

意义:Agent 可以主动构造 UI(canvas)让用户在浏览器看,不需要单独起 web server。

"边界 vs 实现"哲学 —— 微内核保持几千行的根本原因

OpenClaw 架构里,Gateway 是边界,不是实现:

事 谁做
协议定义(WS schema) Gateway
路由 + 认证 Gateway
WhatsApp 会话生命周期 Gateway
Agent 推理 Embedded Pi Runtime(Gateway 内嵌)
Channel 消息收发 Channel Plugins
Memory 整理 memory-core 插件
工具执行 Plugins, Skills

Gateway 自己只做"协议 + 路由 + 信任",其他全是插件 —— 这才能保证微内核保持几千行核心代码。

一些关键工程细节

  1. 默认 127.0.0.1:18789 不对外 —— 安全默认值(secure by default),主动配置才暴露
  2. First frame 必须是 connect —— 握手原子化,握手失败立刻断连,无半连接
  3. hello-ok.features.methods/events 动态发现 —— 客户端不需预知服务端能力,连上后服务端告诉你"我支持哪些方法/事件"
  4. 写操作(chat.send, agent 等会改变状态的方法)必须带 idempotency key —— 分布式系统标准做法,但多数 Agent 框架没做

4. 消息路由 — Session Key 机制

OpenClaw 通过 Session Key 实现消息到 Agent 的精确路由。

4.1 Session Key 格式

agent:{agentId}:{scope}
场景 Session Key 示例
默认主会话 agent:main:main
QQ 私聊 agent:main:qqbot:default:direct:207A5B83...
Discord 群组 agent:support:discord:acc1:group:123456789
Telegram 线程 agent:main:telegram:bot1:direct:user456:thread:msg789

DM 隔离策略:通过 session.dmScope 配置控制私聊会话的隔离粒度。默认 per-channel-peer(同一用户同一 Channel 共享会话);多账号场景可设为 per-account-channel-peer(同一用户通过不同 Bot 账号分别独立会话)。

4.2 多 Agent 路由绑定

OpenClaw 支持在同一 Gateway 下运行多个 Agent,通过 agents.bindings 配置将不同来源的消息路由到不同 Agent。每个 Agent 拥有独立的工作区(人格/记忆/Dreaming)。

配置示例(openclaw.json):

{ "agents": { "list": { "support": { "model": "anthropic/claude-opus-4-6", "identity": "客服助手" }, "dev": { "model": "openai/gpt-4o", "identity": "技术顾问" } }, "bindings": [ { "match": { "channel": "qqbot", "peer": { "kind": "direct", "id": "207A5B83..." } }, "agentId": "support" }, { "match": { "channel": "qqbot", "peer": { "kind": "group", "id": "GROUP_123" } }, "agentId": "dev" }, { "match": { "channel": "discord", "guildId": "987654321" }, "agentId": "dev" } ] }}

路由匹配按优先级逐级尝试(源码 resolve-route.ts):

优先级 匹配维度 说明 示例
1 binding.peer 精确用户 QQ 用户 A → support Agent
2 binding.peer.parent 线程父级 Telegram 线程继承父会话绑定
3 binding.peer.wildcard 同类型通配 所有 QQ 私聊 → 同一 Agent
4 binding.guild+roles 服务器 + 角色 Discord 管理员 → dev Agent
5 binding.guild 服务器/组织 Discord 服务器 987654321 → dev
6 binding.team 团队 MS Teams team → ops Agent
7 binding.account Bot 账号 qqbot:bot2 的消息 → bot2 Agent
8 binding.channel 整个通道 所有 Discord 消息 → dev
9 default 未匹配 兜底到 main Agent

各 Agent 的工作区目录隔离:

~/.openclaw/├── workspace/ ← main Agent 的工作区│ ├── SOUL.md, USER.md ← 人格与用户画像│ ├── MEMORY.md ← 持久记忆│ └── memory/ ← 每日记忆文件(YYYY-MM-DD-slug.md)├── workspace-support/ ← support Agent 的工作区(结构同上)├── workspace-dev/ ← dev Agent 的工作区(结构同上)└── agents/ ← 运行时状态(与 workspace 平级但关联) ├── main/ │ ├── agent/ ← Agent 运行时元数据 │ └── sessions/ ← 会话转录(UUID.jsonl) ├── support/sessions/ └── dev/sessions/

4.3 Agent 间通信——不只是各干各的

多 Agent 不只是"路由隔离"——它们之间可以互相调用。OpenClaw 通过 agentToAgent 工具实现 Agent 间通信:

{ "tools": { "agentToAgent": { "enabled": true, "allow": ["main", "coder", "writer"] } }}

4 种协作模式(通过 SOUL.md 中的 prompt 工程实现,不是框架内置开关):

模式 底层工具 做法 适用场景
Supervisor sessions_send 主 Agent 调度,收到编程需求 → 传给 @coder,写作需求 → 传给 @writer,最后汇总 中央统筹
Router sessions_send 主 Agent 只做路由分发,不参与执行 分诊台
Pipeline sessions_send A 的输出是 B 的输入,串行传递 翻译 → 润色 → 排版
Parallel sessions_spawn 主 Agent spawn 多个子代理并行执行,全部完成后汇总(详见 6.11) 同时翻译 3 篇文章

两套机制的区别:

框架通过 maxPingPongTurns(最大 5 轮)防止 Agent 间 sessions_send 无限来回。

4.4 同一 Agent 下的多用户隔离

同一 Agent 下多用户并发使用时,会话隔离但记忆共享:

会话隔离:每个用户的 SessionKey 不同,对话历史存储在独立的 .jsonl 文件中(文件名 = {sessionId}.jsonl,sessionId 为 UUID):

sessions.json 索引(SessionKey → sessionId 映射): agent:main:qqbot:direct:207A5B83... → c7cbdbf1-...-b303 agent:main:qqbot:direct:9F3E2C71... → ff4b5290-...-0edc agent:main:discord:acc1:direct:123456789 → 69a8d0ce-...-b5d8对应磁盘文件: ~/.openclaw/agents/main/sessions/ c7cbdbf1-2ef0-4dc3-8e0f-8471e4a2b303.jsonl ← 用户 A 的对话 ff4b5290-6aea-48ec-8076-53a5581d0edc.jsonl ← 用户 B 的对话 69a8d0ce-6011-49ef-a651-b046d3f6b5d8.jsonl ← 用户 C 的对话

记忆共享:所有用户的记忆都写入同一个 ~/.openclaw/workspace/memory/ 目录——文件名为 YYYY-MM-DD-slug.md,不含用户标识。LanceDB 向量库也是单一表,无用户分区。

为什么同一 Agent 多用户不是推荐用法? OpenClaw 定位为个人 AI Agent——设计上假设一个 Agent 服务一个人(或一个角色)。同一 Agent 下多用户共享记忆会导致偏好串扰和敏感信息跨用户可见。如果你的场景是"一个 Bot 对外服务多个用户"(如 QQ Bot 公共助手),正确的做法是为不同用户/用户组配置多 Agent 路由绑定(第 4.2 章),让每个 Agent 拥有独立的 workspace 和记忆。简单说:一个 Agent = 一份记忆 = 一个服务对象,这是 OpenClaw 的记忆隔离模型。

5. 插件系统 — 万物皆插件

5.1 插件分类

分类 代表插件 说明
Channel Discord, Telegram, QQ Bot, Slack, 飞书, WhatsApp, Signal, MS Teams 消息通道接入,每个 Channel 一个插件
Provider Anthropic, OpenAI, Google, DeepSeek, Ollama, Groq, Bedrock LLM 模型提供商,统一 API 抽象
Tool Browser, Exa, Firecrawl, Tavily, SearXNG, Brave, DuckDuckGo Agent 可调用的外部工具(搜索、浏览等)
Media ElevenLabs, Deepgram, MLX Talk, Voice-Call 语音合成(TTS)、语音识别(STT)、本地推理
Memory Memory-LanceDB, Memory-Wiki, Active Recall, Dreaming 记忆存储、知识库、主动召回、睡眠整理
基础设施 Diagnostics-OTEL, Device-Pair, Thread-Ownership, Compaction 监控、设备配对、会话压缩等内部能力

5.2 Channel Plugin 适配器架构

每个 Channel Plugin 由一组可选适配器组成,按需实现:

Channel 完整契约:25+ Adapter

OpenClaw 的 ChannelPlugin 不是简单的"消息适配器"——它同时承担协议适配、身份配对、安全审批、命令路由、配置生命周期、Gateway 协议绑定等角色,是一个完整的 IM 域协作单元。

接口源码:

type ChannelPlugin = {// ━━━ 必选 4 项 ━━━ id: ChannelId; // 唯一标识(telegram, discord / ...) meta: ChannelMeta; // 元数据(图标、名称、类型) capabilities: ChannelCapabilities; // 能力声明 config: ChannelConfigAdapter; // 配置加载、校验、解析// ━━━ Setup 三件套 ━━━ setupWizard?: ChannelSetupWizard; setup?: ChannelSetupAdapter; configSchema?: ChannelConfigSchema;// ━━━ Auth + Security 7 项 ━━━ auth?: ChannelAuthAdapter; pairing?: ChannelPairingAdapter; security?: ChannelSecurityAdapter; approvalCapability?: ChannelApprovalCapability; elevated?: ChannelElevatedAdapter; secrets?: ChannelSecretsAdapter; allowlist?: ChannelAllowlistAdapter;// ━━━ Messaging 7 项 ━━━ messaging?: ChannelMessagingAdapter; message?: ChannelMessageAdapterShape; outbound?: ChannelOutboundAdapter; streaming?: ChannelStreamingAdapter; // ⭐ per-channel 流式协议 threading?: ChannelThreadingAdapter; mentions?: ChannelMentionAdapter; agentPrompt?: ChannelAgentPromptAdapter;// ━━━ 协作能力 7 项 ━━━ commands?: ChannelCommandAdapter; groups?: ChannelGroupAdapter; directory?: ChannelDirectoryAdapter; resolver?: ChannelResolverAdapter; bindings?: ChannelConfiguredBindingProvider; conversationBindings?: ChannelConversationBindingSupport; actions?: ChannelMessageActionAdapter;// ━━━ Gateway + 运维 6 项 ━━━ gateway?: ChannelGatewayAdapter; // ⭐ Gateway 协议绑定(核心) gatewayMethods?: string[]; // 暴露给 Gateway 的方法列表 lifecycle?: ChannelLifecycleAdapter; status?: ChannelStatusAdapter; heartbeat?: ChannelHeartbeatAdapter; doctor?: ChannelDoctorAdapter; reload?: { configPrefixes: string[] }; // 精细化热重载// ━━━ 反向工具 ━━━ agentTools?: ChannelAgentToolFactory; // ⭐ Channel 给 LLM 提供工具};

所有槽位都是可选的 —— Telegram/Discord 实现了 30+ 个,简单内部 webhook channel 只需实现 4 个必选 + 5 个可选。

Channel ↔ Gateway 的 5 种交互模式

模式 方向 说明
入站消息 Channel → Gateway → Agent Channel inbound 归一化 → Gateway 路由到 Agent
出站回复 Agent → Gateway → Channel Agent 出 turn → Gateway 派单 → Channel outbound
客户端控制 Client → Gateway → Channel WS method: "telegram.send" → ChannelGatewayAdapter.handle
反向工具 Channel → Agent agentTools 注册到 Agent tool registry(Telegram 提供查群成员、Discord 提供加 reaction 等)
反向通知 Channel → Gateway → Client event:presence / event:tick 推到所有连 Gateway 的客户端

所有 5 种模式都走同一个 WS Schema。

Per-channel Streaming Adapter 是 Channel 的核心价值——LLM 流式输出的"语义"在每个 IM 协议里完全不同(Telegram 用 editMessageText 反复编辑同一条消息、Discord 用 interaction.followUp, iMessage 不支持流式退化为分段发送),Channel 把这些差异封装掉。

Channel Docking 是 OpenClaw 的独门能力——跨 Channel 会话迁移。用户 Alice 在 Telegram 发起会话后想切到 Discord 继续,发 /dock_discord,Gateway 验证 identityLinks 确认两个账号属于同一用户后,保留 session 上下文不变,只换投递地址。不重建 session——相当于"AI 会话的呼叫转移"。

精细化热重载:每个 Channel 声明自己关心哪些 config prefix(如 telegram.bot.*),Gateway 只在对应配置变更时重启该 Channel,不重启整个进程。

Channel 的核心价值就在这里 —— 把"流式 LLM 输出"翻译成每个 IM 协议的最佳呈现。

反向能力:Channel → LLM 工具

agentTools?: ChannelAgentToolFactory —— Channel 可以反向给 LLM 提供工具:

Channel 不只是消息通道,还是 LLM 的能力扩展源。

Channel Docking — 跨 Channel 会话迁移(独门能力)

源码 docs/concepts/channel-docking.md:

用户 Alice 同时在 Telegram 和 Discord 用 OpenClaw ↓identityLinks: { alice: ["telegram:123", "discord:456"] } ↓Alice 在 Telegram 发起会话 → active session 路由到 telegram:123 ↓Alice 想切到 Discord 继续 → 在 Telegram 发 "/dock_discord" ↓OpenClaw 验证:telegram:123 和 discord:456 都属于 alice?是 → 允许 ↓保留 session 上下文不变 → 改路由 → 后续回复发到 discord:456

实现机制:

  1. Gateway 自动为每个 Channel 插件生成 /dock-{channel} 和 /dock_{channel} 命令(auto-reply/commands-registry.data.ts:22)
  2. Session 层有 identityLinks 配置
  3. 不重建 session —— 只换"投递地址"

这是 Hermes, Claude Code 等单 channel 框架做不到的"call forwarding for AI session"。

精细化热重载

reload: { configPrefixes: ["telegram.bot."] }

这告诉 Gateway:当用户修改 telegram.bot.* 任何配置时,只重启 telegram channel,不重启整个 Gateway —— 精细化热重载。

对照:OpenClaw Channel vs Hermes Channel

维度 Hermes Channel OpenClaw Channel
抽象层级 函数式 send/recv 25+ 个可选槽位的完整契约
Setup 流程 改源码、手填配置 SetupWizard + Schema + UI 引导
认证 API Key 写文件 Auth + Pairing + Security + Approval + Elevated 5 层
Streaming 单一实现 Per-channel Streaming Adapter
Docking ❌ ✅ Cross-channel session forwarding
Doctor ❌ ✅ 自诊断
热重载 重启 ✅ 精细化 reload prefix
反向工具 ❌ ✅ Channel 给 LLM 提供工具

设计取舍:Hermes 把 Channel 当消息收发管道——轻量、容易加新平台;OpenClaw 把 Channel 当需要长期维护的平台集成点——重、但加上之后不用再操心认证/重载/诊断。

5.3 插件注册模式

5.4 插件发现与加载

安全检查:

5.5 插件安装安全扫描

6. Agent 执行引擎

OpenClaw 的 Agent Runtime 本质是一个"调度 + 容错 + 预算"的编排核——它不直接承担"如何思考",而是通过 hook 和插件把具体能力外包出去,自己专注于三件事:决定调谁(调度)、失败了怎么办(容错)、花多少资源(预算)。这让 runtime 核心保持在几千行代码量级,却支撑起了完整的多用户、多通道、多模型的生产级能力。

** 底层引擎:@mariozechner/pi-agent-core(ReAct 循环的工程级实现)**

OpenClaw 的 Agent 执行循环建立在一个独立的底层包 @mariozechner/pi-agent-core之上——由 OpenClaw 创始人 Mario Zechner 维护。这个包实现的就是经典的 ReAct(Reason + Act)模式:

agentLoop(prompts, context, config): while (未结束): convertToLlm(context.messages) → 准备 LLM 可理解的 Message[] streamFn(messages, model, tools) → 调 LLM,流式返回(Reason) 解析 assistant response: ├─ 有 toolCall → beforeToolCall → 执行工具 → afterToolCall → 结果加入 context → 继续(Act) └─ 无 toolCall → 结束

pi-agent-core 只负责"循环本身"——它不懂预算、不懂容错、不懂通道路由。OpenClaw 在它之上叠加了所有生产级能力:

层 谁负责 做什么
循环层 pi-agent-core ReAct 循环、工具调用(parallel/sequential)、流式输出、上下文转换
编排层 OpenClaw pi-embedded-runner/ 预算控制、Auth Profile failover, Compaction, Lane 分车道、Bootstrap 注入
拦截层 OpenClaw hooks beforeToolCall(审批/安全扫描)、afterToolCall(截断/日志)、transformContext(Compaction)
能力层 OpenClaw plugins 循环本身不提供的外部能力——记忆检索、消息出站、模型适配等,按需调用、可插拔

关键设计点(来自源码 pi-agent-core/dist/types.d.ts):

和 Hermes 的对比:Hermes 的 AIAgent.run_conversation() 也是 ReAct 循环,但循环和编排耦合在同一个万行类里——没有独立的"循环层"。OpenClaw 把循环抽成独立包的好处是:升级 ReAct 策略(如从 sequential 改 parallel tool call)不需要动编排逻辑,反之亦然。

6.1 分层执行架构

OpenClaw 的 Agent 入站有三条路径,最终都汇聚到同一条执行链路上:

关于入站层的两点澄清:

  1. ACP Server 是"经 Gateway 入站"的——openclaw acp 启动一个 ACP 前端(供 Zed, Copilot CLI 等 IDE 连接),但它收到 session/prompt 后会通过 gateway.request("chat.send", ...) 把请求转发到 Gateway(见 src/acp/translator.ts),和 QQ Bot、飞书走同一条入站路径。所以 ACP 不是"另一个入口平行于 Gateway",而是"Gateway 的一个前端协议适配器"——这就是第 22 章说的 ACP Bridge 模式。
  2. CLI 有两种模式——openclaw tui 默认通过 WS 连接 Gateway(和 Control UI / Mobile App 走同一条路径),而 openclaw chat(tui 的别名)默认启用 --local,在进程内启动嵌入式 Agent 运行时(EmbeddedTuiBackend),不经过 Gateway RPC。Local 模式让开发调试不需要先拉起 Gateway,但代价是不受 Gateway 上的审批/速率限制策略管控(local 模式走本地 TUI 审批)。

关于 Provider 层的三路分叉:注意这里的 DECIDE 不是"会话类型"而是"provider 类型"——Hermes 的 ACP 客户端(copilot_acp_client.py)和 OpenClaw 的 acpManager.runTurn 做的是同一件事:把 ACP 反过来当 LLM provider 用。当你想用 GitHub Copilot 订阅额度跑 Agent 时,就会走这条分支(不是 ACP server 入站)。

三层错误边界:

这是 OpenClaw 容错设计的核心——可恢复错误的处理是静态可证明的,不靠 LLM 猜。

runEmbeddedPiAgent 主循环深入剖析

runEmbeddedPiAgent(src/agents/pi-embedded-runner/run.ts,约 1000 行)是 6.1 架构图中核心层的中央——非 CLI/ACP provider 的所有请求最终都汇聚到这里。名字里的 Embedded 表示"直接调 Provider SDK、不 spawn 子进程",Pi 表示构建在 @mariozechner/pi-agent-core 之上——OpenClaw 没有自己写 Agent 核心循环,而是包装 pi-agent-core 并在外面套多 provider 适配 + 容错降级 + Hook 触发 + 缓存追踪。

三段结构

export asyncfunction runEmbeddedPiAgent(params): Promise<EmbeddedPiRunResult> {// ─── 阶段 1: 一次性初始化(循环外,高成本 IO 只做一次)───const sessionLane = resolveSessionLane(params.sessionKey);const globalLane = resolveGlobalLane(params.lane);const authController = createEmbeddedRunAuthController({ ... });await authController.initializeAuthProfile();const contextEngine = await resolveContextEngine(params.config); // 跨重试复用// ─── 阶段 2: 预算常量与计数器 ───const MAX_RUN_LOOP_ITERATIONS = resolveMaxRunRetryIterations(profileCandidates.length);let runLoopIterations = 0;// ... 其他计数器:overflowCompactionAttempts, timeoutCompactionAttempts ...// ─── 阶段 3: 主循环(真正的重试-降级-恢复)───while (true) { if (runLoopIterations >= MAX_RUN_LOOP_ITERATIONS) return retryLimitExceededResult(); runLoopIterations += 1; const attempt = await runEmbeddedAttempt({ ... }); // 七类分支按优先级判断(顺序不能乱) if (attempt.aborted) return abortedResult(); if (consumeLiveSessionModelSwitch(...)) thrownew LiveSessionModelSwitchError(...); if (timedOut && tokenUsedRatio > 0.65) { /* Timeout Compaction */continue; } if (contextOverflowError) { /* 三级降级:compact → truncate → 抛错 */continue; } if (assistantErrorText) { /* 分类:auth 刷新 / overloaded backoff / 轮换 profile / 抛 FailoverError */continue; } await markAuthProfileGood({ profileId: lastProfileId }); return successResult({ payloads: attempt.payloads, ... }); }}

关键设计

1. 双 Lane 排队:同时持有 globalLane(调用类型:Default/Nested/Subagent/Cron)和 sessionLane(sessionKey 哈希)。双锁意义——一个 Cron 任务和用户对话即使打到同一会话也会被 sessionLane 强制串行,不同会话的 Cron 之间互不阻塞。

2. 七类分支顺序决定正确性:

优先级 分支 不能放后面的原因
1 aborted 用户中断必须立即响应
2 live model switch 要在产生任何副作用前重启
3 timed out + 高 token 预防性主动压缩,避免下次又被 timeout kill
4 context overflow 三级降级(compact → truncate → 抛错)逐级恶化
5 assistant error 分类后选 profile 轮换、token 刷新、overloaded backoff
6 success path 成功路径
7 兜底 迭代上限 → 抛错

两个关键细节:timeout compaction 必须在 overflow 之前——timed out + 65% context 是预防性信号(LLM 还没报错,但延迟暗示 prefill 慢),先走 overflow 会等到下次明确报错,但那时可能直接被 timeout kill;truncate 是 overflow 的最后手段——截断会永久删除 tool 输出并写回 session.json,只在 compaction 都失败后才用,整个 run 只用一次。

3. runEmbeddedAttempt 是"跑一次完整 Agent 轮次":外层 runEmbeddedPiAgent永远不直接调 stream,所有 LLM 交互在 runEmbeddedAttempt(run/attempt.ts,2000+ 行)内完成——Bootstrap 上下文加载 → buildSystemPrompt → 创建 pi-agent-core session → session.run()(内部是 pi-agent-core 的多轮 LLM↔Tool 循环)。关注点分离:attempt 做"跑一轮",外层做"重试到成功或策略耗尽"。

4. Auth Controller 封装凭证决策:createEmbeddedRunAuthController 对外只暴露 initializeAuthProfile, advanceAuthProfile, maybeRefreshRuntimeAuthForAuthError, stopRuntimeAuthRefreshTimer 4 个方法。外层主循环看不到"profile cooldown / token refresh / probe slot"这些复杂度,全被收进 auth-controller.ts。

5. FailoverError 是与外层的唯一契约:主循环里所有"可恢复错误"最终都 throw new FailoverError(reason, ...),调用者 runWithModelFallback 只接 FailoverError(instanceof 匹配就换模型,否则直接抛)。runEmbeddedPiAgent 是"FailoverError 工厂",runWithModelFallback 是"消费者"——两者只通过这一个错误类型交流(详见 §6.3)。

6. Live Model Switch 的幂等条件:只有完全干净的 attempt(没发消息、没执行工具、没产生 assistant 文本、没审批提示、没工具错误)才允许实时切模型。一旦对外产生过影响,切模型重来就会导致重复发送或不可撤销操作——这些条件一旦触发就锁死 live switch 路径。

换句话说,runEmbeddedPiAgent 本身不调 LLM、不执行工具、不构建 prompt(这些都委托给 runEmbeddedAttempt),它只做一件事:反复尝试,直到成功或把错误以 FailoverError 抛给上层。

6.2 Auth Profile——不只是"API Key 数组"

先看一个真实场景:你有 3 个 Anthropic 账号——个人 Pro 订阅、公司 Max 订阅、一个 AWS Bedrock 账号。你想让 OpenClaw 自动管理这 3 个账号:Pro 额度用完了自动切 Max,Max 被限频了自动切 Bedrock,任何一个恢复了自动切回来。

Hermes 做不到——它的 Credential Pool 只是 API Key 数组,按顺序试,失败了不知道为什么失败,也不记得"上次哪个 key 挂了"。

OpenClaw 的 Auth Profile 把每个账号建模为带健康状态的对象:

你的 3 个 Profile:Profile A: "个人Pro" ├─ 类型: OAuth(可自动刷新 token) ├─ 状态: ⚠️ 冷却中(billing 错误,5min 后重试) └─ 冷却原因: 当日额度用完Profile B: "公司Max" ├─ 类型: API Key ├─ 状态: ✅ 可用(上次用于 30s 前) └─ 冷却原因: 无Profile C: "AWS Bedrock" ├─ 类型: Token(带过期时间) ├─ 状态: ✅ 可用(token 2h 后过期) └─ 冷却原因: 无

当请求失败时的行为差异:

场景:用 Profile A 调 Claude,返回 429 rate_limitHermes 的做法: retry → retry → retry → 超时报错(不知道该切 key)OpenClaw 的做法: ① 识别错误类型 = rate_limit(凭证类) ② Profile A 标记冷却 30s ③ 50ms 内切到 Profile B ④ 用户无感知,对话继续 ⑤ 30s 后 Profile A 自动"探针重试"——如果恢复了加回可用队列

数据结构(auth-profiles/types.ts):

type AuthProfileCredential = | ApiKeyCredential // { key, provider } ← 最简单 | TokenCredential // { token, expiresAt } ← 会过期,到期自动换下一个 | OAuthCredential; // { clientId, refreshToken } ← 能自动刷新,最持久type ProfileUsageStats = { lastUsed: number; cooldownUntil: number; // 临时退避:30s → 1min → 5min(指数退避) cooldownReason: "rate_limit" | "overloaded" | "billing" | ...; disabledUntil: number; // 永久型错误(key 被吊销) failureCounts: Record<FailureReason, number>;};

选取策略(auth-profiles/order.ts)——决定"下一个用哪个 Profile":

  1. 类型偏好:oauth > token > api_key(能自动刷新的优先——活得更久)
  2. 均衡轮转:同类型按 lastUsed 升序(不让一个 key 被打爆)
  3. 冷却探针:冷却中的 profile 排末尾,到期后自动试一次——恢复了就回主队列
  4. 用户锁定:显式指定的 preferredProfile 永远优先(调试/测试用)

和 Hermes Credential Pool 的关键差异:

维度 Hermes Credential Pool OpenClaw Auth Profile
抽象层级 API Key 数组 凭据 + 健康状态 + 来源
凭据类型 只支持 api_key api_key, token(带过期)/ oauth(可刷新)
持久化 进程内内存(重启丢失) 磁盘 store(~/.openclaw/auth-profiles/),重启保留冷却状态
外部同步 无 通过 external-cli-sync.ts 自动发现本地 claude-cli / codex 已登录的账号
选取逻辑 线性尝试(从头到尾试) round-robin + 冷却队列 + 类型偏好 + 用户锁定
冷却策略 统一计数 按 FailoverReason 分级退避(rate_limit 30s / billing 5min / auth_permanent 永久禁用)

生产体验差异举例:

6.3 FailoverError——把错误分类做成结构化契约

多数框架遇到错误"抓异常重试",OpenClaw 把错误的 reason 做成闭合枚举:

// agents/pi-embedded-helpers.tstype FailoverReason = | "billing" // 402 | "rate_limit" // 429 | "overloaded" // 503 | "auth" // 401(可刷新) | "auth_permanent" // 403(禁用) | "timeout" // 408 / ETIMEDOUT / ECONNRESET... | "format" // 400(payload 问题) | "model_not_found" // 404 | "session_expired"; // 410

分类器(resolveFailoverReasonFromError)是递归的——逐级走 HTTP status → 符号码(RESOURCE_EXHAUSTED / THROTTLING_EXCEPTION)→ errno → cause 链 → timeout heuristics,容忍不同 Provider SDK 的错误表达差异。

分类结果驱动不同策略(failover-policy.ts):

策略 适用 reason 效果
shouldAllowCooldownProbeForReason rate_limit, overloaded, billing 允许探针式重试冷却中的 profile
shouldUseTransientCooldownProbeSlot 瞬时错误(rate_limit, overloaded) 走临时 slot,不占用主 profile
shouldPreserveTransientCooldownProbeSlot 永久错误(auth_permanent, session_expired) 保留 slot 供后续复用

甚至连不是 API 调用的错误也会被翻译成 FailoverError——context_length_exceeded, session_expired, model_not_found 全走同一条路。这样 runWithModelFallback 能用统一契约处理所有可恢复错误,代价是错误分类器要维护大量启发式规则(值得,因为这部分的边界条件是"外部世界决定的",不是业务复杂度)。

6.4 双路径执行——把 Claude Code, Codex CLI 当 Backend

runAgentAttempt 在 command/attempt-execution.ts 里做一次关键分叉:

isCliProvider?├─ true → runCliAgent│ • 调用 claude-cli, codex-cli 子进程│ • 通过 cli-session.ts 管理子进程生命周期│ • 共享同一套 workspace, memory, session 结构│└─ false → runEmbeddedPiAgent • 通用 pi-agent 引擎(基于 @mariozechner/pi-agent-core) • 直接调用 Provider SDK(openai / anthropic / google / ...)

这是微内核架构的真正红利——OpenClaw 不把 Claude Code, Codex CLI 当"竞品",而是把它们当可替换的执行 backend:同一个 Gateway 管理、同一个 Agent 人格、同一套记忆系统、同一个会话转录格式,只是底层 LLM 调用换了个 Runner。

实际使用中的典型配置:同一个 Gateway 下多个 Agent 各用不同 backend——

CLI Backend 的协议适配

把"Claude Code, Codex CLI 当 backend 用"听起来像是接入一个标准协议——但实际上没有这样的协议。这一节讲 OpenClaw 是怎么解决这个问题的。

各家 CLI 的输出协议互不相同

Backend 命令 输入方式 输出协议
claude-cli claude -p --output-format stream-json --verbose --permission-mode bypassPermissions prompt 作为命令行参数(超长走 stdin) Claude Code 自定义的 stream-json(一行一个 JSON 对象,含 message / tool_use / tool_result 事件)
codex-cli codex exec --json --color never --sandbox workspace-write 命令行参数 Codex 的 JSONL 事件流(fresh)/ 纯文本(resume,因 codex quirk)
gemini-cli gemini --prompt --output-format json 命令行参数 单一 JSON 对象输出

关键事实:这三种格式互不相同——不是 ACP、不是 MCP、不是 OpenAI Chat Completions、不是 Anthropic Messages,是各家 CLI 各自定义的 stdout 协议。Claude CLI, Codex CLI, Gemini CLI 的输出格式都是为各自 IDE 集成(VSCode 插件等)设计的私有协议,早于 ACP 标准出现。

CliBackendConfig ——配置驱动的适配层

由于没有标准协议,OpenClaw 用一个配置对象来抽象差异(src/config/types.agent-defaults.ts:47):

export type CliBackendConfig = { command: string; // 可执行文件名 args?: string[]; // 默认参数 output?: "json" | "text" | "jsonl"; // 输出解析模式 resumeOutput?: "json" | "text" | "jsonl"; // resume 模式可独立设置 input?: "arg" | "stdin"; // prompt 怎么喂 maxPromptArgChars?: number; // arg 超长就转 stdin modelArg?: string; // 怎么传模型 ID(如 --model) modelAliases?: Record<string, string>; // OpenClaw model id → CLI model id sessionArg?: string; // 怎么传 session id sessionMode?: "always" | "existing" | "none"; sessionIdFields?: string[]; // 从输出哪个字段读 session id systemPromptArg?: string; // 怎么传 system prompt systemPromptMode?: "append" | "replace"; imageArg?: string; // 怎么传图片 imageMode?: "repeat" | "list"; clearEnv?: string[]; // 启动前清的 env vars serialize?: boolean; reliability?: { watchdog: { fresh: {...}, resume: {...} } };};

整个适配器层做的事就是把"OpenClaw 抽象的请求"翻译成"目标 CLI 能听懂的命令行 + stdin":

OpenClaw runtime 请求 ├─ prompt: "Help me debug..." ├─ model: "claude-cli/claude-sonnet-4-6" ├─ systemPrompt: "You are..." └─ sessionId: "abc-123" ↓ buildCliArgs (cli-runner/helpers.ts) ↓ spawn("claude", [ "-p", "--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions", "--model", "sonnet", ← 经 modelAliases 映射 "--session-id", "abc-123", ← sessionArg 决定 "--append-system-prompt", "You are...", ← systemPromptArg 决定 "Help me debug..." ← input=arg ]) ↓ 子进程 stdout 输出 stream-json ↓ cli-runner/execute.ts 按 output="jsonl" 行解析 ↓ 翻译回 OpenClaw 抽象的 AgentMessage 流

反向 MCP 注入——隐藏的协议

这是 CLI Backend 设计里最巧妙的一环。Claude CLI 自己有原生工具集(read, write/bash 等),但 OpenClaw 还想让 CLI 能用自己的扩展工具(比如 send_message, subagents 等)。怎么做?

// extensions/anthropic/cli-backend.ts:17{ id: CLAUDE_CLI_BACKEND_ID, bundleMcp: true, // ← 关键 config: { command: "claude", args: [...] },}

bundleMcp: true 让 OpenClaw 在启动 CLI 时,通过 Claude CLI 的 MCP 配置注入一个本地 MCP 服务器——这个 MCP 服务器就是 OpenClaw 自己跑起来的(src/mcp/channel-server.ts)。Claude CLI 通过 MCP 协议反过来调 OpenClaw 提供的工具:

OpenClaw runtime ↓ spawn ┌──────────────────────┐ │ Claude CLI 子进程 │ │ │ │ → Anthropic API │ ◄── LLM 调用是 CLI 自己做的 │ │ (用 CLI 已登录的 OAuth) │ → MCP Client │ ◄── 调 OpenClaw 工具 └─────────┬─────────────┘ │ stdio MCP │ ▼ ┌────────────────────┐ │ OpenClaw MCP Server │ ◄── 提供 send_message / │ (channel-server) │ subagents / 等扩展工具 └────────────────────┘

所以 CLI ↔ OpenClaw 之间实际是混合协议:LLM 输出走各家 CLI 的私有 stdout 协议,工具调用走 MCP。这是文章第 22 章讲到的"反向 MCP"在 CLI 路径上的第二处应用——不只是面向第三方 IDE 暴露,也面向自己 spawn 的 CLI 子进程暴露。

与 ACP 路径的对比

文章 6.1 图里有三种 provider 类型:embedded, CLI provider, ACP provider。它们的协议是这样的:

Provider 类型 协议 适用
embedded 各 LLM 厂商的 HTTP API(Anthropic Messages / OpenAI Responses / Google generateContent / ...) 走自己的 API Key
CLI provider 每家 CLI 各自的 stdout 流格式(stream-json / jsonl / json)+ 反向 MCP 注入工具 复用本地 CLI 的登录态(Claude OAuth, ChatGPT 订阅、Gemini 账号)
ACP provider ACP 协议(JSON-RPC over stdio,由 @agentclientprotocol/sdk 定义) 把别的 ACP agent(GitHub Copilot ACP 等)当 LLM backend

ACP 路径不是直接调"gemini"或"copilot"的同一个二进制——extensions/acpx/ 是 OpenClaw 的 ACP 客户端代理,它启动的是专门的 ACP wrapper 脚本(如 codex-acp-wrapper.mjs, claude-agent-acp-wrapper.mjs),走标准的 ACP 协议(JSON-RPC over stdio)。支持的 ACP harness(注:harness 是 OpenClaw 内部用语,不是 ACP 协议规范术语,指"被 OpenClaw 通过 ACP 协议驱动的外部 Agent 运行时",见 extensions/acpx/skills/acp-router/SKILL.md 和 docs/tools/acp-agents.md)包括:codex, claude, gemini, droid, opencode 等。同一个"codex"既可以作为 CLI provider(走 JSONL stdout 流),也可以作为 ACP harness(走 JSON-RPC 协议)——取决于配置里选哪条路径。

设计哲学:CLI Backend 走的是"已存在生态优先"路线——不要求 CLI 厂商支持 ACP,而是用 CliBackendConfig 写适配器吃掉各家差异。

双向连接——OpenClaw 也是别人的 Backend

6.4 和 6.4.1 讲了"OpenClaw 把 CLI 当 backend"的方向。但这个故事还有另一半——OpenClaw 自己也被设计为别人的 backend。这一节讲反方向。

先解决一个疑问:私有协议为什么能"当 backend 用"?

理解反方向之前,要先回答 6.4.1 留下的隐含问题——既然 stream-json, codex jsonl, gemini json 都是私有协议,OpenClaw 为什么能稳定接入?

三个原因:

  1. 私有协议是"事实开放"的——CLI 厂商为了支持自家 IDE 集成(VSCode 插件, Cursor, Zed),必须让协议对外可解析且稳定。一旦改动会破坏所有下游集成,所以厂商有强烈动机保持向后兼容。OpenClaw 把自己当成"另一个下游集成"——和写一个 VSCode 插件没有本质区别。可以类比 gh CLI 的 --json 输出:没有 RFC 标准,但全世界写脚本的人都在用。
  2. 协议适配做成可配置层——CliBackendConfig 是外部可注册的(api.registerCliBackend(...))。任何人都能加一个新 CLI backend,不改 OpenClaw 核心代码。所以"协议私有"不是问题,问题是"协议是否稳定 + 是否可解析"——这两条满足了,谁定的协议都不重要。
  3. OpenClaw 不需要懂 LLM 协议本身——这是最关键的一点:
embedded 路径: OpenClaw 必须自己实现 anthropic-messages, openai-responses、 google-generateContent 等多套 HTTP 协议适配CLI 路径: OpenClaw 只需要 spawn CLI、解析 stdout LLM 协议适配的复杂度被 CLI 吃掉了

复杂度从"N 套 HTTP 协议"降到"N 套 stdout 格式"——后者天然更简单(行 JSON 比 SSE + tool call schema + thinking blocks 简单太多)。CLI backend 实质是把"LLM 协议适配"委托给 CLI 厂商,OpenClaw 只解决"如何驱动 CLI"这个更窄的问题。

反方向:OpenClaw 提供三种暴露面

那 Claude Code, Codex CLI, Cursor, Zed 这些工具能反过来调用 OpenClaw 吗?能——而且 OpenClaw 主动设计了三种粒度的暴露面:

外部工具想要什么粒度的访问? │ ┌───────────┼───────────┐ ▼ ▼ ▼ 工具粒度 Agent 粒度 系统粒度 │ │ │ ▼ ▼ ▼ MCP Server ACP Server HTTP API

路径 1:MCP Server——工具粒度

openclaw mcp serve 把 OpenClaw 暴露为一个 MCP server。任何支持 MCP 的客户端都可以连接:

Claude Code (用户主动启动的) ↓ stdio MCP 协议 ↓OpenClaw MCP Server (channel-server.ts) ↓ 暴露 9 个具体工具: │ ├─ conversations_list (列出聊天会话) ├─ conversation_get (读会话详情) ├─ messages_read (读 QQ Bot、飞书、Discord 历史消息) ├─ messages_send (从 Claude Code 反向发消息到 QQ Bot) ├─ attachments_fetch (拉取附件) ├─ events_poll / events_wait(监听新消息) ├─ permissions_list_open (看待审批列表) └─ permissions_respond (审批/拒绝 Agent 的执行请求)

使用场景:Codex / Claude Code 等 MCP 客户端需要访问 OpenClaw 管理的 IM 会话时(如在 IDE 里直接测试 QQ Bot 消息收发、CI 完成后通过 OpenClaw 向飞书群发通知等),在客户端配置里加一行 openclaw mcp serve,就能通过 conversations_list(列出会话)/ messages_read(读历史)/ events_wait(等新消息)/ messages_send(回复)等标准 MCP 工具操作 OpenClaw 的所有 Channel 会话——coding agent 把 OpenClaw 当成"统一通讯能力扩展",一个 MCP server 覆盖所有通道。

路径 2:ACP Server——Agent 粒度

openclaw acp 启动 ACP 协议前端。支持 ACP 的 IDE(Zed, Copilot CLI 等)可以把 OpenClaw 当 Agent 用:

Zed IDE ↓ ACP 协议(JSON-RPC over stdio) ↓OpenClaw ACP Server (src/acp/server.ts) ↓ gateway.request("chat.send", ...) ↓Gateway → agentCommand → runEmbeddedPiAgent ↓LLM 调用 + 工具执行 ↓ ACP 协议事件流返回到 Zed

典型场景:用户在 Zed 里有一个聊天面板,里面接的是 OpenClaw 的某个 Agent。用户在 Zed 里发"帮我把今天 QQ Bot 的对话整理成日报"——OpenClaw 用自己的 Agent 跑这个任务,结果通过 ACP 协议流回 Zed 显示。

与 MCP 的区别:MCP 是"暴露几个工具",ACP 是"暴露整个 Agent"——粒度完全不同。

路径 3:Gateway HTTP API——系统粒度

OpenClaw 的 Gateway 本身有完整的 HTTP API(src/gateway/server-methods/),包括 chat.send, session.list, config.get 等几十个方法。任何能发 HTTP 请求的程序都能调它——curl, Python 脚本, Bot, CI/CD 流水线。

ACP Server 和 MCP Server 本质都是这个 HTTP API 的"协议前端适配器"——把 ACP/MCP 请求翻译成 Gateway HTTP 调用。

三种路径对比

路径 协议 谁会用 暴露什么
MCP Server MCP(stdio JSON-RPC) Claude Code, Cursor, Zed、自定义 Agent 9 个具体工具(消息收发、审批管理)
ACP Server ACP(stdio JSON-RPC) Zed, Copilot CLI 等 ACP-aware IDE 整个 Agent 能力(一个聊天 session)
Gateway API HTTP REST/RPC 任何 HTTP 客户端 所有 Gateway 方法(最底层)

完整的协议反转图

把"OpenClaw 调 CLI"和"CLI 调 OpenClaw"放在一起看:

方向 A 和方向 B 都用到了 MCP,但角色完全相反——

差别只在触发者——MCP server 不知道也不关心是谁连过来的,它就是个工具暴露面。

"双向连接"的设计意图

OpenClaw 的选择是不试图取代任何现有工具,而是和它们互联:

场景 谁是主,谁是辅
用户主要在聊天平台(QQ Bot、飞书)和 Agent 对话 OpenClaw 是主,Claude CLI 是 LLM backend
用户主要在 Claude Code 里写代码 Claude Code 是主,OpenClaw 是消息通道扩展
用户在 Zed 里需要一个聊天 Agent Zed 是主,OpenClaw 是 Agent 实现
外部脚本通过 HTTP 触发任务 调用方是主,OpenClaw Gateway API 是执行入口

Hermes 的对比:Hermes 也能处于"被调"位置——v0.13 已有 hermes acp 命令可作为 ACP server 供 VS Code, Zed, JetBrains 调用。但 OpenClaw 的"双向"更彻底——同一个进程同时暴露 MCP server + ACP server + HTTP API + WebSocket,且和 CLI Backend 模式并存,让它能在主/辅/中间层任意位置运转。

协议私有不是障碍——只要厂商对外稳定就能适配;而 OpenClaw 不仅消费别人的私有协议,自己还提供 MCP, ACP, HTTP 三层标准化暴露面,让别人也能消费它。这种"既能当主、也能当辅"的双向连接能力,是微内核架构 + Plugin SDK 抽象的红利在协议层的最直接体现。

6.5 三级 Compaction 策略

OpenClaw 的上下文压缩不是单一触发点,而是分三级响应:

级别 触发条件 位置 动作
L1: Pre-request 会话历史 > 阈值 run.ts 主循环开头 主动调 compaction.ts 生成摘要
L2: Timeout-triggered LLM 首 token 超时 且 prompt > 65% context run.ts 主循环 紧急压缩,用缩短的 prompt 立即重试
L3: Context overflow API 返回 context_length_exceeded run.ts 主循环 三级降级:auto-compact → 截断 oversized tool result → 抛错

L2 是容易忽视但很巧妙的一层——LLM 首 token 慢不一定是服务端慢,很可能是 context 太大导致 prefill 耗时过长。用"超时 + 大 context"双条件判断主动压缩后重试,比盲目切换 profile 更经济(不浪费冷却配额)。

Compaction 本身的实现也比 Hermes 精细一层:

6.6 Context Engine 契约——把"上下文管理"做成插件

src/context-engine/types.ts 定义了一个抽象,把"上下文怎么管"从 runtime 剥离:

interface ContextEngine { bootstrap?(ctx) // 会话初始化 ingest(msg) // 吸收一条 message ingestBatch?(batch) // 吸收一轮 turn afterTurn?(ctx) // 一轮结束后做后处理 assemble(budget) // 按 tokenBudget 组装 prompt compact() // 压缩 maintain?() // 分支重写 prepareSubagentSpawn?() // 子 agent 派生前 onSubagentEnded?() // 子 agent 结束后}

为什么这是亮点:它不把"上下文"当成静态的 message 列表,而是让 engine 自己决定:

这为未来接入 RAG-style 上下文管理(GraphRAG, LightRAG 之类)留好了接口——默认实现走"线性 + compaction",高级场景可以换成"图谱召回"。

6.7 Lanes——并发执行的分车道管控

// src/process/lanes.tsexport const enum CommandLane { Default = "default", Nested = "nested", // 内嵌 agent(如 dreaming review) Subagent = "subagent", // sessions-spawn 子 agent Cron = "cron", // 定时任务}

Lanes 不是简单的"线程池",而是命令调度的隔离通道:

这种"按调用来源分车道"的设计在同类 agent 框架里不多见。Hermes 是单一全局队列,所有命令排同一条线。

6.8 Bootstrap Budget——启动上下文的精细预算

Agent 启动时加载 SOUL.md / USER.md / MEMORY.md / AGENTS.md 等工作区文件时,不是"全部读进来",而是按预算裁剪:

这是典型的"把简单的事做对"——大多数框架把"启动加载哪些文件"写死在代码里,OpenClaw 把它做成可配置、可 hook、可缓存的三层结构。

6.9 Shell 命令执行与审批

核心问题:Agent 想执行 bash 命令时,命令到底在哪台机器上跑?用户怎么审批"是否允许执行"?

两种执行 Host

同一个 bash 工具有两种执行路径,取决于 Agent 的运行模式:

Host 何时使用 怎么执行
exec-host-node openclaw chat(本地 CLI 模式) Node.js spawn,在 agent 进程内直接执行
exec-host-gateway 通过 Gateway 运行(TUI, Control UI, Channel) 命令经 RPC 送到 Gateway,审批通过后才执行

为什么要分:Gateway host 可以跨机器代理执行(src/node-host/ 的 node exec)——Agent 跑在 macOS,shell 命令在远端 Linux 节点上执行。本地 CLI 模式不需要这层间接。

审批路径

两种 host 的审批方式不同,但共享同一套安全基线(evaluateShellAllowlist + detectCommandObfuscation + resolveApprovalAuditCandidatePath):

PTY 与脚本预检

6.10 Cache Trace——全链路可观测性

src/agents/cache-trace.ts 把每次 LLM 调用的上下文变化分 7 个阶段(session loaded → sanitized → limited → prompt before → images → stream context → session after)落盘到 ~/.openclaw/state/cache-trace/,可以精确定位 prompt cache miss 的原因。这是 production agent 才会关心的运维能力——Hermes 靠"冻结快照"兜底,OpenClaw 靠"全链路可追溯"定位。

6.11 Subagent Spawn——深度可控的子 Agent 委派

与 Hermes delegate_tool 的"阻止列表 + 默认深度 1"不同,OpenClaw 的子 Agent 机制更"系统化",被拆成十几个文件:

深度可控 vs Hermes 的默认 MAX_DEPTH=1:OpenClaw 把"递归策略"做成 per-session 的元数据——研究场景允许深度 3,客服场景强制 leaf,不需要改代码。

6.12 预算贯穿 Runtime——把稀缺资源显式量化

6.1 开头把 runtime 的三件事概括为"调度 + 容错 + 预算"。前两件事已经在 6.2–6.11 展开——预算这件事散落在多处,这里集中讲一次。

OpenClaw 对"预算"的理解不是"token 限额"那么窄,而是把 runtime 里的每一种稀缺资源都显式量化,并配一条超限后的降级路径。这和 Hermes 用单一 IterationBudget 计数器的风格形成鲜明对比:

稀缺资源 预算形式 超预算后的降级
上下文窗口 contextTokenBudget(按模型解析,Context Engine assemble/compact/afterTurn 都传入) 三级 Compaction 降级(L1 pre-request → L2 timeout-triggered → L3 overflow)
单次工具输出 MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3(30% 软限)+ HARD_MAX_TOOL_RESULT_CHARS = DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS = 16_000(16K 字符硬限,源码 tool-result-truncation.ts:40) head + tail 截断,最小保留 2000 字符,错误关键词(error, exception, traceback)优先保留 tail
启动上下文 bootstrap-budget.ts 的 maxChars + totalMaxChars + nearLimitRatio = 0.85 按优先级裁剪单文件 + 发 prompt warning 告诉 Agent "有文件被截了"
循环迭代次数 MAX_RUN_LOOP_ITERATIONS = resolveMaxRunRetryIterations(profileCount)(按 profile 数动态算,不硬编码) 抛 FailoverError,交给外层 runWithModelFallback 切模型
Overflow 压缩尝试 MAX_OVERFLOW_COMPACTION_ATTEMPTS = 3 放弃压缩,截断最大的 tool result;仍不行则报错
Timeout 压缩尝试 MAX_TIMEOUT_COMPACTION_ATTEMPTS(独立计数) 放弃压缩尝试,走 auth profile 轮换
凭证可用性 Cooldown 时间预算(rate_limit: 30s → 1min → 5min 分级递增) 轮换到下一个 profile;冷却结束后允许 probe 探针式重试
子 Agent 递归 spawnDepth + subagentRole: orchestrator/leaf 达到深度后强制 leaf(禁止再 spawn)
Lane 并发 Cron / Subagent / Nested / Default 四车道独立队列 超过 lane 并发上限进队列等待,不挤占其他 lane
Steer 速率 STEER_RATE_LIMIT_MS(父对子发送 steer 消息的节流) 超过间隔内的 steer 消息被丢弃

为什么这种做法重要:

  1. 防雪崩:一个持续超窗口的 turn 如果没有压缩次数预算,会无限触发"压缩→压缩不动→再触发"的死循环;Overflow budget = 3 是这条路径的 circuit breaker
  2. 让降级路径可证明:每种预算都对应一条明确的降级路径,所以 FailoverError 一旦抛出,调用链上任何一层都能判断"我还能做什么补救",不用靠 LLM 重新思考
  3. 可观测性的必然结果:因为每种预算都是显式变量(而不是隐式的"让进程自然崩溃"),Cache Trace(6.10)才能把每个阶段的资源消耗落盘,事后能复盘"这次失败是预算耗尽的哪一环"

这是 OpenClaw 风格和 Hermes 风格的分水岭——Hermes 靠单一的 90 迭代上限兜底(到上限就硬停),OpenClaw 把每种资源拆成独立预算并配对应的降级。前者简单可预测但粒度粗,后者精细但实现复杂度更高。

Agent Runtime 预算 5 层防御

OpenClaw 的预算不是单一值,而是"防爆 + 留余 + 自适应" 的 5 层防御组合 —— 4 种预算 × 4 路超预算决策 × 单工具双层硬限 × Bootstrap 双层 char 预算 × 截断告警自感知。

** 4 种预算类型 **

预算类型 控制什么 关键常量 单位
1. Context Token Budget 整个 LLM context 窗口大小 contextTokenBudget(动态,从模型 contextWindow 解析) token
2. Prompt Budget 留给 prompt 的部分(context - reserve) promptBudgetBeforeReserve token
3. Reserve Tokens 留给 output 的余量 DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR = 20_000 token
4. Bootstrap Char Budget 静态层 8 文件 push 注入预算 bootstrapMaxChars=20_000 / bootstrapTotalMaxChars=150_000 字符

注意 Token 和 Char 是两套预算——Bootstrap 用 Char(push 阶段还没进 LLM,只能按字符估算),其他用 Token。

核心约束公式(源码 preemptive-compaction.ts)

// 1. context 必须正整数const contextTokenBudget = Math.max(1, Math.floor(params.contextTokenBudget));// 2. reserve 必须非负const requestedReserveTokens = Math.max(0, Math.floor(params.reserveTokens));// 3. 计算最小 prompt budget — 取两者较小值const minPromptBudget = Math.min( MIN_PROMPT_BUDGET_TOKENS, // 8K 绝对下限Math.max(1, Math.floor(contextTokenBudget * 0.5)), // 50% 上下文);// 4. 实际 reserve 被截断 — 不能挤占 minPromptBudgetconst effectiveReserveTokens = Math.min( requestedReserveTokens,Math.max(0, contextTokenBudget - minPromptBudget),);// 5. 真正给 prompt 的预算const promptBudgetBeforeReserve = Math.max(1, contextTokenBudget - effectiveReserveTokens);

如果 reserve 想吞太多 → 自动让步给 prompt minPromptBudget**——保证 prompt 至少有 min(8K, 50% context) 可用。

反例:用户配置 reserveTokens=100K 但 contextTokenBudget=20K:

这个 clamp 防止配置错误导致 prompt 完全没空间。

SAFETY_MARGIN = 1.2(源码 compaction.ts:22)

export const SAFETY_MARGIN = 1.2; // 20% buffer for estimateTokens() inaccuracy

所有 token 估算都乘以 1.2:

const estimated = estimateMessagesTokens(messages) + ...;return Math.max(0, Math.ceil(estimated * SAFETY_MARGIN));

为什么乘 1.2:

很多 Agent 框架直接用 estimate 不留 margin,会随机触发 context overflow。OpenClaw 的 1.2 倍安全边际把"估算不准"这个已知风险直接消化掉。

超预算的 4 路决策

检查到 overflow 后不是只有一个动作,而是分情境路由:

let route: PreemptiveCompactionRoute = "fits";if (overflowTokens > 0) { if (toolResultReducibleChars <= 0) { route = "compact_only"; // 没工具结果可裁 → 只能 compact } else if (toolResultReducibleChars >= truncateOnlyThresholdChars) { route = "truncate_tool_results_only"; // 工具结果够裁 → 只裁工具 } else { route = "compact_then_truncate"; // 都做:先 compact,再裁工具 }}
场景 工具结果可裁量 选择路径 为什么
装得下 — fits 不动
装不下,没工具结果 ≤ 0 compact_only 只能压缩历史
装不下,工具结果够多 ≥ overflow × 1.5 + 512 token truncate_tool_results_only 工具截断更便宜
装不下,工具结果不够 之间 compact_then_truncate 双管齐下

设计取舍:优先裁工具结果——工具结果通常可重新获取(再跑一次工具就有了),对话历史压缩了就丢了语义。

单工具结果双层硬限(源码 tool-result-truncation.ts)

const MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3; // 软限:占 context 不超过 30%const DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS = 16_000; // 硬限:单次最多 16K 字符const HARD_MAX_TOOL_RESULT_CHARS = DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS;

双层防御逻辑:

工具返回 100K 字符 ↓软限检查:100K > context * 0.3?是 → 裁 ↓硬限检查:100K > 16K?是 → 裁到 16K ↓取两者较严的限制 → 16K

最小保留 + error 关键词 tail 保留:

Bootstrap 截断告警注入 LLM(自感知机制)

源码 bootstrap-budget.ts 的 appendBootst…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/Openclaw/2026052927413.html