Ouroboros × OpenCode 双路径集成指南：Subagent Bridge 插件与子进程运行时实战

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具

本指南讲解如何在 Ouroboros 中以OpenCode作为运行时后端：日常交互推荐 Subagent Bridge 插件（MCP 工具自动扇出为原生 Task 面板），无人值守场景使用opencode run子进程运行时。读完你将掌握两种模式的安装、配置、互斥选型、权限透传、故障排查，以及桥插件与子进程底层的源码级实现机制。

Ouroboros 与开源多 Provider AI 编程代理OpenCode的集成并非单一方案，而是两条互补路径：一条在交互式 OpenCode 会话内运行（Subagent Bridge 插件，推荐默认），另一条以非交互子进程方式驱动opencode run（用于 CI / 脚本化自动化）。两条路径共享同一套 spec-first 工作流骨架——Seed 文件、验收标准、评估原则与确定性退出条件完全一致，区别仅在于执行载体。

两种路径的定位与选型

两条路径都无需在ouroboros-ai基础包之外安装任何额外 Python SDK——OpenCode 运行时适配器已内置在基础包中。官方建议：日常交互选插件，自动化选子进程。模型层面，OpenCode 支持其配置的 Provider 提供的任何模型；Ouroboros 工作流建议使用擅长多步 Agentic 编码任务的前沿模型（如 Claude Opus、GPT-5.4 或同级模型）。

前置条件

• OpenCode已安装、配置并位于PATH（安装步骤见下文）；
• OpenCode 内已配置 Provider：运行opencode完成首次配置，或使用opencode providers auth <provider>；
• Python >= 3.12。

关键注意点：OpenCode 自行管理 Provider 认证。你不需要为 Ouroboros 设置ANTHROPIC_API_KEY或OPENAI_API_KEY环境变量——OpenCode 通过自己的配置文件~/.config/opencode/opencode.jsonc（或opencode.json）内部处理凭证。

安装 OpenCode

OpenCode 以独立二进制分发，官方推荐安装器或 npm 两种方式：

# 推荐：官方安装器 curl -fsSL https://opencode.ai/install | bash # 备选：npm npm i -g opencode-ai@latest

验证安装：

opencode --version

安装后运行一次opencode完成首次 Provider 设置（选择 Provider 并认证）。

安装 Ouroboros

完整的安装选项（pip、one-liner、源码安装）与首次引导见 Getting Started。基础ouroboros-ai包已包含 OpenCode 运行时适配器，无需安装任何 extras。

平台支持

OpenCode 运行时适配器面向 Linux、macOS 与 Windows（WSL 2）设计。OpenCode 本身支持 macOS 和原生 Windows；Ouroboros 的路径处理与子进程分发是可移植的。

配置：ouroboros setup --runtime opencode

执行ouroboros setup --runtime opencode即可配置 OpenCode 集成。配置时必须在两种互斥模式中二选一：

为什么互斥：如果 Ouroboros MCP 工具在opencode run子进程内被调用，全局注册的插件也会触发——造成重复的子智能体分发、浪费 token。只能二选一。若刻意在同一台机器上同时打通两条路径，可分别以不同--opencode-mode运行两次ouroboros setup，并接受额外的 token 开销。

ouroboros setup --runtime opencode # 交互式选择 ouroboros setup --runtime opencode --opencode-mode plugin # OpenCode 内使用（默认） ouroboros setup --runtime opencode --opencode-mode subprocess # 无人值守 CI ouroboros setup --runtime opencode --non-interactive # 接受默认值（plugin）

各模式实际安装的内容

plugin 模式

• 在<opencode_config_dir>/plugins/ouroboros-bridge/ouroboros-bridge.ts写入 Bridge 插件（原子写入、内容哈希，未变更则 no-op）；
• 在~/.config/opencode/opencode.jsonc或opencode.json写入插件条目（自动去重过期条目）；
• 在同一文件中注册 Ouroboros MCP server；
• 不修改 Claude SDK MCP sidecar，其 MCP 1.x profile 保持隔离。

subprocess 模式

• 在~/.ouroboros/config.yaml写入orchestrator.runtime_backend: opencode；
• 在同一文件中写入orchestrator.opencode_cli_path: <自动探测路径>；
• 在同一文件中写入llm.backend: opencode。

.jsonc文件会被重写为纯 JSON（去除注释）以保证兼容性。

文件落点一览

OpenCode 工作流的模型选择在OpenCode 自身中配置，而非config.yaml。

源码佐证：setup 的失败闭合与互斥清理

从 setup.py 的_setup_opencode实现可以看到两条细节：

1. plugin 模式 fail-closed：先安装插件、注册 MCP、注册插件条目，全部成功后才持久化 config；任何一步失败都不会留下"处于 plugin 模式却没有可用 bridge"的半残状态。
2. subprocess 模式的互斥清理：写入 config 后会调用_cleanup_plugin_artifacts()移除插件模式遗留物，避免双路径同时激活造成重复分发。注释中明确说明：没有runtime_backend: opencode，MCP 的should_dispatch_via_plugin()门控永远返回 False，plugin 分发不会激活——这正是两种模式必须互斥的底层原因。

配置文件的位置解析逻辑集中在 opencode_config.py：依次检查OPENCODE_CONFIG_DIR环境变量、opencode debug paths命令报告（避免把版本相关的平台假设写死在代码里）、XDG 默认路径（$XDG_CONFIG_HOME/opencode或~/.config/opencode）、Windows 的%APPDATA%\OpenCode。

路径 1：Subagent Bridge 插件（推荐）

插件挂钩 OpenCode 的tool.execute.after事件。当 Ouroboros MCP 工具返回_subagent/_subagents信封时，插件执行三步：

1. 为每个 subagent 派生一个独立子会话（client.session.create+client.session.prompt）；
2. 将subtaskpart 补丁进父消息，使子会话在原始工具调用下方以内联Task 面板形式渲染；
3. 最多并发扇出MAX_FANOUT = 10个子会话——每个子会话拥有全新的 LLM 上下文（无跨 persona 锚定偏差）。

多 persona 示例：

ouroboros_lateral_think persona="all" → hacker (子会话, Task 面板) → researcher (子会话, Task 面板) → simplifier (子会话, Task 面板) → architect (子会话, Task 面板) → contrarian (子会话, Task 面板)

环境可调项

OUROBOROS_CHILD_TIMEOUT_MS是桥插件读取的唯一环境开关（见 ouroboros-bridge.ts）。重试次数是该文件中的编译期常量——PATCH_RETRIES = 3、RESOLVE_RETRIES = 5（见 第 40-41 行），两者均不可通过环境变量覆盖。

插件工作机制（源码级）

从 ouroboros-bridge.ts 可还原完整执行时序（与 OpenCode Subagent Bridge 文档 相互印证）：

1. tool.execute.after钩子中解析工具输出文本（parse()），统一处理_subagent（单个）或_subagents（数组，最多截取MAX_FANOUT=10个）；
2. 对每个 payloadAWAIT新子会话（client.session.create）；
3. AWAIT通过直接 HTTP PATCH/session/{parent}/message/{mid}/part/{pid}将原始工具 assistant 消息 part 补丁为subtaskpart（state: running），Task 面板以 spinner 内联渲染；
4. 不 await地触发client.session.prompt(...)——子会话后台运行，钩子约 100ms 内返回，主 LLM 不被子会话阻塞；
5. 挂接.then/.catch处理器，子会话完成时 PATCH 面板为completed（含<task_result>输出）或error；
6. 在metadata.ouroboros_dispatch中盖章人类可读的分发横幅 + 结构化信封。

去重与安全：插件以(parentSessionID, callID)作为去重身份（DEDUPE_MS = 5000窗口内同一 MCP 调用重复触发只分发一次，见 dupe()）。resolveMid()采用 fail-closed 策略：5 次重试后仍找不到承载该callID的 assistant 消息则返回null，绝不回退到任意消息，防止繁忙会话中的串话。

权限派生：每个委托子会话都会先加载一次不可变的 authority 快照（父会话权限 + agent 名册），再经deriveSubagentSessionPermission()派生子会话权限规则集（第 517-530 行）——agent 未声明todowrite/task权限时，子会话自动补deny规则。

结构化分发信封（供下游工具识别插件分发与子进程分发）：

{ "status": "dispatched" | "dispatch_failed" | "skipped" | "nothing", "mode": "plugin_subagent", "dispatched_at": "2026-04-17T…Z", "children": [{"title","childID","agent","tool","truncated"}], "failed": [{"title","tool","reason?"}], "skipped": [{"title","tool"}] }

Python 处理器返回的契约键（如job_id、session_id、status）会被保留在out.metadata.ouroboros_response_shape中，即使stamp()把文本内容覆写为横幅，调用方仍能恢复原始工具契约。

插件模式的安装保证

ouroboros setup的安装是原子、幂等、内容哈希的：os.replace原子复制插件源码；opencode.json的plugin数组去重（清除 XDG 迁移、sudo 迁移或历史路径留下的过期条目）；写入前比较 SHA-256 内容哈希，内容相同则不动 mtime。安装后需重启 OpenCode。验证方式：检查<plugin-dir>/bridge.log是否出现INIT行。

路径 2：子进程运行时（回退）

对于无交互式 OpenCode 会话的 headless、CI 或脚本化工作流，显式选择子进程运行时：

# ~/.ouroboros/config.yaml orchestrator: runtime_backend: opencode opencode_cli_path: /usr/local/bin/opencode # 在 PATH 上可省略 llm: backend: opencode

或按次调用：

uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml

OpenCodeRuntime适配器以子进程方式启动opencode run --format json --dangerously-skip-permissions，通过 stdin 管道喂入提示词，并解析 stdout 的结构化 JSON 事件流。orchestrator.opencode_permission_mode默认为bypassPermissions；seed 执行会在新分发与恢复分发时强制该模式。

子进程 vs 插件：何时用哪个

子进程能否替代插件做并行扇出？

理论上可以：orchestrator 可为_subagents信封的每个条目派生N 个并行opencode run --format json子进程，各自通过 stdin 喂 persona 提示词，收集 stdout JSON 事件流，合并回单一信封：

parent = subprocess(opencode run --format json) ← seed 提示词 └─ 命中返回 _subagents=[hacker, researcher, ...] 的 MCP 工具 orchestrator ├─ subprocess(opencode run --format json) ← hacker 提示词 ├─ subprocess(opencode run --format json) ← researcher 提示词 └─ subprocess(opencode run --format json) ← simplifier 提示词 ↓ 每个子进程的 stdout JSON merge → 父信封

但该项目刻意不提供这条路径，对比见下：

结论：子进程运行时始终限定在其擅长的领域——单次 headless 执行。并行子智能体扇出是插件专属特性；用子进程模拟可行，但在所有挂接场景下 UX 严格更差。

源码佐证：OpenCodeRuntime的实现细节

opencode_runtime.py 的类级常量揭示了生产级细节：

• _max_resume_retries = 3（会话恢复最多 3 次）、_max_ouroboros_depth = 5（递归深度上限，防 fork 炸弹）；
• _startup_output_timeout_seconds = 120.0（等待 CLI 首个 stdout 输出的启动保护）、_stdout_idle_timeout_seconds = 600.0（chunk 间空闲保护，可用环境变量OUROBOROS_OPENCODE_STDOUT_IDLE_TIMEOUT覆盖，非正值禁用流循环守护，交给更上层 watchdog）；
• _process_shutdown_timeout_seconds = 5.0（SIGTERM 后宽限 5 秒再 SIGKILL）。

命令构建在 _build_command() 中：

• 提示词不进 argv，而是通过 stdin 管道喂入——规避 Linux 单参数约 128 KB 的ARG_MAX/MAX_ARG_STRLEN限制；OpenCode 在!process.stdin.isTTY时自动读取管道 stdin；
• 使用--pure禁用外部插件：子进程运行时是 LLM 执行器而非交互式会话，若此前安装过 plugin 模式遗留的 bridge，_subagent信封泄漏进 MCP 输出时会在子进程内双重分发——--pure让隔离显式化（注释原文）；
• bypassPermissions（含bypass_permissions、bypass变体）映射为原生--dangerously-skip-permissions标志；
• 可选--model与--session <id>（恢复会话，session id 有严格的正则白名单^[A-Za-z0-9_-]+$，非法字符直接ValueError）。

执行流程（execute_task，第 1096-1412 行）：先尝试确定性 skill 拦截（resolve_skill_dispatch共享路由器，精确前缀匹配本地 MCP handler）→ 未命中才启动opencode run子进程 → 逐行解析 JSON 事件 →OpenCodeEventNormalizer归一化为AgentMessage→ 从事件中提取sessionID构建RuntimeHandle→ 绑定observe/terminate控制回调。Windows 上还有 best-effort 的子进程孤儿清理（wmic process where ParentProcessId=...）。

oooSkill 在 OpenCode 上的可用性

运行ouroboros setup --runtime opencode后，Ouroboros MCP server 注册进 OpenCode 配置，oooskills 即可在 OpenCode 会话内通过 MCP 工具分发调用：

Ralph 说明（#528）：ooo ralph现在调用 MCP 持有的ouroboros_ralph接口，而非在客户端用evolve_step轮询重新实现多代循环。在 OpenCode 子进程/非插件模式下，它返回标准的后台job_id，用 job 工具监控、用ouroboros_cancel_job(job_id)取消；在 OpenCode 插件模式下返回status=delegated_to_plugin且job_id=None——bridge 派发子 Task 会话而非创建任何本地 JobManager job，因此本地 Ralph job 轮询/取消工具对插件委托的运行不适用。ouroboros cancel execution <execution_id>仅针对 execution 会话，不能取消 Ralph job id。

ooo seed与ooo interview的区别：这是职责不同的两个 skill。ooo interview运行苏格拉底式问答会话并返回session_id；ooo seed接收该session_id生成结构化 Seed YAML（含歧义评分）。终端里两步合并为一次ouroboros init start调用。

OpenCode 使用共享的无状态ouroboros.router解析器进行精确的ooo与/ouroboros:skill 分发。新增或修改命令只需更新对应SKILL.mdfrontmatter；运行时保持日志、消息组装与 MCP 调用的本地化。详见 SharedoooSkill Dispatch Router。

快速开始

完整的首次引导流程（interview → seed → execute）见 Getting Started。

验证安装

opencode --version ouroboros --help

第一条命令

在打开第一个工作流之前，先配置一次 OpenCode 集成：

ouroboros setup --runtime opencode

然后启动新的 OpenCode 会话并运行：

ooo interview "Build a task management CLI"

ooo命令在 setup 注册 Ouroboros MCP server 后可用。

OpenCode 专属优势

• 多 Provider 支持—— 通过单一运行时使用 Anthropic、OpenAI、Google 等 Provider；
• 内置 Provider 管理—— OpenCode 自行处理认证与 Provider 配置，无需设置环境变量；
• 丰富的工具访问—— 完整的文件、shell、搜索工具套件（与 Claude Code 同面）；
• 原生 MCP 集成—— OpenCode 内置 MCP server 支持；
• 开源—— 完全开源，可检视与贡献；
• 会话感知运行时—— Ouroboros 跨工作流步骤保留 OpenCode 会话句柄与恢复状态。

所有运行时后端的横向对比见 runtime capability matrix。

运行时差异：OpenCode / Claude Code / Codex CLI

OpenCode、Claude Code、Codex CLI 是三种独立运行时后端，工具集、权限模型与 Provider 生态各不相同。同一 Seed 文件可适用于三者，但执行路径可能不同：

Ouroboros 工作流模型（Seed 文件、验收标准、评估原则）在各运行时之间完全一致。但由于三种后端底层 Agent 能力、工具访问与 Provider 生态不同，同一 Seed 文件可能产生不同的执行路径与结果。

CLI 选项

工作流命令

# 执行工作流（OpenCode 运行时） # ouroboros init 生成的 Seed 保存在 ~/.ouroboros/seeds/seed_{id}.yaml uv run ouroboros run workflow --runtime opencode ~/.ouroboros/seeds/seed_abcd1234ef56.yaml # 调试输出（显示日志与 Agent 输出） uv run ouroboros run workflow --runtime opencode --debug ~/.ouroboros/seeds/seed_abcd1234ef56.yaml # 恢复之前的会话 uv run ouroboros run workflow --runtime opencode --resume <session_id> ~/.ouroboros/seeds/seed_abcd1234ef56.yaml

Seed 文件参考

已知限制

会话污染（仅子进程运行时）

每次经opencode run的任务执行都会在 OpenCode 的会话历史中创建可见会话。多 orchestrator 步骤的长工作流会累积会话。这不影响插件路径——bridge 创建的子会话被内联重挂为 Task 面板，不污染选择器。

后台 job 工具在插件模式下 fire-and-forget

ouroboros_start_execute_seed与ouroboros_start_evolve_step在子进程模式下是后台 job API：返回job_id，调用方经ouroboros_job_status/ouroboros_job_result轮询。

在插件模式下，这些工具将执行委托给 bridge 插件，插件在宿主内派生子会话。MCP server 对子会话生命周期无可见性，因此：

• job_id为None（不创建JobManager记录）；
• status为"delegated_to_plugin"——而非"running"或"queued"；
• ouroboros_job_status(None)/ouroboros_job_result(None)不是有效句柄。

Bridge 管理自身的生命周期：子会话创建、进度渲染（Task 面板）、完成信令。调用方应检查status == "delegated_to_plugin"并依赖 bridge 的内联渲染，而非轮询。

无交互模式

适配器使用opencode run --format json（非交互）。需要交互式 OpenCode 会话的功能（如手动批准提示）在 Ouroboros 执行期间不可用。

权限模式

OpenCode 没有多值--permission-mode选项，但当前版本暴露--dangerously-skip-permissions。Ouroboros 将bypassPermissions翻译为该原生标志，在新分发与--session恢复命令上均生效；较窄的存储模式不会追加全跳过标志。

插件模式下，bridge 为每个委托子会话创建显式 OpenCode 权限规则集：permission="*", pattern="*", action="allow"。这是会话 API 层面的子进程跳过标志等价物；插件恢复不受支持，因为宿主 bridge 无法持久地重挂已分发的子会话。

故障排查

OpenCode 未找到

确保opencode已安装且在PATH上：

which opencode

未安装时：

curl -fsSL https://opencode.ai/install | bash

Provider 未配置

如果 OpenCode 报告 Provider 错误，确认已完成首次设置：

opencode # 交互式首次设置 # 或 opencode providers auth anthropic # 配置特定 Provider

OpenCode 自行管理 Provider 凭证——无需为 Ouroboros 集成设置ANTHROPIC_API_KEY或类似环境变量。

健康检查中的 "Providers: warning"

使用 orchestrator 运行时后端时属正常现象。该警告指向 LiteLLM Providers，orchestrator 模式不使用它们。

"EventStore not initialized"

数据库会在ouroboros config show显示的激活路径下自动创建。

插件相关排查（详见 插件指南）

• 日志无DISPATCH、无 Task 面板：确认 MCP 工具名以ouroboros_为前缀、工具输出为含_subagent/_subagents的合法 JSON、opencode.json中的插件路径指向存在的文件；
• ERR行：常见原因是 SDK 早于 v1.4.3（运行opencode upgrade）、未知agent名（bridge 自动回退general）、子会话超时（调高OUROBOROS_CHILD_TIMEOUT_MS）；
• 原始 JSON 信封泄漏给主 LLM：插件钩子未运行——确认bridge.log有INIT行且安装后重启过 OpenCode；
• Task 面板未内联：subtaskpart 补丁失败，检查bridge.log中ERR PATCH part=... status=...。

成本

将 OpenCode 作为运行时后端会产生配置 Provider 的 API 费用。成本取决于：

• OpenCode 配置中选择的 Provider 与模型；
• 任务复杂度与 token 用量；
• 工具调用与迭代次数。

请参考 Provider 定价页面获取当前费率。

Active Conductor 与 Synapse

OpenCode CLI 子进程会话是经验证的 Synapseinform/after_turn传输通道，使用同一 OpenCode 会话 ID。这并不声称实时 checkpointredirect或硬replace。OpenCode 插件 Task 分发是宿主持有的独立生命周期，不被重新解释为运行时中断。

对于可轮询的运行，一个只读观察者转发当前模型/harness、效率保障、有界 Discover 目标、依赖/并行层级、首批调度的 AC、注意力与终端保障，主会话保持可用。主宿主按语义而非用户提供的内部 ID 选择受影响的 AC，并以用户的会话语言从规范英文指南出发自然表达。

延伸阅读

• OpenCode Subagent Bridge 插件详解 —— 插件安装、验证、重试阶梯与完整诊断手册
• Getting Started —— 安装与首次引导全流程
• SharedoooSkill Dispatch Router ——ooo与/ouroboros:skill 分发的共享无状态解析器
• runtime capability matrix —— 全部运行时后端的横向对比
• 插件源码：ouroboros-bridge.ts；子进程运行时：opencode_runtime.py；配置实现：setup.py、opencode_config.py

• AI Agent
• 人工智能
• 代码智能体
• Agent 编排
• AI 评测
• CLI
• 开发工具