第 13 章 实战拆解：OpenCode、OpenClaw、Hermes、Claude Code 与 Codex

13.1 比较范围：先分清产品、模型和 Harness

资料核对：2026-09-26。 本章比较公开文档与可读源码中的系统设计，不给未经同条件测试的编程能力排名。Claude Code 与 Codex 以官方公开接口为依据；源码分析只覆盖下面明确链接的文件，不推断未公开的服务实现。版本升级可能改变默认配置和目录。

OpenCode、Claude Code、Codex 的主要入口是仓库开发；OpenClaw 与 Hermes 也能读写代码和运行测试，但其设计还覆盖消息渠道、持续任务和个人助理。会用终端是共同能力，任务生命周期才是关键区别。 Hermes Agent 指 Nous Research 的 Agent 项目，不等同于 Hermes 模型系列。

入口资料：OpenCode [导读]、OpenClaw 架构 [导读]、Hermes 架构 [导读]、Claude Code 工作原理 [导读]、Codex CLI [导读]。以下横向表是对这些资料和各节引用的归纳；“适合”与“工程代价”是基于架构的判断。

13.2 共同技术骨架：一条工具循环，几种系统边界

入口 → 选工作区与会话 → 构造上下文 → 模型生成动作
                                   ↓
              校验工具与权限 → 执行 → 记录结果与状态
                                   ↓
                      新观察 → 继续 / 等待 / 终止

五家都可以放进第 11 章的 harness 思路里分析，但组件的具体实现不同。读代码时沿着以下六个问题追踪，避免只看系统 prompt：

技术判断：LSP 诊断能提供类型与引用信息；测试提供可执行反馈；向量检索只是代码定位的一种路径。一个 Agent 没有向量数据库，也可能通过文件名、文本搜索和逐步读取理解仓库。工具丰富程度不能直接推出修复成功率。

13.3 OpenCode：可配置模型与客户端分离的编程系统

Server 文档 [导读]说明 TUI 是客户端，后端提供 HTTP API 与 OpenAPI 描述。这把界面交互和任务执行分开，便于接不同客户端或程序化入口。模型/provider 可配置，适合研究“同一个 harness 换模型”的差异；各 provider 的工具调用兼容性仍需检查。项目入口 [导读]提供初始化与仓库规则文件的使用方式。

Agents 文档 [导读]区分主要交互角色和子任务角色；Build 面向实现，Plan 对修改和命令施加限制。角色名本身不是权限保证，应检查实际 permission 配置。Permissions [导读]提供 allow/ask/deny 与动作匹配；这些是应用层决策，不应据此假设任意 shell 子进程已被 OS 隔离。

本章读取的源码快照是 696f41bc8e75（dev 分支，2026-09-26 获取）：

上下文压缩有独立配置，不能假定裁剪总是开启，参见 Compaction 配置 [导读]。LSP [导读]为诊断提供入口；Skills [导读]允许按需加载流程知识。

可以借鉴：流式状态机、主/子会话、可替换 provider、压缩与重试的分层。需要验证：重复动作检测是否误判合法重试；换模型后 schema、错误与 token 预算是否仍匹配。后台子任务出现在源码中，不代表每个发行版或配置都默认开放。

13.4 OpenClaw：Gateway、消息路由与持续运行

Gateway 架构 [导读]把长驻服务放在中心：消息渠道接入、控制客户端连接、事件流与任务运行围绕 Gateway 组织。它的额外问题是“谁从哪个渠道发来消息、该进入哪个会话、回复送到哪里”。这与一次本地修补丁的生命周期不同。

消息渠道 / 控制客户端 / 自动触发
                ↓
       Gateway：身份、路由、会话、队列
                ↓
         所选 Harness / Agent runtime
                ↓
           工具执行与状态保存
                ↓
       终态事件 + 来源渠道的回复投递

Multi-agent routing [导读]与子 Agent [导读]属于不同问题：前者决定任务进入哪个 Agent，后者处理一次任务的委派。多个独立助理并不自动等于它们共同求解同一个问题。

源码快照 239bae9aa9ea（2026-09-26 获取）的运行时架构说明 [导读]表明：内置 runtime、provider transport、session 与 harness registry 分层；内置核心位于 packages/agent-core/，也能注册其他 harness。因此，旧资料中的“核心就是外部 Pi runtime”不能直接描述这个快照。实际 runtime 选择仍取决于配置和 provider 路由。

同一快照的 Agent loop [导读]记录了会话队列、运行超时与写入者校验：旧 run 被替代后，不能用过期身份提交会话历史。这是持续服务的并发一致性设计。任务执行完成、记录终态和成功投递回复应分别观察，不能看到一段 assistant 文本就宣布整个任务结束。

Memory [导读]包含 Markdown 长期信息与日记式记录；Agent runtime [导读]当前说明活动会话历史存于 SQLite。记忆文件与会话数据库职责不同，不宜把历史 JSONL 路径当作永久存储规范。Sandboxing [导读]明确沙箱需配置，Gateway 本身仍在宿主侧，工具执行才移动到所选后端。

可以借鉴：入口与执行分离、身份路由、队列、写入一致性、投递状态。工程代价：增加渠道连接、后台调度和运维；如果只要修一个本地仓库问题，这些能力未必带来收益。

13.5 Hermes Agent：持久记忆、流程复用与工具后端

架构文档 [导读]围绕 AIAgent 组织入口、上下文、工具发现、执行和会话持久化；终端可以接本地或隔离/远端后端，会话搜索使用 SQLite 与 FTS5。换终端后端改变的是动作发生在哪里，不等于模型运行在同一台机器。

Persistent Memory [导读]将环境事实与用户资料分到 MEMORY.md、USER.md，还支持历史会话搜索。一个值得关注的细节是：会话启动时注入的记忆快照保持稳定，后续写入落盘后由新的会话读取。这有助于保持 prompt 前缀稳定，但也意味着“写成功”与“旧会话已经读到更新”是两件事。

Skills System [导读]让 Agent 保存和改进可复用流程，按需读取内容与参考资料。这里的“自我改进”主要可以体现为记忆和技能文件的变化，不能直接解释为每次对话都训练了模型权重，也不能假定一定提高了下次任务成功率。

源码快照 d0288be5b333（2026-09-26 获取）：

Security 文档 [导读]分别描述用户授权、命令审批、写入约束和容器隔离。应用侧命令判断与后端隔离要分别检查，选择 local 后端不能自动得到容器边界。

可以借鉴：事实、偏好与操作流程分开存；稳定输入前缀；将复杂成功流程转成 skill 后再评测。需要验证：错误经验被重复使用、记忆过期、技能误触发，以及保存与加载是否真的发生。

13.6 Claude Code：围绕开发反馈组织上下文

工作原理 [导读]把闭环描述为收集上下文、行动和验证；内置文件、搜索、执行等工具接入模型。项目记忆 [导读]区分人维护的 CLAUDE.md 与自动保存的经验。持续规则应放进可重新加载的资料，不能只依赖早期聊天内容。

Subagents [导读]将专门任务放入独立上下文，并允许配置工具和角色。对于仓库修复，一个探索子任务可以返回关键路径与证据，让主会话集中在需求、实现和验收；这种组织收益需要与新增调用费用一起测量。

Sandboxing [导读]区分运行前权限决策与进程运行时隔离：沙箱化 shell 在 macOS/Linux 等平台利用 OS 机制限制文件与网络访问。它并不等于所有 MCP 工具或远端服务都被同一层限制。

该产品公开说明了会话恢复、自动压缩与文件修改检查点。文件回退不等于外部动作回滚：API 调用、部署或数据库更改仍需单独处理，见工作原理中的检查点说明 [导读]。本章不把文档中的行为反推成某种未公开的压缩算法或训练实现。

可以借鉴：将搜索、改动、验证放进同一循环；用规则、经验与子任务控制上下文。需要验证：压缩后约束是否保留、检查点覆盖哪些改动、所选权限模式与 sandbox 配置是否符合实际任务。

13.7 Codex：工作区执行、审批隔离与结构化客户端协议

Codex CLI [导读]在本地仓库中读取、修改并运行开发工具，也提供会话恢复、审查、非交互执行和外部工具连接。CLI 是客户端/运行时产品，Codex 模型是策略来源，云端任务是另一个执行环境；三者不能混成一个配置。

AGENTS.md [导读]规定项目指导文件的发现与层级；Skills [导读]按名称/描述发现，使用时读取完整流程。它们都影响当前上下文，规则文件不是文件系统访问控制。Subagents [导读]把探索与日志等工作移出主上下文，返回结果供主 Agent 合并。

Agent approvals & security [导读]明确区分 sandbox 与 approval：前者限制命令实际能访问什么，后者决定何时需要批准。只改成“不询问”不会自动获得权限。OS 实现随平台和版本变化，应核对具体配置；网络、可写目录和外部工具的边界也需分别确认。

App-server [导读]提供双向、基于 JSON-RPC 的客户端协议，组织 thread、turn 与事件；审批可作为服务端发起的请求交给客户端响应。这是把界面与执行连接起来的接口，不等于 MCP。文档标注了实验性 transport，接入时要按所用版本生成 schema，不能把实验传输视为稳定生产接口。

同一 app-server 文档 [导读]还暴露 thread/compact/start 与 contextCompaction 事件：请求被接受和压缩完成是不同状态，客户端需跟踪完成事件。这提供了可观察的上下文管理接口，并未公开承诺摘要永远无损。

客户端：发起 thread / turn，展示执行事件，接收审批请求
                           ↕
           app-server：运行与事件协议
                           ↕
                Harness 与工具执行环境

可以借鉴：把任务事件、工具执行和审批变成显式协议；将执行权限与是否询问分开；用非交互入口构建可复现流程。需要验证：CLI、桌面与云端是否有相同的环境、工具和权限；后台进程的成功退出也不能代替需求验收。

13.8 横向对比：技术路线与工程代价

下面依据 13.3–13.7 的来源归纳，描述关注点，不表示其他产品“没有”某项能力。

三个容易混淆的点：上下文隔离不自动等于文件隔离；会话恢复不自动等于外部动作幂等；支持相同 Skills 格式不保证有相同工具名、加载规则和审批语义。移植时应检查流程的运行条件，而不是只复制文件。

13.9 选型：按任务边界做判断

以下是基于上述架构的选择思路，不是质量排名，也没有在本章实测五家产品。

可以组合入口与执行层，例如消息网关把任务交给编程 harness；这会引入两层状态和权限。此时必须确定谁拥有模型循环、谁执行工具、谁记账、谁宣布结束，避免双方同时压缩或重试同一任务。

开源程度只说明哪些代码能被检查或改造，不直接说明模型权重是否开放、服务是否离线、账号授权是否可互换。跨产品使用模型时还要核对官方支持的接入路径。

13.10 同一道修复任务，怎样做公平对比

实验设计，不是已跑出的结果。 准备相同仓库快照和一组任务：小 bug、跨文件修改、陌生依赖、测试失败后的恢复、长任务中断。由独立验收器检查补丁，开发反馈与隐藏验收分开。

1. 固定初态：独立工作区、相同依赖/测试命令、相同网络与可写范围；明确初始记忆、Skills、MCP 和插件集合。
2. 做两类比较：产品默认配置对比测“拿来用”的表现；可配置系统尽量固定同一模型对比 harness。不能强行给所有产品配置同一模型，结果应分别解释。
3. 统一预算：设置费用、墙钟时间和尝试次数上限。主 Agent、子 Agent、压缩、辅助审批或摘要产生的开销都纳入记录；部分数据不可得时明确标注。
4. 记录验收：报告隐藏测试与需求通过率、无关改动、人工接管、违规动作、成本和时延。测试数量不能充当完成率。
5. 检查恢复：在指定工具步骤后中断，重启并检查目标、文件版本、重复动作和未决状态；每个任务重复运行，报告波动。

对 Hermes 等强调知识复用的系统，另设“首轮冷启动”与“已验收经验复用”两组。复用组保留的知识不能包含测试答案；否则测到的是泄漏，而不是流程学习。生产选型还需比较真实配置，不能只看消融实验。

13.11 源码阅读顺序与面试复盘

面试追问：为什么用相同模型的两个 Agent 修复率不同？从工具表达、检索路径、输出裁剪、上下文压缩、权限与环境、预算、反馈选择和完成判断拆开归因，再设计只改一项的实验。

本章交付物：五家架构对比表、一条实际失败轨迹、一个机制的源码解释、一份注明版本和预算的任务对比报告。源码中存在某项功能只能证明机制可见；产品效果必须由可复现任务来证明。