OpenCode 2 调研报告

By 陈成 · Published October 23, 2026

OpenCode 2 相比 v1 有哪些架构变化和亮点，社区怎么看？

摘要

• OpenCode 2 是一次架构重写，不是功能迭代。核心变化有六项：常驻后台服务、新 API、Code Mode、后台任务、插件化与热重载、可嵌入的 SDK。
• 定位从"终端里的编码助手"转向"可嵌入的 agent 后端"。TUI、Web、桌面端都只是同一个服务的客户端，同一套代码还能运行在用户进程或 Cloudflare Durable Object 中。
• 设计重心是长时间运行、多客户端并存、允许断线的场景。具体做法是持久化的输入队列、可续读的事件日志，以及不破坏 prompt cache 的工具清单更新。
• 主要代价是兼容性。v1 插件和 Server API 全部失效，实验性接口占比较高，发布节奏和版本说明也不够清晰。

1. 时间线

2. 架构变化概览

3. 核心特性

3.1 常驻服务与多端客户端

• 服务以单一后台进程运行。TUI、Web、桌面端连接同一进程，多个会话共享资源，社区反馈的主要收益是多会话下内存占用更低。
• 会话与窗口解耦。关闭终端不会中断会话，可在其他客户端继续操作。
• 图形界面内部称为 "gooey"。通过 /pair 在浏览器中打开，默认启用密码认证，可经 Tailscale 等方式远程访问，并支持作为 PWA 安装。
• 已知问题包括服务启动等待、端口冲突，以及桌面端性能和完成度不及部分竞品。

3.2 新 API

• 单一契约。 接口用 Effect HttpApi 和 Schema 定义一次，OpenAPI、Promise 客户端和 Effect 客户端均由此自动生成，CI 校验生成结果与契约一致。
• 输入持久化。 发送消息不再同步等待回复，而是写入会话收件箱后立即返回。调用方可选择插入当前执行（steer）或排队（queue）。客户端可指定消息 ID，重试具备幂等性。
• 事件可续读。 实时事件流在断线期间会丢失事件，另提供带序号的会话事件日志，客户端重连后可从断点补齐。这一机制对应官方确认采用的 event sourcing。
• 资源模型完整。 会话支持创建、分叉、迁移、导入导出与归档，并提供表单、权限、终端、MCP、凭据等资源接口。插件可通过 RPC 对外提供接口。
• 类型化错误。 定义 31 种错误类型，各对应固定 HTTP 状态码。
• 服务发现与认证。 客户端可自动发现并拉起本地服务。配对签发 30 天有效的会话令牌，修改服务密码即全部失效。
• 自调用。 agent 可通过 API 管理自身会话与 worktree，例如新建 worktree 并将当前会话迁入。

3.3 Code Mode

• 机制。 模型通过一个 execute 工具提交 JavaScript 脚本，在脚本中调用、组合工具，只有最终返回值进入上下文。
• 适用范围。 读写文件、shell、子代理等主力工具仍为直接调用。Code Mode 承载 MCP 工具（默认全部接入）、OpenCode 自身的会话与 worktree 工具，以及桌面端的浏览器控制工具。
• 运行时。 自研的 JavaScript 子集解释器，基于 Acorn 解析，未采用 QuickJS 或 V8 isolate。程序只能通过宿主授予的工具与 fetch 访问外部，不存在文件系统、进程或模块能力，所有跨边界数据均为拷贝。
• 上下文控制。 工具描述保持不变以利于 prompt cache。工具清单单独注入，预算约 2000 token，超出部分通过 search() 按需检索。工具集变化时只下发差异。
• 可配置性。 可按 MCP server 关闭 Code Mode，也可通过权限规则整体禁用。
• 风险。 当前未设置执行超时、调用次数与输出大小上限，也没有并发限制。部分失败需模型自行处理。工具检索仅支持 ASCII 关键词匹配。

3.4 后台任务

• 子代理和 shell 命令可在后台执行，完成后通知主 agent。子代理可指定不同模型。
• 运行中的前台任务可通过 ctrl+b 转入后台。
• 同类能力在 Claude Code 等工具中已有，OpenCode 2 的特点是与常驻服务结合，后台任务不依赖客户端存活。

3.5 插件化与热重载

• 内置 agent、集成、配置加载、system prompt 等 80 余项功能以内部插件实现，可单独禁用，插件 API 由官方自身持续使用。
• 配置、MCP、插件的变更立即对所有会话生效，模型可在同一轮中编写并调用新工具，无需重启，也不破坏 prompt cache。实现方式是每类状态由一组可重放的变换构建，重载时从空状态重新执行。
• TUI 插件已转为稳定，社区已出现 vim 模式、文件树、用量统计、目标模式等插件。
• 这一方向与 deepseek-harness 的 "Everything is a Plugin" 一致。

3.6 SDK 与 Effect API

• @opencode/sdk 与 CLI 共用代码，在调用方进程内运行同一套 router，不监听端口、无网络开销。默认内存存储，可配置数据库实现重启恢复。
• 支持按会话选择插件实例，例如为每个 Slack 线程加载不同插件。官方说明该机制不构成授权或存储隔离边界。
• 提供 Workerd 入口，可运行于 Cloudflare Durable Object。
• 同时提供 Promise 与 Effect 两种 API，端点一一对应：

官方选择 Effect 的理由有两点：规模扩大后稳定性问题集中暴露；AI 生成 Effect 代码的质量较高。

4. 升级与迁移

• 升级方式为先更新到最新 1.x，再执行 opencode upgrade --major。v1 与 v2 共用 opencode 命令，默认不能并存。
• 破坏性变更共三项：插件 API 全新，v1 插件不可用；Server API 与客户端协议全新；tui.json 迁移为全局 cli.json（自动完成）。
• 其余配置与 .opencode/ 文件保持兼容。原生 v2 配置的主要变化是权限改为有序规则数组，并统一了若干字段命名。
• 安全相关默认值有变化：v2 默认允许访问项目目录以外的路径，如需保持 v1 行为须显式配置。
• 官方建议由 OpenCode 自身执行配置与插件迁移。

5. 社区反馈

正面

• 单进程架构在多会话场景下资源占用明显更低。
• 后台子代理与并行执行被普遍视为升级的主要理由。
• Code Mode 缓解了大量 MCP 导致的上下文膨胀。
• 多模型、多订阅用户认为其灵活性优于单一厂商工具。

负面

• 发布初期版本状态不清：GitHub Release 仍显示 1.x，更新频繁且版本说明不完整。
• 插件迁移成本高，社区插件质量参差。
• 界面层面存在并行操作难以追踪、标签页占用空间、桌面端偏慢等问题。
• 会话间协同与整体打磨仍被认为不及 Claude Code。

6. 评估

优势

• 以契约驱动的 API 与可嵌入 SDK 使其适合作为平台底座，第三方集成有稳定依据。
• 持久化输入、幂等重试与可续读事件，针对的是 agent 长时运行和多端接入的实际问题。
• Code Mode 与清单增量更新的组合，在工具规模与 prompt cache 之间取得了可行的平衡。
• 插件化与热重载让定制成本显著下降，并支持 agent 自我扩展。

风险

• 146 个 API 操作中有 32 个处于实验阶段，事件日志、导入导出等关键能力尚未稳定。
• Code Mode 缺少默认资源限制，复杂脚本也降低了操作的可审查性。
• 生态迁移尚未完成，依赖 v1 插件或 API 的用户短期内需要投入改造。
• 默认放开项目外路径访问，对安全敏感场景需要额外配置。

参考资料

官方

• OpenCode 2.0 发布博客
• 热重载设计：OpenCode Reloaded
• v1 至 v2 迁移文档
• 更新日志
• 源码 v2.1.3
• Cloudflare：Run OpenCode 2.0 on Cloudflare with the Agents SDK

社区

• @opencode 发布公告
• @thdxr：2.0 可嵌入与 event sourcing
• @thdxr：几乎一切都是内部插件
• @thdxr：图形界面与 /pair
• @thdxr：内置 tool search 与 Code Mode
• r/opencode：Is OpenCode v2 quietly becoming the better harness than Claude Code?
• r/opencodeCLI：Opencode 2 stable?

Read this report as Markdown · Cite it (BibTeX)