OpenCode 的核心设计：主 Agent 与子 Agent 的分层架构

2026 年 1 月Anthropic 做了一件事封禁第三方工具调用 Claude Code 服务。消息传开的那一周OpenCode 的 GitHub Star 数开始疯长。前五个月攒了 5 万颗星1 月之后短短几周又多了 3 万。到今天这个数字已经超过 17 万。很多人说 OpenCode 是“Claude Code 被封禁的最大受益者”。但事情没那么简单。一个开源项目用不到一年时间做到 800 万月活如果只是因为竞争对手封禁了入口撑不起这个量级。真正让开发者留下来的是它背后那套经得起推敲的架构设计。目录一、发生了什么二、本质上是供应商锁定的反弹三、核心机制拆解主 Agent 与子 Agent 的分层架构四、一个真实的对比同样改代码差别在哪里五、工程落地启示六、最后问一个问题一、发生了什么OpenCode 的起点很小。2025 年 6 月在 GitHub 发布创始团队最开始只有几个人。真正的转折点在 2026 年 1 月。Anthropic 开始封禁第三方工具通过 Claude Pro / Claude Max 订阅账号调用 Claude 模型的行为。OpenCode 之前支持用户用 Claude 订阅直接登录原理是伪装成 Claude Code 的客户端身份发送相同的 OAuth 请求头。Anthropic 的反应分三步技术封锁、账号封禁、法律行动。OpenCode 的回应也很干脆——直接移除了对 Claude Pro/Max 订阅和 Claude API key 的支持。但社区的反应比这两边都快。开发者开始大量涌入。到 2026 年 3 月OpenCode 的 GitHub Star 数达到 12.8 万贡献者超过 800 人。月活跃开发者从 65 万飙到 650 万。安全博主 Daniel Miessler 做了一个直接对比实验用 OpenCode 从零写一个完整博客。他的结论是——“OpenCode 和 Claude Code 一样好至少在这个任务上。”他原本以为 Claude Code 的优势在于某种“秘密酱汁”——上下文管理、记忆维护、多文件多步骤的编排能力。但实际用下来发现OpenCode 做得同样好。他的判断是Claude Code 并不秘密。可能就是围绕上下文窗口和记忆管理的优秀工程实践。一旦其他工具实现了类似的编排策略差距就会迅速缩小。二、本质上是供应商锁定的反弹这件事的本质不是“Claude 不让用了”。本质是开发者对“供应商锁定”的集体反弹。过去两年AI 编程工具市场被几个巨头瓜分。Cursor 每月 20 美元绑定了自己的模型套餐。Claude Code 按 Token 计费只能用 Anthropic 的模型。GitHub Copilot 每月 10 美元只能用 OpenAI。每个工具都在努力把用户圈在自己的生态里。OpenCode 走了一条完全相反的路模型无关。它支持 75 种以上的模型提供商——Anthropic、OpenAI、Google Gemini、DeepSeek、本地部署的 Ollama 和 llama.cpp。你用谁的 API Key就连谁的模型。工具本身不抽成、不锁定、不干预。一个 Reddit 高赞评论说得更直接「Anthropic 正在激励用户留在自己的产品生态里而不是在 API 之上构建外部工具。」开发者用脚投票的结果是OpenCode 成了 GitHub 上星标最高的开源编程 Agent。但模型无关只是“为什么用”的理由。真正让开发者“留下来”的是它内部那套主 Agent 与子 Agent 的分层架构。三、核心机制拆解主 Agent 与子 Agent 的分层架构OpenCode 采用客户端-服务器架构基于 TypeScript 和 Bun 运行时构建。整体分为四层客户端层、核心服务层、扩展层、模型适配层。但最值得关注的设计是核心服务层里的 Agent 系统。OpenCode 的核心设计理念是以“代理模式工作流”为核心将复杂编程任务拆分为“主代理 子代理”的协作模式。3.1 主 Agent 与子 Agent 的定位差异主 Agent 出现在 OpenCode 的 Agent 切换器中是用户直接交互的对象。子 Agent 通过 Task 工具被主 Agent 生成不能直接被用户选中。本质上是这样分工的主 Agent 负责理解用户的整体目标、规划执行步骤、统筹全局。子 Agent 负责拆出去干具体的小任务——查文档、改某个模块、写测试、跑命令、整理结果。你可以把子 Agent 理解成主 Agent 派出去的专项助手。主 Agent 负责整体目标和主线判断子 Agent 负责一个更明确的小任务。3.2 为什么需要分层单个 Agent 处理复杂任务时会遇到三个典型问题第一上下文窗口不够用。一个 Agent 既要理解项目全貌又要处理具体文件的修改细节上下文很快就会撑爆。第二任务无法并行。主 Agent 处理任务是排队的——先做 A、再做 B、再做 C。但很多任务其实可以并行——审查代码和写测试完全可以同时进行。第三职责混杂。同一个 Agent 既要做规划又要写代码还要做审查。角色不清晰决策质量就会下降。分层的核心价值就在于解决这三个问题。3.3 四层架构中的 Agent 系统OpenCode 的四层架构从下到上分别是用户交互层提供 CLI、TUI、Web 三种接入方式。AI 引擎层通过统一的模型抽象层实现模型热插拔和智能路由。核心能力层是 Agent 系统的所在地。工具集成层通过标准化接口与外部系统交互。Agent 系统在核心能力层中包含三个关键组件决策中枢基于 ReAct 框架的思维链推理引擎记忆管理短期工作记忆与长期知识库的分层存储行动规划动态生成可执行步骤序列的规划器3.4 主从协作的完整流程下面这张图展示了主 Agent 与子 Agent 协作的典型流程以一个实际的开源插件 Blueprint 为例它实现了五个专门化的 AgentAgent类型职责Planner主 Agent调研代码库、访谈用户、生成结构化实施计划Orchestrator主 Agent执行计划、创建 git worktree、委派任务、验证结果Investigator子 Agent深度代码库调研——目录结构、代码模式、依赖关系Reviewer子 Agent审查计划和代码发现遗漏和范围蔓延Worker子 Agent在隔离的 git worktree 中实现单个原子任务这里有一个关键的设计约束只有 Worker Agent 可以写源代码。Planner、Orchestrator、Investigator、Reviewer 被限制为只能在 .blueprint/ 目录内写入文件。这个约束解决了一个很实际的问题职责边界清晰。做规划的就做规划写代码的就写代码审查的就审查。不会出现一个 Agent 既当运动员又当裁判员的情况。3.5 Self-Healing 自愈机制OpenCode 还有一个不太常被提及但很重要的设计Self-Healing 自愈机制。核心思想是任务中断后可以从断点继续。实际运行中LLM 的调用可能超时、网络可能闪断、上下文可能溢出。如果没有自愈机制整个任务就要从头开始。有了断点续传损失就被控制在了局部。四、一个真实的对比同样改代码差别在哪里假设你要给一个项目添加用户认证功能涉及三个文件的修改和一个新文件的创建。没有分层架构的 Agent一个 Agent 从头干到尾。它要先理解项目结构然后写代码然后自己审查。过程中它的上下文会越来越臃肿——既要记住项目全局又要关注每个文件的细节。改到第三个文件的时候前面两个文件的上下文可能已经被挤出去了。结果就是顾此失彼。有分层架构的 OpenCode主 Agent 先派一个 Investigator 子 Agent 去调研项目结构——目录怎么组织的、用了什么框架、现有的认证方式是什么。调研结果写回主 Agent 的记忆里。然后主 Agent 基于调研结果生成实施计划派 Worker 子 Agent 去改代码。每个 Worker 只负责一个原子任务在隔离的 git worktree 里工作。改完了派 Reviewer 子 Agent 去审查。每个子 Agent 的上下文是干净的——它只关注自己那一亩三分地。主 Agent 的上下文也是干净的——它只关注整体目标和状态协调。分层的本质不是“多几个 Agent”而是让每个 Agent 的上下文窗口只装它该装的东西。五、工程落地启示说了这么多 OpenCode 的设计对我们自己有什么启发第一上下文隔离是 Agent 系统稳定运行的前提。一个 Agent 的上下文窗口再大也是有限的。把任务拆细、把职责拆清让每个子 Agent 只关注一件事比训练一个“万能 Agent”要靠谱得多。第二主 Agent 不要做具体的事。主 Agent 的核心职责是规划、调度、决策。具体执行交给子 Agent。如果主 Agent 既要做规划又要写代码它的决策质量一定会下降。第三工具级别的权限控制比提示词约束更可靠。Blueprint 的做法是在工具层面通过 tool.execute.before 钩子强制执行权限控制而不是靠提示词告诉 Agent“你不要写源代码”。工程上能用代码保证的事不要依赖提示词。第四自愈机制不是可选项。在生产环境中LLM 调用失败是常态不是异常。设计系统时要假设每一步都可能失败并且有办法从失败中恢复。六、最后问一个问题你的系统里Agent 的上下文是共享的还是隔离的如果是共享的——所有 Agent 共用一个巨大的上下文窗口——那当任务变复杂的时候上下文污染几乎是必然的。如果是隔离的——每个子 Agent 有自己的上下文主 Agent 只负责协调——那你就已经在用分层架构的思路了。想清楚这个问题比学会用 OpenCode 本身更重要。因为工具会变但架构思想不会。