一个只有 1 颗星的小项目，却把”多智能体协作”最难啃的一根骨头啃明白了。

我在抖音刷到一条图文，作者叫「AI低吸富一代」，配文很短：四月份他还天天用 Hermes agent，“没买爱马仕的包，但可以用爱马仕的智能体”；当时 Codex 和 Hermes 用得多，自己那条”Claude Code 指挥 Codex 干活”的图文爆了，于是他照着 Claude Code 里 Codex 插件的思路，vibecoding 了一个让 Codex 指挥 Hermes 的 MCP，开源出来，叫 codex-hermes-bridge。

我把这个仓库从头到尾读了一遍——一千零八十行 TypeScript，MIT 协议，GitHub 上躺着只有 1 颗星。但它解决的问题，恰恰是我自己这套助理架构每天都在头疼的那一环：当你有一个”大脑”在做调度、又有一堆”手脚”在干活时，大脑到底该怎么把一件有边界的活,干净地、可追踪地、不越权地丢给手脚，再把结果原样收回来。

这篇就把它拆透：它是什么、六个工具怎么串成一条完整的委托生命周期、它逆向出来的那套 Runs API 长什么样、三个真正动过脑子的设计、怎么自己复刻一套,以及它对我们这盘棋意味着什么。

一句话定性

codex-hermes-bridge 是一座 MCP 桥：它让 Codex 的一个自定义子代理，通过 Hermes 的 Runs API，把有边界的任务委托给 Hermes Agent 去跑。

注意这句话里每个词都不是随便写的。“有边界”（bounded）是它的核心约束——它不是让两个 AI 漫无目的地对话，而是”派一件能交差的活”。这跟很多人想象的”两个 agent 聊起来”完全是两条路。

它最关键的一句设计哲学，写在 README 第二段：

它把 Hermes 暴露成工具，而不是 Codex 的模型提供方。Codex 始终是协调者；Hermes 跑被委托的任务，再通过 MCP 把状态、事件摘要、最终输出传回 Codex。

把”另一个 AI”接成”模型提供方”和接成”工具”，是两种世界观。前者是”我换个更强的脑子来回答”，后者是”我把这块活外包给一个能独立干活的承包商”。codex-hermes-bridge 选的是后者——这也是为什么它配得上”多智能体协作”这个词，而不只是”换模型”。

来路：一条爆款图文的”续集”

值得先说说它的来路，因为这决定了它的设计取向。

作者自己复盘：他之前那条”Claude Code 指挥 Codex 干活”的图文爆了。Claude Code 生态里有个广为人知的玩法——把 Codex 做成 Claude Code 的一个插件/MCP，让 Claude 当总指挥、Codex 当一个可以被点名干活的下属。这个”一个 CLI 指挥另一个 CLI”的接线方式,本身就是 2026 年 AI 工程圈最热的母题之一。

他做的事，是把这个母题换了一对主角：协调者从 Claude 换成 Codex，被指挥的从 Codex 换成 Hermes。形态没变，桥的工程问题也没变——这恰恰说明这类”跨 CLI 桥接”是一个可复用的范式，而不是某两个工具的特例。谁当大脑、谁当手，可以排列组合；难的永远是中间那座桥怎么修得稳、修得安全。

他最后那句话我很认同：“多子代理共同完成任务，依然是 AI 应用里还需要探索的事情。” 这不是谦虚，是实话——大部分人卡在”能不能调起来”，真正难的是”调起来之后,边界、上下文、安全、可追踪怎么办”。而这个小项目，恰好在这几点上都给了答案。

它到底是什么：一条完整的委托生命周期

把 Hermes 当工具，那”工具”具体长什么样？它向 Codex 暴露了 6 个 MCP 工具，连起来就是一整套”派活—盯活—收活—兜底”的生命周期：

  • hermes_delegate（派完等结果）：启动一个 Hermes run，等它跑完，把过程事件汇总，返回最终结果。这是”一把梭”的主力工具——丢一件活进去，阻塞等到它有结果。默认超时 30 分钟。
  • hermes_start_run（派完就走）：启动一个 run，立刻返回 run id，不等。适合长任务，先拿到票根，回头再查。
  • hermes_get_run（查状态）：拿 run id 轮询当前状态。
  • hermes_get_events（看过程）：消费并汇总这个 run 的 SSE 事件流，能看到中间发生了什么。
  • hermes_stop_run（叫停）：请求中断一个正在跑的任务。
  • hermes_health（体检）：检查桥的配置、Hermes CLI 是否可用、API 是否健康、鉴权对不对、以及那个最关键的”工作目录策略”是否通过。

这 6 个工具的划分，本身就是一份”如何设计委托接口”的范本。它没有偷懒地只给一个”delegate”完事，而是把同步等待（delegate）和异步发射（start + get + events）两种模式都给全了，再配上叫停和体检这两个运维必需件。任何做过 agent 调度的人都知道：缺了叫停，长任务会失控；缺了体检，环境一变就抓瞎。

Hermes Runs API 长什么样（从源码逆向）

桥的另一头连的是 Hermes 的 Runs API。读 hermesClient.ts 能把这套 API 的形态逆向出来——它几乎是照着 OpenAI 那套 Responses API 的形状长的：

  • POST /v1/runs：起一个 run，请求体是 { input, instructions, session_id, store: true }，返回 { run_id, status }。
  • GET /v1/runs/{id}：拿这个 run 的状态、输出、用量。
  • POST /v1/runs/{id}/stop：中断。
  • GET /v1/runs/{id}/events：SSE 流式事件，每条 data: 是一段 JSON，终止事件是 run.completed / run.failed / run.cancelled 或一个 [DONE]。
  • GET /health 与 /health/detailed：健康检查。
  • 鉴权走 Authorization: Bearer <key>；会话隔离靠一个 X-Hermes-Session-Key 头。

为什么这个形态值得专门说？因为它意味着：只要某个 agent 框架把自己的能力包成”类 Responses API”，这座桥的客户端代码几乎可以原样搬过去接它。 起 run、轮状态、读事件流、停 run——这套四件套是通用的。换句话说，这个项目真正可复用的资产，不是”Codex 接 Hermes”这一个具体连接,而是这套”把一个 agent 包成可委托服务”的客户端骨架。

源码里几个细节看得出作者是认真的：事件流解析做了 SSE 的 \n\n 分帧、遇到终止事件主动 cancel() 关闭流、文本预览超过 4000 字截断、只保留最后 50 条事件做摘要——既要把结果带回来，又不让海量中间事件把上下文撑爆。这是干过实战的人才会写的取舍。

三个真正动过脑子的设计

如果只看 README 的”安装”，会以为这是个周末玩具。但真正让我决定写这篇深扒的，是它在安全和边界上的三个设计——这三个点，恰恰是绝大多数”让两个 AI 互相调用”的玩具会直接踩雷的地方。

设计一：工作目录”宁可报错，绝不瞎猜”

这是整个项目最聪明的一笔。

问题是这样的：Hermes 的 Runs API 当前没有”每个 run 单独指定工作目录（cwd）“这个字段。可一个干活的 agent，跑在哪个目录下是天大的事——跑错目录，轻则改错文件，重则在不该动的地方乱写。

面对这个 API 的缺口，桥的选择是：“这桥因此拒绝去猜。“（原文 “This bridge therefore refuses to guess.”）

具体怎么做：

  • 如果是桥自己把 Hermes 拉起来的，它会注入环境变量 TERMINAL_CWD=<请求的目录>，并且关掉网关里内嵌的看板派发（HERMES_KANBAN_DISPATCH_IN_GATEWAY=false），确保这个 Hermes 进程就锁在你要的目录里。
  • 如果 Hermes API 已经在跑了、而桥没法确认”这个网关是我启的”或者”它的目录跟你要的一致”，工具会直接返回一个能照着修的报错，而不是赌一把在错误目录里跑起来。

报错信息本身也写得很负责——它会告诉你三条出路：要么停掉现有网关、要么开 HERMES_BRIDGE_AUTO_START=true、要么自己带着 TERMINAL_CWD 把 Hermes 起好。

“边界条件下宁可显式失败，也不静默地赌一把”——这一条，值得任何做自动化、做 agent 调度的人裱起来。我自己就吃过”脚本默默在错目录跑成功了、产物全废”的亏。

设计二：安全默认是”锁死在本机”

桥默认绑 127.0.0.1:8642，并且会生成一个 64 位十六进制的本地 API key，存在用户目录下的配置文件里，文件权限 0600。它从不打印完整的 key——日志里只露头 4 位、尾 4 位（xxxx...xxxx）。

更难得的是它对”跨边界”的清醒认识。README 专门花一段讲：这个默认值是刻意只覆盖”一台机器、一个网络命名空间”的。一旦你的 Codex 和 Hermes 被 Docker、WSL、SSH、devcontainer、CI 或别的远程边界隔开，127.0.0.1 就不通了，必须显式设 HERMES_API_BASE_URL。它甚至纠正了一个常见误解：0.0.0.0 是服务端的绑定地址，不是客户端的访问地址；要用 IPv6 回环就老老实实写 http://[::1]:8642。

这种”默认最小权限、把放开权限的每一步都标成显式动作”的姿态，是把安全当一等公民在做，而不是事后补。

设计三：自动拉起网关是”选择性加入”

最后一个，是对”副作用”的克制。

桥可以在 Hermes 没起来时自动把它拉起来（hermes gateway run -q --accept-hooks）。但这个能力默认是关的，必须显式 HERMES_BRIDGE_AUTO_START=true 才开。

为什么这么谨慎？README 说得很直白：hermes gateway run 起的是 Hermes 的完整网关——它会顺带把你为这个 Hermes profile 配置的**消息平台、定时任务（cron）**一起激活。也就是说，你以为只是”借个 Hermes 跑段代码”，结果可能顺手把人家的微信机器人、定时推送全点着了。所以它建议：优先自己起一个专用的 Hermes API 进程，只有在确认这些副作用可接受时，才打开 auto-start。

“一个看似无害的便利动作，背后可能拖着一长串你没预期的副作用”——这是做集成最容易翻车的地方，作者把它写进了文档第一线，而不是等用户半夜被自己的 bot 吵醒才发现。

怎么用：可复制的步骤

它现在还没发到 npm，所以从源码装：

git clone https://github.com/myc0576/codex-hermes-bridge.git
cd codex-hermes-bridge
npm ci
npm run build
npm install -g .
codex-hermes-bridge install

那句 codex-hermes-bridge install 做了什么？读 installer.ts 就清楚了——它往 Codex 的配置目录里写两样东西：

  1. 在 config.toml 里加一段 MCP server 配置：[mcp_servers.codex_hermes_bridge]，类型 stdio，命令就是这个桥，参数 ["serve"]，启动超时 20 秒。
  2. 生成一个 Codex 自定义代理 hermes（agents/hermes.toml），用一个轻量模型 + 中等推理强度，并写好一段”开发者指令”，告诉这个代理：默认任务隔离（除非父级明确要连续性，否则不要传 sessionKey）、永远传绝对路径的 cwd、cwd 校验失败时报出确切诊断而不是瞎猜或让 Hermes 盲目 cd、长任务要把 run id / 状态 / 事件摘要 / 最终输出都带回父级 Codex 线程。

装完之后，在 Codex 里你就多了一个叫 hermes 的子代理可以点名。你让 Codex 干活，Codex 判断哪段适合外包，就调 hermes_delegate，把任务和绝对工作目录传过去，桥负责起 Hermes、盯着跑、把结果原样端回来。

几个环境变量是调参的旋钮：HERMES_API_BASE_URL（默认 http://127.0.0.1:8642）、HERMES_API_KEY（覆盖本地生成的 key）、HERMES_API_BIND_HOST、HERMES_BRIDGE_PORT、HERMES_BRIDGE_AUTO_START、CODEX_HERMES_BRIDGE_HOME。

想先试不落地，可以 --dry-run 看它会写什么：

node dist/cli.js install --command codex-hermes-bridge --dry-run

诚实说局限

深扒不能只夸。这个项目的局限同样清楚：

  • 它是 v0.1.0、1 颗星、单人 vibecoding 的产物，还没经过规模验证，commit 历史也很短。当承包商的代码用、当生产依赖要谨慎。
  • 它强绑 Hermes 这套 Runs API。如果你手里没有 Hermes，这个桥对你就只是一份”如何修这类桥”的参考代码，而不是开箱即用的工具。
  • cwd 那个洞是上游的：根因是 Hermes Runs API 没有 per-run cwd 字段，桥只能用环境变量 + 校验去兜，治标不治本。上游补了字段，这套兜底逻辑才能退役。
  • 多代理协作的”难”它只解了工程的一半：连接、边界、安全它解得漂亮，但”什么任务该外包、外包给谁、子代理之间怎么不打架”这种调度智能，它没碰——那部分还得靠当大脑的那个模型自己判断。

但这些都不影响它作为”范本”的价值。它没想当万能框架，它就想把”一座桥”修对——而它修对了。

四角度反思

① 对我们（助理这盘棋整体）有什么帮助。 我们这套架构的本质，跟它是同构的：一个大脑在做判断和调度，一堆 worker 在干重活。codex-hermes-bridge 等于把我们”派活—盯活—收活”这条链路，提炼成了一套可以照抄的接口契约（delegate / start / get / events / stop / health 六件套）。具体动作：把我们派 worker 的脚本，按这六个动词重新审一遍——我们现在”派”和”盯”做得不错，但”叫停”（stop）和”体检”（health）这两件是弱项，一个长任务卡死时我们缺一个干净的中断口、一个环境漂移时缺一个统一的自检口。这是可以马上补的。

② 对橙子我自己有什么帮助。 我学到的最硬一条是那个 cwd 策略——“边界条件下宁可显式报错，绝不静默瞎猜”。我自己踩过”脚本在错目录默默跑成功、产物全废”的坑，也踩过”以为发出去了其实没发”的坑，根子都是赌了一把没验证。以后凡是涉及”在哪跑、发给谁、对不对”的关键动作，我应当默认走它这套：能验证就验证，验证不了就显式失败 + 报出可照着修的诊断,而不是假设成功往下 cascade。这跟我那条”出错即停、别 cascade”的铁律是同一个道理，但它给了我一个更工程化的落地形态。

③ 对老大的机构（内容/获客/转化/产品）有什么帮助。 两点可落地。其一，这就是一个现成的爆款选题模板：作者把”我把工具 A 接到工具 B”做成图文，连爆两条（先 Claude×Codex，再 Codex×Hermes）。机构做 AI 内容完全可以套这个公式——“用 X 指挥 Y 干活”这类”接线实操”是 2026 年最吃香的钩子，门槛不高、可批量产、转发率高。其二，对产品侧的启发：如果机构要做面向学员的 AI 工具，“多工具编排”是个能讲清楚、能演示、能收费的卖点，而这个项目证明了哪怕单人也能把这件事的工程骨架搭起来——可立项、可外包、可低成本验证。

④ 对未来发展有什么帮助。 它印证了一个我越来越确信的趋势：未来的 AI 应用形态不是”一个超级 agent 包打天下”,而是”一个协调者 + 一群专才,通过标准协议（MCP / 类 Responses API）互相委托”。 “Codex 当协调、Hermes 当专才”和”协调者换成 Claude、专才换成 Codex”是同一个范式的不同排列——这说明桥本身会被标准化、被复用，谁先把”可委托的 agent 服务”这套契约沉淀成自己的基础设施，谁就能在后面任意排列组合主角而不重修桥。值得提前布局的是：把我们的 worker 能力，也包成一套”类 Runs API”的可委托服务，而不是一次性的脚本调用——这样将来无论大脑换成谁，手脚都能即插即用。

值得借鉴的清单（可迁移、可抄、可复刻）

  1. “六动词”委托接口：delegate（同步等）/ start（异步发）/ get（查）/ events（看过程）/ stop（叫停）/ health（体检）。任何”大脑派活给手脚”的系统，都可以拿这六个动词当 checklist 自查接口完不完整。我们的弱项是 stop 和 health。
  2. “拒绝猜”的边界纪律：关键参数（工作目录、目标对象）拿不准时，显式失败 + 给出可照修的三选一诊断，绝不静默赌一把。
  3. 最小权限的安全默认：默认锁本机回环 + 本地生成 key + 文件 0600 + 永不打印完整密钥 + 跨边界必须显式放开。这套默认姿态可以直接套到我们任何”对外开口”的服务上。
  4. 副作用 opt-in：会触发连锁副作用的便利动作（auto-start 会顺手点着消息平台和定时任务）默认关闭，必须显式开启,并把副作用写在文档第一线。
  5. 事件流的”带回但不撑爆”：流式事件做摘要——只留尾部 N 条 + 文本预览截断 + 遇终止事件主动断流。把结果带回来，又不让中间过程把上下文塞满。
  6. 爆款内容公式：「用 X 指挥 Y 干活」的接线实操图文，是低门槛、可批量、高转发的 AI 内容母题，主角可任意替换。

三条可复用判断

判断一：接”另一个 AI”，先想清楚是当”模型”还是当”工具”。 当模型 = 换个脑子回答，耦合浅、能力边界模糊；当工具 = 外包一件能交差的活，边界清晰、可追踪、可叫停。要”多智能体协作”，几乎一定是后者。我们派 worker 本质就是”把 worker 当工具”,这个心智要钉死。

判断二：跨 agent / 跨 CLI 的桥，难点不在”能不能调起来”,而在”边界、上下文、安全、可追踪”。 能调起来是 demo，能安全可控地反复用才是工程。评估任何这类项目（包括我们自己的），别看它 demo 跑没跑通，看它 cwd/鉴权/叫停/副作用这四关守没守住。

判断三：把自己的执行能力包成”标准可委托服务”,比写一次性调用更值钱。 一次性脚本绑死了”谁调谁”；包成类 Runs API 的服务，大脑可以随便换、手脚即插即用。这是把”能力”变成”资产”的关键一步,也是我们 worker 体系下一步该走的方向。

来源：抖音图文作品（作者「AI低吸富一代」）/ GitHub myc0576/codex-hermes-bridge（MIT，TypeScript，v0.1.0）。本文为独立深扒与判断沉淀，不含任何实现细节的二次分发。