OpenCode 技术调研：与 Qoder、Codex、Claude Code 的路线差异，以及在其上自建 agent 工具的可行路径

版本历史

术语与缩略语

可靠性标记

1. 核心判断（TL;DR）

• 【C】OpenCode 是 MIT 许可、TypeScript 实现的开源终端编码 agent，采用 client/server 架构：TUI 只是客户端之一，opencode serve 暴露 OpenAPI 3.1 规范与 SSE 事件流，官方明确说明这一架构"让你可以以编程方式驱动 opencode"。[S01][S02][S03]
• 【C】它与三者的根本区别在开放的层次：OpenCode 全栈开源（MIT）且模型层完全开放（75+ providers、任意 OpenAI 兼容端点、本地模型）；Codex CLI 开源（Apache-2.0、Rust）但生态围绕 OpenAI 模型；Claude Code 与 Qoder 闭源，前者只能接 Anthropic 系（含 Bedrock、Vertex 托管），后者是闭源平台但开放 Agent SDK 与自定义模型。[S01][S10][S33][S39][S45][S26][S30]
• 【C*】四者的外挂扩展机制已经收敛——MCP、自定义指令文件（AGENTS.md、CLAUDE.md、agent markdown）、子代理、hooks 都能找到对应物；真正的差异在"能否改到内部"：OpenCode 的插件可以拦截工具执行与聊天参数、覆盖内置工具、改写压缩提示，闭源工具只能在外挂点活动。[S05][S11][S23][S41][S42]
• 【C】在 OpenCode 上自建自己的 agent 工具有三条路线：插件（改行为、复用官方 TUI/桌面端）、SDK/Server（用 OpenAPI 客户端自建前端或把 agent 嵌入自有产品）、fork（MIT 允许，但需承担与上游同步与 v2 迁移成本）。生态里已经有 kimaki（Discord bot）、OpenChamber（VS Code 扩展）、Portal 等用 SDK 构建的第三方案例。[S04][S05][S20][S21]
• 【P】若目标是做一个"自己的 agent 产品"而不是换皮同类 CLI，建议以 SDK/Server 为主线、插件补齐行为、fork 仅在必须改 TUI 与内置工具语义时采用；理由是前两者不承担上游合并成本，而 OpenCode 正在向 v2 迁移。[S04][S22]

2. 问题、范围与方法

2.1 调研问题与边界

本报告回答三个问题：(1) OpenCode 是什么、由谁维护、处于什么状态；(2) 它与 Qoder、OpenAI Codex、Claude Code 在定位、开放性、扩展机制、可编程性上的区别是什么；(3) 如果想在 OpenCode 基础上开发自己的 agent 工具，技术上可行吗、走哪条路、代价是什么。

边界说明：报告只使用公开可核验来源（仓库元数据、官方文档、npm 元数据、官方站点）；不评价各工具的产品优劣，不做性能与成本实测；涉及许可的表述仅引用官方原文，不构成法律意见。

2.2 证据分级与判读口径

• 工具事实以官方文档与仓库元数据为准；第三方博客与社区文章只用于线索发现。
• "可扩展"的判断以官方文档是否定义接口为准，而不是以社区插件是否存在为准。
• 涉及版本与数量的数字标注采集时点（2026-09-29）；OpenCode 仓库默认分支为 dev，接口与包结构仍在演进，读者复核时应以最新文档为准。

3. 全球技术基线

3.1 OpenCode 是什么：沿革、版本与社区规模

仓库事实。 目标仓库位于 github.com/anomalyco/opencode，描述为 "The open source coding agent."，主语言 TypeScript，默认分支 dev，MIT 许可证，创建于 2025-04-30；采集时点星标约 21.1 万、fork 约 2.8 万。当前发布线版本为 1.18.33（npm 包名 opencode-ai，命令为 opencode，dist-tags 含 dev、beta、next、snapshot），仓库 tags 中已出现 v2.0.x，说明 2.0 正在推进。[S01][S22]

地址变迁与历史澄清。 旧地址 github.com/sst/opencode 返回 301 并跳转到 anomalyco/opencode；anomalyco 组织的展示名为 Anomaly，官网域名为 anoma.ly，SST 官网页脚署名为 "© 2026 Anomaly Innovations" 并写明团队同时维护 OpenCode，YC 页把 OpenCode 列为 Winter 2021 批次（团队规模 24）。也就是说：这是同一个项目随公司品牌迁移，不是两个项目。[S01][S25]

另一个容易被混淆的项目是 github.com/opencode-ai/opencode——一个 Go 语言实现、13.7k 星、已于 2025-09-18 归档的终端编码 agent，其归档说明是 "Archived: Project has been Moved … The project has continued under the name Crush, developed by the original author and the Charm team."。它与当前 TypeScript 版 OpenCode 不是同源延续，只是同名历史项目：旧项目已改名为 Crush，当前 OpenCode 由 SST/Anomaly 团队另起实现。选型与引用时应避免把两者的历史与事实混用。[S24]

仓库结构与工程形态。 packages/ 下包含 opencode（主程序）、tui、desktop、sdk、plugin、server、web、ui、docs、enterprise、slack、containers、console、llm 等数十个包，呈现出"一个 agent 运行时 + 多客户端 + 多发行形态"的工程布局。[S01]

3.2 架构：TUI 只是客户端之一

官方文档对架构的表述非常直接："When you run opencode it starts a TUI and a server. Where the TUI is the client that talks to the server."；而 opencode serve 运行一个无界面 HTTP 服务端，"exposes an OpenAPI endpoint that an opencode client can use"。这套架构的官方定位是："This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically."——这句话是"能否在其上自建工具"的第一个制度性依据。[S03]

具体接口面：服务端在 /doc 发布 OpenAPI 3.1 规范，官方建议 "Use the spec to generate clients or inspect request and response types"；GET /event 提供 SSE 事件流（首个事件为 server.connected）；会话相关的核心端点包括 POST /session、POST /session/:id/message、POST /session/:id/prompt_async、POST /session/:id/command、POST /session/:id/shell，以及会话的 fork、share、summarize、revert、permissions 等；还提供 /agent（代理清单）、/find、/file、/lsp、/mcp、/config、/provider 等资源端点，以及一组 /tui/* 控制端点（追加提示、提交提示、打开帮助/会话/主题/模型、显示 toast、控制权协商）。认证通过 OPENCODE_SERVER_PASSWORD 启用 HTTP basic auth。[S03] 注意：官方文档没有对"公网暴露服务端"给出专门的安全章节，把它当内网/本机服务对待是更稳妥的口径。[S03]【P】

其它客户端形态：headless 运行 opencode run [message..]（支持 --continue、--session、--model、--agent、--file、--format、--attach、--auto 等参数）；ACP 模式 opencode acp 以 stdio 上的 JSON-RPC 对接 Zed、JetBrains、Avante.nvim、CodeCompanion.nvim 等编辑器；IDE 集成在 VS Code、Cursor、Windsurf 的终端内自动安装扩展并支持 Cmd+Esc；桌面端处于 BETA（Electron，提供 dmg、exe、deb、rpm、AppImage 发行包）。[S13][S14][S15][S01]

3.3 扩展面：五个层次

OpenCode 的扩展能力可以按"离模型有多近"分为五层，每层都有官方定义的接口：

权限模型是插件之外的另一处“可编程点”：permission 支持 allow/ask/deny 三态，可按输入做对象匹配（例如 {"bash":{"*":"ask","git *":"allow","rm *":"deny"}}），规则"last matching rule winning"，支持星号与单字符两类通配符，另可用 external_directory 做目录外访问控制；--auto 只自动批准 ask，不会突破 deny。[S12]

图 1：OpenCode 的架构分层与三处自建落点（客户端层可由自建客户端替换；扩展层用插件 hooks 拦截与改写行为；server 层可由 SDK 直接驱动；内核层不开放，除非 fork）。来源为 OpenCode 官方文档（server、sdk、plugins、agents、models、mcp）与仓库包结构归纳；为架构示意，不代表实现细节与性能数值。[S03][S04][S05][S06][S09][S10][S11][S16][S23]

理解这张分层图的直接结论是：自建工具的所有扩展动作都发生在客户端层、扩展层或 server 接口层，越往内核层走代价越高，架构与扩展点关系见图 1。

3.4 SDK 与可编程集成

@opencode-ai/sdk 是官方 JS/TS SDK，文档定义为 "Type-safe JS client for opencode server."，且 "All types are generated from the server's OpenAPI specification"。两种用法：createOpencode() 会同时拉起服务端与客户端（默认端口 4096），createOpencodeClient({ baseUrl }) 用于连接已有实例。文档给出的能力包括 session.list/create/prompt、event.subscribe、client.app.log()，以及在请求里用 format 指定 JSON schema 以获得"returns validated JSON matching the provided schema"的结构化输出。[S04]

需要如实说明的限制：packages/sdk 下只有 JS 客户端与 openapi.json，没有官方 Go/Python SDK；其它语言要自己从 OpenAPI 生成客户端。[S01][S04] 官方 SDK 文档未标注 beta/实验状态，但项目在向 v2 迁移（仓库已出现 sdk-next 包与 v2.0.x tags），接口稳定性需要以具体版本为准。[S01][S22]【P】

集成形态方面：opencode github install 会生成 .github/workflows/opencode.yml，在 Issue/PR 评论 /opencode 或 /oc 触发，Action 写法为 uses: anomalyco/opencode/github@latest；另有 GitLab 集成文档页。[S16]

3.5 商业化与生态

OpenCode Zen 是团队提供的模型网关（官方表述 "Curated list of models provided by OpenCode"、"AI gateway"），文档明确写成 "completely optional"，端点形如 https://opencode.ai/zen/v1/responses、/zen/v1/chat/completions、/zen/v1/models，按请求计费并包含若干 -free 模型；官方对定价的说法是 "selling at cost; so the only markup is to cover our processing fees"。团队工作区在 beta 期免费，角色分 Admin/Member。[S17] 订阅产品 OpenCode Go 为 10 美元/月、Go Plus 为 40 美元/月；企业版按席位计费，官方承诺 "OpenCode does not store your code or context data."、"You own all code produced by OpenCode."，并提供 SSO 与内部 AI 网关接入。[S18][S19]

生态：官方 ecosystem 页列举的第三方项目包括 kimaki（Discord bot，基于 SDK）、opencode.nvim、Portal、OpenChamber（VS Code 扩展）、OpenWork、CodeNomad、ai-sdk-provider-opencode-sdk、Daytona 隔离沙箱插件、opencode-wakatime、helicone-session 等，另有社区聚合的 awesome-opencode 与 opencode.cafe。这些项目本身就是"在 OpenCode 上构建"的现成样本。[S20]

命名条款：README 的 "Building on OpenCode" 一节要求，若第三方项目名称包含 "opencode"（例如 "opencode-dashboard"、"opencode-mobile"），须在 README 中声明"not built by the OpenCode team and is not affiliated with us in any way"。这是自建产品在命名与品牌上的唯一明文要求。[S21]

3.6 对比基线一：Qoder（阿里）

定位与形态。 Qoder 官方定位是 "Qoder is an agentic platform for real work"，围绕 "understand → plan → execute → verify → iterate" 的端到端闭环组织产品。发布形态覆盖 IDE（Editor 加 Quest）、JetBrains 插件、Qoder CLI、Cloud Agents、移动端与 Web、桌面应用，操作系统标注为 Windows、macOS、Linux。[S26][S27]

核心能力（官方措辞）。 Quest（"long-running, multi-step delegation"）、Repo Wiki（/qoder/repo-wiki，为仓库生成可维护的知识库）、Spec 驱动开发（/user-guide/quest/spec-driven）、代码审查（/qoder/review-and-commit）、Memory and Rules、Skills and plugins、multi-agent collaboration。[S26]

模型开放性。 文档中出现 Qwen3.8 系列（Flash、Max）与 Model Selector、Model Tier Selector；支持 Custom Models 与 Model Policy（IDE、CLI、Agent SDK、Cloud Agents 均可配置），免费档明确支持 BYOK。这一点与 OpenCode 的"provider 完全开放"方向一致，但实现路径是平台内配置而非开源可改。[S26][S30][S28]

扩展与可编程性。 MCP 在 IDE、CLI、Agent SDK、企业版各有独立文档；同时提供 Skills、Plugins、Hooks、Custom Agents / Custom Agent Teams。可编程接口方面，官方称 "Qoder Agent SDK is officially open"，提供 TypeScript 包 @qoder-ai/qoder-agent-sdk（Node 18+）与 Python 包 qoder-agent-sdk（3.10+），涵盖 planning、tools、session、memory、permission；Cloud Agents 另有 sessions、events stream 等 REST API。[S29][S31][S32]

开源与商业。 主体不开源（文档版权署名 "© 2026 BRIGHT ZENITH PRIVATE LIMITED."）；组织下有少量开源件（如 qoder-action 为 MIT、qoder-acp-demos 为 Apache-2.0）。订阅为 Free、Pro 20 美元/月、Pro+ 60 美元/月、Ultra 200 美元/月，对应不同 Credits 额度；企业版提供成员、身份、策略、知识、模型、市场与审计等治理能力。[S28]

3.7 对比基线二：OpenAI Codex

形态与许可。 openai/codex 仓库描述为 "Lightweight coding agent that runs in your terminal"，语言 Rust，Apache-2.0 许可证，约 12.7 万 stars；npm 包 @openai/codex（版本 0.159.0，Apache-2.0）。形态除 CLI 外还包括 IDE 扩展、桌面应用、浏览器端界面，以及云端 Codex 与 GitHub 代码审查服务。[S33][S34]

关键机制。 仓库 docs/ 下可确认存在 agents_md.md、skills.md、slash_commands.md、execpolicy.md、sandbox.md、config.md 等文档入口（正文托管在 developers.openai.com）：自定义指令走 AGENTS.md；执行安全走沙箱与审批（macOS Seatbelt、Linux Landlock 加 seccomp，配置项 sandbox_mode、approval_policy）；外部工具走 MCP；config.toml 支持定义 model_providers（可接第三方或自托管端点）。默认模型为 GPT-5-Codex 系列。[S33][S35][S36][S37]

可编程性。 codex exec 提供非交互式/headless 模式用于脚本与 CI；官方提供 TypeScript 的 Codex SDK（npm @openai/codex-sdk，Apache-2.0，描述为 "TypeScript SDK for Codex APIs"）。综上，Codex 的开放度介于 OpenCode 与 Claude Code 之间：CLI 与 SDK 开源、可 fork、可接自定义 provider，但平台侧（云 Codex、账号体系、部分能力）仍是 OpenAI 的商业服务。[S37][S38]

3.8 对比基线三：Claude Code

形态与许可。 Claude Code 官方定义是 "agentic coding tool"，"Available in your terminal, IDE, desktop app, and browser"。npm 包 @anthropic-ai/claude-code（版本 2.1.284）的 license 字段为 "SEE LICENSE IN README.md"（即专有许可），对应 GitHub 仓库 anthropics/claude-code 无 license 字段——闭源、不可 fork。[S39][S40]

扩展机制（外挂点完备）。 CLAUDE.md 作为项目级记忆，官方说明 "Claude Code reads at the start of every session"；Subagents 定义在 .claude/agents/ 或 ~/.claude/agents/，为 Markdown 加 YAML frontmatter（必填 name、description，可选 tools、model、hooks、skills）；Hooks 允许在动作前后运行 shell 命令；此外还有 Skills、slash commands、Plugins、MCP。[S39][S41][S42]

可编程性与 provider 边界。 headless 模式为 claude -p，支持 --output-format json|stream-json 与 --permission-mode，面向 CI 自动化；Agent SDK 为 npm @anthropic-ai/claude-agent-sdk（版本 0.3.284，描述 "SDK for building AI agents with Claude Code's capabilities"，license 同为 "SEE LICENSE IN README.md"）。provider 方面官方称 "Terminal CLI, VS Code, and JetBrains also support third-party providers"，支持 Amazon Bedrock、Google Cloud 的托管 Claude（原 Vertex AI）与 LLM Gateway，相关环境变量如 ANTHROPIC_BEDROCK_BASE_URL、ANTHROPIC_VERTEX_BASE_URL；未见支持任意非 Anthropic 模型的官方说明。[S43][S44][S45]

3.9 四者对照与定位判断

判断要点：四者在外挂扩展上已经收敛（都能接 MCP、都能定义自定义指令与子代理、都能在 CI 里跑 headless），差异集中在三点——(1) 开源的深度：只有 OpenCode 与 Codex CLI 能 fork，其中只有 OpenCode 全栈 MIT；(2) 模型自由度：OpenCode 面向任何 provider，Codex 名义上可配但生态绑定 OpenAI，Claude Code 限定 Anthropic 系，Qoder 在平台内开放自定义模型；(3) 是否允许你换掉客户端：只有 OpenCode 把"多客户端"写进架构目标并给出 OpenAPI 与 SSE 事件流。对"我想做一个自己的 agent 工具"这个问题，第三点是最关键的分水岭。[S03][S10][S37][S45][S30]

图 2：OpenCode、Qoder、OpenAI Codex、Claude Code 的路线对照（上：MCP、自定义指令与角色、子代理与技能、CI 与 headless 四项四家共有；下左：OpenCode 的 MIT 许可、插件 hook 深度、75+ providers 与可自建客户端；下右：Qoder 的闭源平台加 Agent SDK、Codex 的 Apache-2.0 CLI 加 OpenAI 生态、Claude Code 的闭源专有许可加 Anthropic 系模型）。来源为四家官方文档与包元数据归纳；为定位示意，不代表能力评分与产品优劣。[S01][S03][S05][S10][S29][S33][S37][S40][S45]

两个分水岭（能否替换客户端、能否改造内核）决定了自建工具的可行空间，四者的定位差异见图 2。

能力成熟度对比矩阵

从上表可以看出："能不能嵌入自有产品"四家都给了答案，但"能不能替换掉 agent 本体的界面与交互"只有 OpenCode 给了完整的、开放的答案；而"能不能改造 agent 内核本身"则是 OpenCode 与 Codex CLI 独有的可能（前者 MIT，后者 Apache-2.0）。[S03][S04][S01][S33]

4. 国内发展、差距与机会

4.1 国内代表：Qoder 走"平台加 SDK"路线

国内 agentic coding 工具的商业化代表是 Qoder：闭源平台化交付，但把可编程面做得很完整——Agent SDK 同时提供 TypeScript 与 Python、Cloud Agents 提供 sessions 与事件流 REST 接口、模型支持 Custom Models 与 BYOK。对国内团队而言，这条路线的好处是开箱可用与合规可控（企业版含身份、策略、审计），代价是不能改内核、不能自建客户端，工具能力受平台路线图约束。[S29][S30][S28]

4.2 国内开源路线：在开源 agent 基础上二次开发已有先例

国内已有"在开源 agent CLI 基础上做自己的工具"的成功先例：Qwen Code 是一个开源 AI 编码 agent（TypeScript、Apache-2.0、约 2.8 万 stars），其 README 明确写道 "This project was originally based on Google Gemini CLI v0.8.2."——即先在开源 CLI 上二次开发，再形成自有产品与生态。这说明本报告第 7 章讨论的路线（插件、SDK 集成、fork）在国内有可对照的实践样本，而且开源许可（Apache-2.0/MIT）是这类实践成立的前提。[S46]

4.3 差距与机会

差距。 (1) 国内尚无与 OpenCode 同量级的通用开源 agent 运行时【?】——本报告未检索到 20 万星级、且同时具备"多客户端架构加插件系统加开放 SDK"的对等开源项目；(2) 国产模型进入 agent 工具链的路径依赖 OpenAI 兼容协议，OpenCode 的 @ai-sdk/openai-compatible 加 baseURL 是现成入口，但模型侧对工具调用、长上下文与结构化输出的支持差异仍需逐项验证 [S10]；(3) 闭源平台与开源框架的生态位置不同，国内团队在"自建 agent 工具"时往往缺少可参考的许可证与品牌合规经验。[S21]

机会。 OpenCode 的 MIT 许可与 client/server 架构给国内团队留出了三块空间：(1) 行业化 agent 产品——用 SDK/Server 把 OpenCode 作为运行时，自建符合行业流程（合规审查、私有化部署、领域工具链）的前端；(2) 私有化与离线场景——基于任意 OpenAI 兼容端点与本地模型接入，配合插件做企业内网工具与权限策略；(3) 生态位补充——官方 ecosystem 已列出多个基于 SDK 的第三方项目，中文语境下的入口（文档、模板、行业插件）仍有空间。以上判断属工程推断【P】，落地前需按第 7 章的验收条件逐项验证。[S04][S10][S20][S21]

5. 关键机制深挖

以下四节围绕"在 OpenCode 上自建工具"必须打交道的四个机制面展开：插件、Agent 编排、Provider 抽象、Server/SDK。每节按"接口与实现依据 → 失效边界 → 验证条件 → 成本与权衡"给出可直接执行的结论。

5.1 插件系统：hook 生命周期、加载作用域与覆盖语义

接口与实现依据。 插件用 TypeScript/JavaScript 编写，类型来自 @opencode-ai/plugin，插件函数的入参包含 { project, client, $, directory, worktree }——其中 client 就是 OpenCode 客户端（可用 SDK 能力），$ 是 shell 执行器。加载来源有三：全局目录 ~/.config/opencode/plugins/、项目目录 .opencode/plugins/ 自动加载，或在 opencode.json 的 "plugin" 列表里声明 npm 包，由 Bun 安装并缓存到 ~/.cache/opencode/node_modules/；加载顺序为全局 config → 项目 config → 全局插件目录 → 项目插件目录。可用的 hook 覆盖了 agent 生命周期的关键路径：tool.execute.before/after（工具执行前后）、tool.definition（工具定义）、chat.message、chat.params、chat.headers（消息与模型请求参数、请求头）、permission.ask（权限询问）、command.execute.before、shell.env（shell 环境变量）、event（全局事件）、config、auth、provider（配置、认证与 provider 挂钩），以及实验性的 experimental.chat.system.transform 与 experimental.session.compacting（后者可以整体替换压缩提示 output.prompt）。[S05][S23]

失效边界与已知风险。 (1) 静默覆盖：插件注册的工具与内置工具同名时 "the plugin tool takes precedence"——覆盖不报错，若插件实现有误，表现为 agent 能力"悄悄变了"而不是失败，排查成本高。[S05] (2) 实验性接口不稳定：名称含 experimental 的 hook 不承诺兼容，项目又正在向 v2 迁移，依赖这些 hook 的产品需要版本锁定与回归测试。[S01][S23]【P】(3) 同进程风险：插件代码与 agent 进程同生命周期，插件抛错或阻塞会影响会话本身；官方文档未给出插件超时与隔离机制的说明。[S05]【P】(4) 供应链风险："plugin" 列表可直接引用 npm 包，等于把第三方代码放进 agent 进程，需按依赖治理流程评审。[S05]

验证条件。 建议的最小验证集：写一个本地插件依次打印各 hook 的触发顺序，确认生命周期符合预期；用 tool.execute.before 拦截一次 bash 调用并返回拒绝，确认拦截生效且上层可感知；用 chat.params 修改温度或模型参数，在请求侧核对生效；注册一个与内置同名的工具，确认覆盖语义与预期一致（这条用于评估"是否有工具能替换内置能力"）；在 CI 中固定插件版本与缓存目录，并断言加载顺序。[S05][S23]

成本与权衡。 插件的成本结构最优：进程内调用无 IPC 开销，改动不涉及 fork，不必与上游合并；代价是能力受限于官方暴露的 hook 集合——能改行为与参数，但改不了 TUI 交互与核心数据模型。与"改源码"相比，插件把维护成本从"跟进上游 diff"降级为"跟进 hook 兼容性"；与"纯配置"相比，插件能实现条件逻辑与外部系统对接，但引入了代码与依赖治理负担。[S05][S23]

5.2 Agent 与子代理：角色、权限与工具编排

接口与实现依据。 Agent 可以定义在 opencode.json 的 "agent" 键，或写成 markdown 放在 ~/.config/opencode/agents/、.opencode/agents/；字段包括必填的 description，以及 mode（primary/subagent/all）、model、temperature、prompt（支持 "{file:...}" 引用外部提示文件）、steps、permission、tools、disable。内置角色分三类：primary 有 build（默认全权）与 plan（对编辑与 bash 默认 ask）；subagent 有 general、explore、scout；另有对用户隐藏的系统 agent compaction、title、summary 负责上下文压缩、标题与摘要。[S06] 子代理的调用面既可由主代理自动派发，也可由命令 frontmatter 的 subtask 指定，或经服务端 /agent 端点枚举。[S06][S08][S03]

失效边界与故障模式。 (1) mode 配置错误会让 agent 在预期位置"看不见"——写成 subagent 的 agent 不会出现在主代理列表里，表现为"配置没生效"而非报错。[S06] (2) steps 是硬上限，长任务被截断时表现为"任务做了一半停下"，需要把步数上限当作容量规划参数而不是安全阀。[S06] (3) tools 白名单与 permission 规则叠加：权限按"最后匹配规则生效"判定，若白名单开放了工具而 permission 未限制输入，等于把 bash 全权交给了该 agent。[S12] (4) prompt 用 "{file:...}" 引用文件，路径错误时提示退化为空，角色行为随之漂移而无告警。[S06]

验证条件。 定义两个 agent 做对照实验：一个只读 reviewer（禁写、禁 bash），一个可写 builder；用同一任务分别运行，核对 plan/reviewer 在遇到编辑与命令时确实触发 ask；把 steps 设为很小的值验证截断行为与日志可观测性；用 /agent 端点或 SDK 校验 agent 清单与配置文件一致；对 subagent 派发链路做一次端到端验证（主代理派发、子代理返回、结果合并）。[S06][S03][S12]

成本与权衡。 多 agent 编排的收益是权限最小化与提示隔离（reviewer 与 builder 用不同的系统提示与工具集），以及可复用的角色资产；成本是 token 与延迟：子代理需要重复读取上下文，长链路任务的总开销高于单 agent；调试复杂度也显著上升，因为失败可能发生在派发、子代理执行或结果合并任一段。判断口径：只在权限边界或提示边界确实不同时才拆 agent，否则用命令（.opencode/commands/*.md）封装流程更省。[S06][S08]

5.3 Provider 抽象与模型接入

接口与实现依据。 OpenCode 的模型层建立在 AI SDK 与 models.dev 目录之上，官方文档称支持 75+ provider；接入任意兼容端点的方式是声明 "npm": "@ai-sdk/openai-compatible" 并提供 options.baseURL，密钥支持 "apiKey": "{env:...}" 形式；文档给出了本地模型示例（如 LM Studio 上的模型标识 lmstudio/google/gemma-3n-e4b）。模型可以在 TUI 中选择，也可由 CLI --model、agent 定义的 model 字段、命令 frontmatter 指定，便于"角色绑模型"（例如 reviewer 用便宜模型、builder 用强模型）。[S09][S10][S13][S06]

失效边界与限制。 (1) 兼容 ≠ 可用：OpenAI 兼容通常只覆盖聊天补全接口，工具调用（tool calling）与流式工具结果的实现质量参差；一个端点"能聊天"不等于"能驱动 agent"，这是接入国产或自托管模型时最常见的坑。[S10]【P】(2) 结构化输出依赖 provider 能力：SDK 文档要求用 format 传 JSON schema 返回经验证的 JSON，若 provider 不支持相应能力，降级路径与错误形态需要实测。[S04] (3) 上下文与限流：不同模型的最大上下文与限流策略差异会直接改变长任务成功率与成本曲线。[S10]【P】(4) 配置漂移：模型标识随 provider 目录更新而变化，硬编码模型名在升级后可能失效。[S09]

验证条件。 为每个候选模型跑同一套"agent 冒烟四件套"：读文件（验证工具调用）、改文件（验证写权限路径）、执行命令（验证多轮工具循环）、结构化输出（验证 JSON schema）。再补三项：多轮工具调用后的上下文保持、限流下的重试与失败行为、把模型配置与 "{env:...}" 密钥分离并以版本库固化。全部通过后再把该模型写入默认配置。[S09][S10][S04]

成本与权衡。 开放 provider 的价值在于成本与合规可优化：可用本地或内网模型满足数据不出域，用低成本模型承担高频子任务；代价是质量方差与自建评测成本，工程上应把"模型可用性"当作持续集成项而不是一次性选型。托管网关（如官方 Zen）降低接入与计费复杂度，但把可用性与价格暴露给服务方；自建网关可做统一鉴权与配额，代价是运维与合规责任内移。[S10][S17]

5.4 Server 与 SDK：把 OpenCode 当作 agent 运行时

接口与实现依据。 opencode serve 启动无头服务端（支持 --port、--hostname、--cors），在 /doc 发布 OpenAPI 3.1 规范并明确 "Use the spec to generate clients or inspect request and response types"；GET /event 提供 SSE 事件流，首个事件为 server.connected，可用于构建实时 UI；会话侧提供创建会话、发消息（含 prompt_async 异步提示）、执行命令与 shell、fork、share、summarize、revert、查询会话权限等端点，资源侧提供 /agent、/config、/provider、/find、/file、/lsp、/mcp，另有 /tui/* 控制端点用于驱动官方 TUI。认证通过 OPENCODE_SERVER_PASSWORD 启用 HTTP basic auth。[S03] SDK 侧 @opencode-ai/sdk 提供 createOpencode()（同时拉起服务端与客户端，默认端口 4096）与 createOpencodeClient({ baseUrl })（连接已有实例），类型 "All types are generated from the server's OpenAPI specification"，并支持 event.subscribe 与结构化输出。[S04]

失效边界与限制。 (1) 部署定位：官方文档没有"公网暴露"的安全章节，把服务端当内网或本机服务更稳妥；若要对外提供服务，需要在前面自建鉴权、限流与审计。[S03]【P】(2) 接口稳定性：项目在 dev 分支推进 v2（已出现 v2.0.x tags 与 sdk-next 包），自建客户端要承担破坏性变更与迁移成本。[S01][S22]【P】(3) 语言与生态：packages/sdk 只提供 JS 客户端与 openapi.json，没有官方 Go/Python SDK，其它语言需自行从 OpenAPI 生成并自行维护。[S01][S04] (4) 长连接运维：依赖 SSE 的客户端必须实现断线重连与事件去重，否则会出现"界面卡在旧状态"的故障。[S03]【P】

验证条件。 建议以一条端到端冒烟作为验收基线：启动服务端 → 创建会话 → 发送消息 → 订阅事件 → 收到完成事件 → 取回结构化输出；再补三项契约测试：用 OpenAPI 生成的客户端固定用例回归、开启 OPENCODE_SERVER_PASSWORD 后未授权请求被拒、会话 fork 与 revert 后数据一致。把这套用例接进 CI，作为"上游升级后自建客户端是否仍可用"的门禁。[S03][S04]

成本与权衡。 SDK/Server 路线不需要维护 fork，升级成本低，且天然支持"多客户端"（Web、桌面、IM bot、CI 都可以是客户端）；代价是：自建客户端要把认证、会话存储、权限 UI、错误处理都做一遍——工作量远大于"接一个 API"；同时要把 API 变更当作外部依赖来管理。与插件相比，SDK 能完全掌控交互体验，但拿不到进程内 hook 那样的深度（例如无法直接替换内置工具实现）。因此实践上常见组合是：SDK 做产品形态，插件做行为深度。[S03][S04][S05]

6. 演进方向与情景

6.1 技术走向

第一，从"一个 CLI"变成"一个 agent 运行时"。client/server 架构、OpenAPI 规范、SSE 事件流、/tui/* 控制端点，加上官方列举的第三方客户端（Discord bot、VS Code 扩展、编辑器 ACP 集成），都指向同一方向：OpenCode 把自己定位成可被多种前端复用的运行时，而不是单一 TUI 产品。对自建工具而言这是最有利的结构性趋势。[S03][S04][S20]

第二，扩展生态向插件与 SDK 两端生长。插件层提供进程内行为深度（工具、聊天、权限、认证、系统提示），SDK 层提供产品形态自由（自建前端、服务化集成）；官方 ecosystem 页已经出现基于 SDK 的第三方项目与插件类项目，说明两端都有真实采用。[S05][S20][S23]

第三，版本演进带来短期不稳定性。仓库标签已出现 v2.0.x、包目录出现 sdk-next，说明 v2 正在推进；在 v2 落地前后，插件 hook 与 SDK 接口的兼容性是自建方案的主要技术风险，版本锁定与契约测试是必需的工程手段。[S01][S22]【P】

第四，商业化与开源并行但不绑死。Zen 网关、Go 订阅与企业版构成商业面，但 Zen 被明确标注为 "completely optional"，模型层仍向任意 provider 开放；企业版承诺不存代码与上下文、产出归用户所有。这意味着自建工具不依赖官方商业服务也能成立，但接入企业治理能力（SSO、审计）需要走企业版。[S17][S18][S19]

6.2 到 2028 年的三种情景

6.3 观察信号

建议按季度复核以下信号，用于判断"现在投入自建是否合算"：

1. v2 的发布与兼容承诺：v2.0.x 从 tags 转为正式发布线、官方是否给出插件与 SDK 的兼容策略。[S01][S22]
2. 插件 hook 的稳定性：experimental.* 类 hook 是否转正或被新接口替代，直接影响依赖深度行为的自建方案。[S23]
3. SDK 的官方语言覆盖：是否出现官方 Go/Python SDK；未出现则非 JS 技术栈需自维护生成的客户端。[S01][S04]
4. 企业治理与私有化能力：企业版 SSO、内部 AI 网关之外是否增加审计与策略接口，决定大型组织的采纳路径。[S19]
5. 生态项目存活率：官方 ecosystem 列表中的第三方项目（SDK 类与插件类）是否持续更新，是"这条路真的能走通"的最直接证据。[S20]

7. 建议与验收

7.1 先回答三个问题

问题一：可以在 OpenCode 基础上开发自己的 agent 工具吗？ 可以，而且这是官方架构明确支持的方向：MIT 许可允许修改与分发，client/server 架构允许替换客户端，插件系统允许在不 fork 的前提下改变行为，SDK 提供生成式的类型安全客户端。唯一的明文约束是品牌的：若产品名包含 "opencode"，须声明与官方无隶属关系。[S01][S03][S04][S05][S21]

问题二：走哪条路？ 取决于你要改的是"行为"、"产品形态"还是"内核"。三条路线的边界与代价见 7.2 表与图 3。

问题三：和直接用 Qoder、Codex、Claude Code 相比，什么时候值得自建？ 当出现下列任一需求时值得：需要把 agent 嵌入自有产品（Web、IM、内部平台）；需要替换客户端交互与品牌；需要深度定制工具链与权限策略；需要数据不出域或使用特定模型；需要与闭源平台的能力路线解耦。反之，若只是"想要一个好用的编码 agent"，四家的开箱产品都能覆盖，自建反而增加成本。[S03][S04][S29][S44]

7.2 三条自建路线选型表

组合建议：SDK 做产品形态，插件做行为深度，fork 只作为最后手段；如确需 fork，应把改动集中在最小模块并保留上游可合并的边界（例如以插件或独立包形式承载自有逻辑）。[S04][S05][S21]【P】

图 3：在 OpenCode 上自建 agent 工具的三条路线与代价（插件：改行为不改界面，成本最低；SDK/Server：自建前端或嵌入自有产品，不改内核但需自建认证与状态管理；fork：自由度最高但长期合并成本最高）。来源为 OpenCode 官方文档（plugins、sdk、server）与仓库 README 命名条款归纳；为路线示意，成本量级为工程判断。[S05][S04][S03][S21]

三条路线的自由度与维护成本同向增长，选型时应从最左侧能满足需求的路线开始评估，路线与代价关系见图 3。

7.3 工作包与验收条件

建议—验收矩阵

7.4 不建议做法

• 不建议在没有明确需求的情况下 fork。 fork 的代价不在第一次改动，而在长期跟进上游：项目正在 v2 迁移，合并成本会被放大。[S01][S22]
• 不建议把 experimental.* hook 当作稳定接口设计产品。 名称本身即表明不兼容承诺，依赖它们必须配合版本锁定与回归测试。[S23]
• 不建议把 OpenCode 服务端直接暴露到公网。 官方文档未提供面向公网部署的安全章节与加固清单，鉴权之外还需要自建限流与审计。[S03]【P】
• 不建议把插件当"零成本扩展"忽略依赖治理。 "plugin" 列表可以引用任意 npm 包并在 agent 进程内执行，等价于把第三方代码放进核心链路。[S05]
• 不建议在工具调用能力未验证前就接入国产或自托管模型。 兼容聊天接口不等于能驱动 agent，先跑"四件套"再上生产。[S10]【P】

8. 不确定性与研究限制

8.1 主要不确定性

1. v2 的兼容策略未公开。 仓库已出现 v2.0.x tags 与 sdk-next 包，但上游未给出插件 hook 与 SDK 的兼容承诺文本，自建方案的长期成本无法提前确定 [S01][S22]。
2. 插件隔离与错误处理缺乏文档。 官方文档未说明插件执行是否有超时、异常隔离或沙箱；本报告将其列为同进程风险，属推断 [S05]。
3. 闭源三方的内部机制不可验证。 Qoder、Codex、Claude Code 的扩展机制以官方文档为准，其内部调度、工具实现与安全模型无法从外部核实 [S26][S35][S39]。
4. 生态项目质量未经核查。 官方 ecosystem 列表只证明项目存在，未证明其维护活跃度与生产可用性 [S20]。
5. "国内无对等开源项目"是检索性结论。 该判断基于本报告检索范围，可能存在未被检索到的项目 [S46]【?】。

主张—证据矩阵

8.2 研究限制

本报告全部结论基于公开资料，未对任何工具做安装、运行或语义实测；文档中"可用""支持"等表述均来自官方文档口径，实际行为需按第 5 章与第 7 章的验证条件复现确认。星标、版本、包版本等数字为 2026-09-29 采集值。OpenCode 处在 dev 分支快速迭代期，引用接口细节时应以当时文档与代码为准。许可证相关表述仅复述官方原文，不构成法律意见。[S01][S03][S05]

参考来源

附录：研究方法

• 检索顺序：官方文档与仓库元数据优先；npm/GitHub API 用于核对版本与许可证字段；第三方资料只用于线索发现，不作为结论依据。
• 链接核验：台账链接均经访问核验；GitHub 页面在远端间歇不可达时改用 raw.githubusercontent.com 或 GitHub API 复核内容。
• 对照口径：跨工具对比统一按"官方文档是否定义接口"判定能力有无；对未公开的部分一律标注推断标记【P】或缺口【?】，不替厂商补全能力。
• 阅读顺序建议：若只关心结论，读第 1 章与第 7 章；若在做技术方案，读第 3.3 节（扩展面五层）、第 5 章（机制与边界）与 7.2 节（路线选择）。