---
title: "OpenCode 2"
author: "陈成"
author_url: "https://research.sorrycc.dev/@sorrycc"
question: "OpenCode 2 相比 v1 有哪些架构变化和亮点，社区怎么看？"
url: "https://research.sorrycc.dev/@sorrycc/opencode2"
emoji: "🧩"
published: 2026-10-23T09:38:06Z
updated: 2026-10-23T09:38:00Z
version: 3
cite: "https://research.sorrycc.dev/@sorrycc/opencode2.bib"
---

# OpenCode 2 调研报告

By [陈成](https://research.sorrycc.dev/@sorrycc) · Published October 23, 2026

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

| 项目 | 内容 |
|---|---|
| 日期 | 2026-10-23 |
| 对象 | OpenCode 2，2026-10-12 正式发布，当前版本 v2.1.3 |
| 依据 | 官方博客与 v2 文档、v2.1.3 源码、X 与 Reddit 社区讨论 |
| 专题文档 | `opencode2-code-mode-分析-2026-10-23.md`、`opencode2-新API-分析-2026-10-23.md` |

## 摘要

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

## 1. 时间线

| 时间 | 事件 |
|---|---|
| 2026-04-30 | 官方预告 2.0 将更易嵌入，支持分布式会话与断线重新同步 |
| 2026-08 | opencode2 beta 开放试用，约 1.5 万用户每日使用 |
| 2026-10-12 | 2.0 正式发布；Cloudflare 同日发布基于它的 OpenCodeHarness |
| 2026-10-20 至 22 | v2.1.0 至 v2.1.3 连续发布 |

## 2. 架构变化概览

| 维度 | v1 | v2 |
|---|---|---|
| 进程模型 | 每个客户端各自启动，server 模式需手动开启 | 本机单一常驻服务，所有客户端共享 |
| API | 逐步累积的路由，188 个操作 | 从零重写，146 个操作，由单一契约生成 |
| 工具调用 | 逐个调用，全部工具 schema 常驻 prompt | MCP 等长尾工具经 Code Mode 脚本化调用 |
| 扩展 | 插件系统存在但覆盖有限 | 80 余项内置功能以插件实现，全部可热重载 |
| 嵌入 | 需启动独立 server 并通过 HTTP 连接 | 进程内 SDK，无需监听端口 |

## 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，端点一一对应：

| | Promise 版 | Effect 版 |
|---|---|---|
| 依赖 | 无 Effect 依赖，基于 `fetch` | 依赖 Effect，HTTP 客户端可注入 |
| 数据 | JSON 结构，不做运行时校验 | 领域类型，运行时 Schema 校验 |
| 错误 | 以带标签的异常 reject | 体现在类型签名中 |
| 适用 | 脚本、前端、轻量集成 | 已采用 Effect 的项目，需要类型化错误、中断与依赖注入 |

官方选择 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 发布博客](https://anoma.ly/notes/opencode-2-0/)
- [热重载设计：OpenCode Reloaded](https://anoma.ly/notes/opencode-reloaded)
- [v1 至 v2 迁移文档](https://opencode.ai/v2/docs/migrate-v1/)
- [更新日志](https://opencode.ai/changelog)
- [源码 v2.1.3](https://github.com/anomalyco/opencode/tree/v2.1.3)
- [Cloudflare：Run OpenCode 2.0 on Cloudflare with the Agents SDK](https://developers.cloudflare.com/changelog/post/2026-10-12-opencode-harness/)

**社区**
- [@opencode 发布公告](https://x.com/opencode/status/2109649032931119362)
- [@thdxr：2.0 可嵌入与 event sourcing](https://x.com/thdxr/status/2049523023145771476)
- [@thdxr：几乎一切都是内部插件](https://x.com/thdxr/status/2087945880863191162)
- [@thdxr：图形界面与 `/pair`](https://x.com/thdxr/status/2092247685524865257)
- [@thdxr：内置 tool search 与 Code Mode](https://x.com/thdxr/status/2085865399195779308)
- [r/opencode：Is OpenCode v2 quietly becoming the better harness than Claude Code?](https://www.reddit.com/r/opencode/comments/1x7iqzv/is_opencode_v2_quietly_becoming_the_better/)
- [r/opencodeCLI：Opencode 2 stable?](https://www.reddit.com/r/opencodeCLI/comments/1xcgor3/opencode_2_stable/)