OpenCode 实现多 Agent 协作主要依赖其插件生态核心思路是主 Agent 编排 多个子 Agent 并行执行。以下是完整的实现路径1. OpenCode 多 Agent 简介1.1. 核心架构Sisyphus 模式OpenCode 原生是单 Agent 的终端 AI 助手多 Agent 能力通过插件主要是Oh-My-OpenCode注入。其架构模仿人类开发团队角色职责典型 Agent 名称主 Agent编排器任务拆解、调度、依赖管理、结果汇总Sisyphus / Orchestrator架构师技术方案设计、数据库 Schema、接口契约Oracle / Architect开发者核心代码实现前端/后端Hephaestus / Developer探索者存量代码库分析、依赖检索Librarian / Explore测试/审查代码审查、测试用例、Bug 修复Reviewer / QA文档技术文档、发布说明Document-Writer主 Agent 收到需求后自动拆解任务并分发给子 Agent子 Agent 之间可通过消息传递直接通信例如后端 Agent 改完接口后通知前端 Agent。1.2. 安装与配置1. 安装 OpenCode 核心# 方式一官方脚本curl-fsSLhttps://opencode.ai/install|bash# 方式二npmnpminstall-gopencode-ai2. 安装多 Agent 插件Oh-My-OpenCode# 需要 Bun 环境curl-fsSLhttps://bun.sh/install|bash# 交互式安装bunx oh-my-opencodeinstall# 或 npxnpx oh-my-opencodeinstall安装过程中会提示选择启用的模型Claude / GPT / Gemini并自动写入配置。3. 配置文件~/.config/opencode/opencode.json{$schema:https://opencode.ai/config.json,provider:{name:openai-compatible,baseURL:https://api.xxx.com/v1,apiKey:sk-xxx},model:gpt-5.2,plugins:[oh-my-opencode]}4. 项目级配置AGENTS.md在项目根目录创建AGENTS.md定义项目规范、技术栈和 Agent 行为边界所有 Agent 都会读取该文件以保持上下文一致。1.3. 使用方式1. 符号调用特定 Agent安装完成后直接在对话中使用调用专业 Agentoracle 请设计整体微服务架构图和数据库 Schema librarian 搜索项目中所有与支付相关的代码总结现有逻辑 frontend-ui-ux-engineer 实现一个响应式侧边栏支持折叠和动态路由2. 主 Agent 自动拆解推荐直接描述需求让主 AgentSisyphus自动判断是否需要拆分给现有 API 端点加输入验证前端表单报错文案也要统一同时补上集成测试。主 Agent 会自动创建团队并分配子任务Alice处理用户接口验证范围src/api/users/Bob处理订单接口验证范围src/api/orders/Carol补集成测试和前端错误提示依赖 Alice、Bob 完成后启动3. 多模型混合调度不同 Agent 可配置不同模型实现成本与性能的平衡Agent 角色推荐模型原因主编排 / 架构GPT-5.2 / Claude Opus逻辑强、上下文长代码探索 / 检索Claude Sonnet速度快、成本低前端 / 视觉Gemini 3 Pro多模态能力强文档 / 简单任务Gemini 3 Flash / 本地模型极低成本1.4. 实战示例开发邀请码功能以给 SaaS 后台加一套邀请码机制为例完整协作流程如下阶段执行者产出设计主 Agent / 用户字段定义、接口契约、验收标准并行 1Agent A后端邀请码生成与校验逻辑并行 2Agent B前端管理后台页面后置Agent C测试集成测试、错误提示检查收口用户Review diff、跑验证、合并关键约束——给子 Agent 设硬边界处理用户注册接口的输入验证。 只允许修改 - src/api/users/ - src/validators/user.ts 不要修改 - package.json - 数据库迁移文件 - 共享 UI 组件 完成后输出改动说明、风险点、需要谁继续接手1.5. 关键机制与最佳实践1. 消息传递Agent 间通信当两个任务共享规则但不值得合并时子 Agent 可直接通信alice → bob用户邮箱验证我用了 z.string().email()订单联系人邮箱也统一吗 bob → alice统一我这边也按这个规则走避免前后端提示不一致。2. 依赖管理先拆依赖再拆 Agent接口契约必须先定否则前后端反复返工后置任务放在依赖链后面测试 Agent 等开发 Agent 完成后再启动避免多个 Agent 同时修改同一批文件如共享 Schema、通用工具函数3. 权限隔离通过opencode.json中的permissions字段控制每个 Agent 的文件访问范围防止越界修改。4. 人工审查兜底多 Agent 协作不能自动合并最后必须人工检查diff 是否超出任务目录多个 Agent 是否引入了相似但不一致的实现前后端字段名、错误码是否对齐lint / test / build 是否通过1.6. 与 Claude Code Agent Teams 的对比能力Claude CodeOpenCode OMO多 Agent 协作✅✅跨厂商模型混合❌✅可同时调用 GPT Claude Gemini异步并行✅✅消息传递✅✅开源免费❌✅1.7. 总结OpenCode 实现多 Agent 协作的核心公式是OpenCode 核心 Oh-My-OpenCode 插件 多模型配置 清晰的任务边界它解决的不是AI 会不会写代码而是一个人如何同时推进多块互相关联、但不必串行的任务。关键记住三点先拆依赖再拆 Agent——不要看见能并行就全并行范围写死——子 Agent 不会自动理解这个文件最好别碰人工兜底——最后的审查和合并必须你自己来做2. OpenCode 多 agent 协作示例先重新梳理 多 agent 协作概念然后介绍内置 agent、自定义配置最后实战编排模式。2.1. 核心概念两类 AgentOpenCode 的多 agent 体系只有两种角色 类型说明调用方式Primary agent主 agent我们直接对话的助手按Tab键切换人工切换Subagent子 agent被主 agent 通过 Task 工具调用的专项助手也可以在消息里 提及手动调用自动委派或名称内置 primary agent 有两个 Build默认所有工具全开日常开发用。Plan受限的规划 agent文件编辑和 bash 默认设为ask适合只做分析不改代码。内置 subagent 有三个 General通用型几乎全工具权限可执行多步任务、并行跑多份工作。Explore快速只读 agent用于找文件、搜代码、回答代码库问题不能改文件。Scout只读的外部文档/依赖调研 agent可把依赖仓库克隆到 OpenCode 托管缓存里对照源码。2.2. 基本协作玩法1. 会话内切换主 agentTab 循环切换 Build / Plan比如先用 Plan 出方案再切 Build 执行 。2. 提及子 agent在输入框直接写explore 帮我找一下认证中间件在哪些文件里被引用3. 主 agent 自动委派Build/Plan 会根据子 agent 的description自行决定何时把任务拆给 Explore/General 并行执行。多个general可以在一条消息里并行派发 。4. 查看子会话子 agent 会创建子会话默认快捷键CtrlX ↓进入子会话↑返回父会话 。2.3. 自定义 Agent有两种定义方式效果等价 方式 Aopencode.json{$schema:https://opencode.ai/config.json,agent:{code-reviewer:{description:审查代码的最佳实践和潜在问题,mode:subagent,model:anthropic/claude-sonnet-4-20250514,prompt:你是代码审查员重点关注安全、性能和可维护性。,permission:{edit:deny}}}}方式 BMarkdown 文件放在全局~/.config/opencode/agents/或项目级.opencode/agents/下文件名即 agent 名 --- description: 审查代码质量与最佳实践 mode: subagent model: anthropic/claude-sonnet-4-20250514 temperature: 0.1 permission: edit: deny bash: deny --- 你处于代码审查模式。重点关注 - 代码质量与最佳实践 - 潜在 bug 和边界情况 - 性能影响与安全风险 给出建设性反馈不直接修改代码。2.4. 进阶编排真正的多 agent 协作1. 用permission.task控制调度权限用 glob 模式精确规定某个 agent 能调用哪些子 agent——这是构建编排者模式的关键 {agent:{orchestrator:{mode:primary,permission:{task:{*:deny,orchestrator-*:allow,code-reviewer:ask}}}}}设为deny的子 agent 会从 Task 工具描述中彻底移除模型根本不会尝试调用它 。2. 控制嵌套深度subagent_depth默认值为1主 agent 可以启动子 agent但子 agent 不能再启动子 agent。设为2允许再嵌套一层设为0禁止一切子 agent 调用 {$schema:https://opencode.ai/config.json,subagent_depth:2}3. 隐藏内部 agenthidden: true让子 agent 不出现在 补全菜单里但仍可被其他 agent 通过 Task 工具程序化调用适合做纯后台 worker 。4. 权限细化权限支持到命令级 glob例如 permission:{bash:{git push:ask,git status *:allow}}权限键包括read、edit、bash、task、webfetch、websearch等取值allow/ask/deny。2.5. 实战示例审查流水线一个典型的 Subagent-Driven 工作流——主 agent 负责思考和决策脏活累活全委派 你对话 └─ Build主 agent设计、决策、修代码 ├─ explore → 定位相关代码只读快 ├─ scout → 查第三方库上游实现只读 ├─ general → 并行执行多个独立改造任务 └─ code-reviewer → 改完后审查 diffedit: deny搭配建议给explore、code-reviewer配便宜快速的模型如 haiku 级别省成本主 agent 用强模型 。审查类 agent 一律edit: deny从机制上防止审查员顺手改代码。给不同 agent 设color如color: accentUI 里一眼区分谁在说话 。想让会话默认从规划开始设default_agent: plan必须是 primary agent。2.6. 常见坑在opencode.json里给 markdown 定义的 subagent 加条目时记得显式写mode: subagent否则部分版本会把它错误地当成 primary agent 出现在 Tab 切换列表里 。子 agent 的description要写清楚——主 agent 是根据它决定何时委派的 。生态里还有现成插件可以按主会话模型自动路由子 agent 模型如 opencode-subagent-model-selector不想手写配置可以看看 。3. OpenCode 与 LangGraph 协作OpenCode 与 LangGraph 属于不同层级、不同定位的工具二者是互补关系而非竞争关系。简单来说OpenCode 是终端编码 Agent应用层工具LangGraph 是多 Agent 编排框架基础设施层。3.1. 生态定位对比维度OpenCodeLangGraph类别终端编码 AgentCLI 工具多 Agent 编排框架核心模式Single loop单 Agent 内循环Graph composition图编排执行模型Hybrid混合执行Stateful有状态持久化主要场景终端代码编写、重构、调试复杂工作流编排、多 Agent 协作多 Agent 原生支持❌ 无完整多 Agent 团队机制✅ 核心能力状态管理会话级上下文内置 checkpointing、time-travel3.2. 核心差异OpenCode专注终端编码体验OpenCode 的核心价值在于统一命令、技能、权限和会话路径提供精美的 TUI 界面、LSP 深度集成和多模型支持。它是一个单 Agent产品本身没有内置完整的多 Agent 团队机制。LangGraph专注工作流编排LangGraph 将 Agent 工作流建模为有向图通过节点LLM 调用、工具、条件判断和边条件跳转、循环、分支实现复杂的多步骤推理。它提供内置的 checkpointing支持长运行任务在崩溃后恢复以及 time-travel 调试。3.3. 两者的关系互补与组合关系 1不同层级的工具两者都属于自托管 AI 工具的大范畴但关注点完全不同OpenCode更偏向代码和执行工具使用LangGraph更偏向工作流编排和状态管理选择哪个取决于任务是否需要复杂流程图和多节点状态。关系 2LangGraph 编排 OpenCode 执行最佳实践这是目前业界推荐的组合模式用 LangGraph或 CrewAI做编排层驱动多个专用 Coding Agent如 OpenCode并行工作构建端到端工程自动化流水线。例如LangGraph 定义整体工作流需求分析 → 架构设计 → 并行编码前端/后端→ 代码审查 → 测试 → 部署OpenCode 作为执行节点中的具体工具负责实际的代码编写和文件操作通过 MCPModel Context Protocol或外部 Agent 迁移机制让 LangGraph 调用 OpenCode 完成具体编码任务关系 3与 Codex 的 AgentGraphStore 对比有趣的是Codex CLI 的AgentGraphStore被描述为最接近 LangGraph 的竞品抽象但两者关注点不同LangGraph关心图怎么执行编排运行时AgentGraphStore关心图怎么持久化与查询拓扑存储Codex 把编排留给 ThreadManager把拓扑存储独立为 trait——未来甚至可以把 LangGraph 风格的执行器接到 AgentGraphStore 上。这种设计思路也适用于 OpenCode 与 LangGraph 的关系OpenCode 负责终端执行LangGraph 负责上层编排。3.4. 实际使用场景场景推荐方案个人日常编码、终端交互单独使用 OpenCode复杂多步骤工作流需要分支、循环、人工审批单独使用 LangGraph企业级 Multi-Agent 流水线LangGraph 编排 OpenCode 执行需要跨厂商模型混合的编码任务OpenCode原生支持多 provider需要审计追踪和状态恢复LangGraph内置 checkpointing3.5. 总结OpenCode 与 LangGraph 的关系可以概括为不是替代品——OpenCode 不会取代 LangGraph 的编排能力LangGraph 也不会取代 OpenCode 的终端编码体验可以组合使用——LangGraph 作为上层编排器OpenCode 作为下层执行器通过 MCP 或 API 集成生态分层——OpenCode 属于Coding Agent Harness层LangGraph 属于Multi-Agent Orchestration Framework层如果已经在用 OpenCode 做日常开发但遇到需要多个 Agent 协作的复杂项目正确的做法不是放弃 OpenCode而是在其上叠加 LangGraph或 CrewAI、AutoGen作为编排层让 OpenCode 专注于它最擅长的终端编码执行。4. OpenCode 与 HarnessOpenCode 对Harness Engineering驾驭工程的支持程度可以概括为原生能力扎实、生态扩展丰富、但在深度编排和状态持久化上仍有提升空间。OpenCode 本身就被业界视为一个功能完备的Agent Harness同时也有大量第三方项目专门为其增强 harness 能力。4.1. Harness Engineering 的核心理念Mitchell Hashimoto 提出的 Harness Engineering 强调不是优化模型本身而是设计一个让 Agent 无法越界的环境。每次 Agent 犯错就增加一条工程约束让它不会再犯。这对应三层栈上下文工程Context Engineering给 Agent 足够且精准的信息护栏工程Guardrail Engineering限制 Agent 的行为边界编排工程Orchestration Engineering多 Agent 协作与任务调度4.2. OpenCode 原生支持的 Harness 能力OpenCode 作为终端编码 Agent本身提供了大量 Harness Engineering 所需的基础设施能力维度OpenCode 支持情况说明多模型支持✅ 12 提供商Anthropic、OpenAI、Google、GitHub Copilot、Bedrock、Azure、OpenRouter、本地模型等无厂商锁定Skills 系统✅ 可发现、可复用自动发现SKILL.md支持本地和远程来源形成可复用的能力生态MCP 协议✅ 完整支持stdio / HTTP / SSE 三种传输方式prompts 和 resources 可作为命令暴露权限控制✅ per-agent 规则支持按 Agent 设置规则集如build宽松、plan只读文件模式拒绝如.env插件系统✅ 一等公民opencode-ai/pluginSDK支持事件钩子、工具注册、Provider 钩子、OpenTUI 组件Session 管理 部分支持SQLite 持久化消息、工具调用、权限、待办事项和文件 diff支持快照和回滚但无显式 checkpoint APIWorktrees✅ 支持隔离的 git worktree 流程支持并行 Agent 工作和安全的实验LSP 集成✅ 深度集成自动加载语言服务器为 LLM 提供精确的工具支持这在编码 Agent 中很少见多界面✅ 终端/Web/桌面/IDE同一后端驱动多种前端还支持opencode serve无头模式及 SDK跨 Harness 协作✅ 通过 Agent Intercom支持与 Pi、Claude Code、Codex 等跨 Harness 的本地消息传递4.3. 第三方 Harness 增强生态业界已出现多个专门为 OpenCode 打造的 Harness 增强项目说明其扩展性得到认可1. OpenCode Harness80 Agents, 260 Skills提供完整的 Agent 团队体系17 个工程工作流 Agent规划、架构、代码审查、TDD、重构、测试、调试17 个代码审查 Agent按语言细分Python、Rust、Go、Java、TS 等11 个构建修复 Agent覆盖所有主流语言26 MCP 服务器配置GitHub、Jira、Supabase、Vercel、Playwright 等核心命令/plan # 创建实现计划 /tdd # 强制 TDD 工作流80% 覆盖率 /code-review # 代码质量与安全审查 /security # 综合安全审查 /orchestrate # 多 Agent 编排 /learn # 提取模式与经验2. OpenCode Agent Team HarnessOrchestrator 6 子代理采用能力自适配设计Orchestrator 自动发现项目层提供的可选能力有什么用什么没有则优雅降级。子代理按模型能力分层assistant主力大范围搜索、多文件分析architect架构设计、方案对比reviewer深度代码审查、安全审计scout只读搜索用轻量模型降低成本worker极简单修改用最便宜模型3. AI Engineering Harness跨工具统一配置支持用同一套配置同时管理 Claude Code、OpenCode、Gemini CLI、Pi 四个工具实现跨 Harness 的上下文工程标准化。4. OpenCode MemoryHarness 工程引导器提供本地 RAG 记忆层并内置Harness 工程自动引导器一键创建标准的三层架构和生命周期文件。4.4. Harness Engineering 实践中的四护栏在 OpenCode 的 Harness Engineering 实践中社区总结出了四层护栏机制OpenCode 对其支持度如下护栏一上下文工程Context EngineeringAGENTS.md全局注入的系统 prompt所有 subagent 启动时必读分层 Spec按 agent 类型注入规范文件模板已建自动化注入尚未完全落地Codebase Memory MCP代码知识图谱按需检索避免 grep 瞎猜或凭记忆编造⚠️教训过度注入上下文反而有害。有实践者建了 30 个loop-*.md命令文件结果占满 context window执行质量下降最终全部删除后 Agent 反而更稳定。护栏二权限与沙箱文件级权限支持edit: deny等规则防止 Agent 修改关键文件⚠️ 无真正 OS 级沙箱权限是 UX 和运行时策略层不是操作系统隔离护栏三多模型路由静态配置已成熟自动化模型路由仍在探索中如前端布局自动用轻量模型安全关键代码自动升级最强模型护栏四反馈循环Learnings 机制手动将经验写入 memory理想状态是让 Agent 在 TDEKTest-Driven Experience Knowledge循环中自动更新规范文件4.5. 与其他 Harness 的对比定位特性OpenCodePi Coding AgentClaude CodeCodex定位Batteries-included 全能型极简可扩展Lego 式单 Agent 深度体验OpenAI 原生资源占用较高极低中等中等Harness 扩展性高插件 Skills MCP极高TypeScript 模块中等Skills MCP中等Plugins多模型✅ 最广✅ 支持❌ Anthropic 为主❌ OpenAI 为主跨 Harness 协作✅ Agent Intercom✅ Agent Intercom✅ Agent Intercom✅ Agent IntercomLSP 支持✅ 深度❌ 无✅ 有 基础Worktrees✅ 支持❌ 无✅ 支持✅ 支持4.6. 当前局限与待改进无显式 Checkpoint API虽然 SQLite 持久化丰富但缺乏 LangGraph 式的 time-travel 和状态恢复机制无真正沙箱权限控制是策略层非 OS 隔离敏感操作仍需人工兜底多 Agent 原生支持有限核心仍是单 Agent 产品多 Agent 需依赖 Oh-My-OpenCode 等插件或外部编排器如 LangGraph记忆系统待升级当前主要是项目级记忆跨项目的个人知识迁移尚未实现复杂度较高后端、TUI、Web、桌面、SDK、协议层叠加比极简 CLI 更难理解和定制4.7. 总结OpenCode 对 Harness Engineering 的支持程度是中上水平且生态活跃层级支持度评价基础 Harness 能力⭐⭐⭐⭐⭐多模型、Skills、MCP、插件、权限、LSP、Worktrees 一应俱全Harness 扩展生态⭐⭐⭐⭐⭐第三方项目丰富80 Agents、260 Skills、跨 Harness 协作深度编排能力⭐⭐⭐原生多 Agent 有限需借助 Oh-My-OpenCode 或 LangGraph状态持久化⭐⭐⭐⭐SQLite 持久化扎实但缺少 checkpoint/time-travel安全隔离⭐⭐⭐策略层权限完善但无 OS 级沙箱适合场景需要多模型混合同时用 GPT Claude Gemini 本地模型需要深度编码集成LSP、Worktrees、复杂文件操作愿意通过插件和第三方 Harness扩展多 Agent 能力重视开源和可审计性MIT 协议可 fork 和自托管不适合场景需要原生复杂工作流编排LangGraph 更适合需要严格的 OS 级沙箱隔离追求极简轻量Pi 更合适需要自动化的跨项目知识迁移尚在探索中