OpenCode 2.0 架构与使用说明

版本：2.0.27 · 发布日期：2026-10-12（公测 2026-07-10）· 文档定位：架构说明 + 关键操作参考

速查：关键结论

一、架构

1.1 从单进程改为客户端 / 服务端

V2 中，后台服务持有一切核心状态与能力：

• 会话（sessions）
• 配置（configuration）
• 插件（plugins）
• 权限（permissions）
• 工具执行（tool execution）

客户端只负责界面渲染与输入，属于"瘦客户端"。

1.2 进程拓扑

     TUI（终端）        ─┐
     桌面 App           ─┤
     网页浏览器          ─┼── HTTP / SSE ──►  后台服务（本地 HTTP 服务器）
     程序化客户端        ─┤                     ├─ 会话 / 配置 / 插件 / 权限 / 工具执行
     自研客户端          ─┘                     ├─ REST API + OpenAPI
                                                └─ Web UI

1.3 后台服务的形态

后台服务本质是一个 HTTP 服务器：

• 默认监听地址：127.0.0.1（仅本机）
• 默认端口：49374（可修改）
• 同时对外提供：Web UI、REST API、SSE 事件流、OpenAPI 规范

即：网页版界面不是额外的前端工程，而是由同一个服务在本机原生提供。

1.4 相关包（V2 新增）

三者的详细介绍、对比与使用示例见《OpenCode 2.0 新增开发包：client / codemode / sdk》。

二、数据与文件位置

说明：

• 会话、项目等持久数据都存放在数据库中，不随客户端关闭而消失。
• 请勿在排障时直接删除或编辑服务文件与数据库，使用 opencode service 系列命令进行管理；如需查看，请先备份。

三、升级后原有会话的位置

结论：升级到 V2 后，原有会话仍然保留在本地数据库中，可直接访问。

访问方式（TUI）：

相关迁移说明：

• 终端客户端配置由 V1 的分层 tui.json(c) 迁移为单一全局 cli.json（首次启动自动迁移，V1 文件保留）。
• 配置、agents、commands、skills 等受支持的 V1 功能在 V2 中仍可使用。
• 旧会话数据存放在同一数据库中，可在新版本中继续打开。

四、接入方式

远程方式补充：

• 首次执行 opencode pair --remote 会提示"是否将服务器暴露到公网"，需确认。
• 非交互环境需附加 --yes。
• 接受后保持开启，后续执行仅生成新的配对链接。
• 关闭远程：opencode service set remote false + opencode service start。

五、鉴权与配对

服务默认受密码保护，任何客户端（含本机浏览器）首次访问都需要登录。

5.1 两种登录方式

5.2 配对链接的兑换结果

打开 .../auth/connect/<code> 时，按请求类型返回不同结果：

• 会话 Cookie 名称形如 opencode_session_49374，有效期 30 天。
• 配对链接 5 分钟内有效，且只能使用一次；重复使用返回 401（提示已过期或已使用）。

5.3 使用要点

• 配对链接仅用于首次登录；登录成功后应直接访问基础地址，无需再次输入链接。
• 浏览器会保留 30 天会话 Cookie，关闭浏览器不影响登录状态。
• Cookie 按来源主机区分：127.0.0.1 与远程域名的 Cookie 相互独立，应固定使用同一入口。
• 查看服务器密码：opencode service get password
• 设置服务器密码：opencode service set password "新密码"

六、服务管理命令

常用配置项：

# 监听所有网络接口（供局域网接入）
opencode service set hostname 0.0.0.0

# 固定端口
opencode service set port 49374

# 修改服务器密码（会使所有会话登出）
opencode service set password "a-long-secret"

# 关闭远程访问
opencode service set remote false

注意：修改任意配置都会停止后台服务，需再执行 opencode service start 生效；重启会断开当前所有客户端，但会话数据不会丢失。

七、设备与会话管理

• V2 当前不提供"按设备撤销"功能：设置中只有"Pair device（添加设备）"入口，没有已连接设备列表或单独撤销项，接口层面亦无对应接口。
• 唯一的一键吊销方式是修改服务器密码：修改密码会使全部已登录会话登出。
• 登录会话有效期为 30 天，到期需重新登录。
• 配对链接为一次性且 5 分钟有效，不会长期滞留。

八、自研客户端要点

服务对外暴露标准 HTTP 接口，且项目开源，可据此开发自有客户端。

注意事项：

• 事件流为"尽力而为"：慢消费者会导致流中断，断线期间事件会丢失。客户端必须实现断线重连，并在重连后全量重新拉取状态；事件仅作增量提示，状态以 REST 为准。
• 带 /api/experimental/* 前缀的接口属实验性，可能变更，不宜重度依赖。
• 版本迭代较快，接口契约可能调整。
• 鉴权 Cookie 名称包含端口（如 opencode_session_49374），修改端口后名称随之变化。

九、破坏性变更与升级

升级命令：

opencode upgrade --major

V2 有三处明确的破坏性变更：

1. 插件不兼容：1.0 插件无法在 2.0 运行，需按新的插件 API 重写。
2. 服务器 API 重写：调用旧服务器 API 的集成需迁移到 @opencode/client。
3. 配置文件迁移：tui.json 迁移为全局 cli.json（首次启动自动迁移）。

其他需要注意的变更：

• V2 仅读取 AGENTS.md，不再回退到 CLAUDE.md。
• compaction.prune 被忽略，并产生告警。

十、常用 TUI 快捷键

以下 leader 键为 Ctrl+X。

参考

• 官方发布说明：OpenCode 2.0 launch note（Anomaly，2026-10-12）
• 更新日志：opencode.ai/changelog（v2.0.27，2026-10-12）
• V2 文档：opencode.ai/v2/docs/