升级指南
当你需要将 OpenCode 从一个版本升级到较新版本时，使用本指南。内容覆盖多个组件（CLI、TUI、Web、桌面端、SDK）、可能需要更新的配置文件，以及出现问题时的处理步骤。
开始之前
- 记录当前版本：
opencode --version。 - 在 releases 页面选择目标版本。
- 阅读两个版本之间的 release notes。
- 备份配置文件（
opencode.json、~/.opencode/以及工作区专用配置）。
组件关系
OpenCode 同一发布线会包含多个组件。一般建议将它们保持在同一 minor 版本，避免意外差异。
| 组件 | 运行位置 | 说明 |
|---|---|---|
| CLI | 本机终端 | 其他组件的参考实现 |
| TUI | 本机终端 | 基于 CLI 构建 |
| Web | 浏览器 + 本地服务器 | 本地服务与 CLI 共用同一二进制 |
| Desktop | 原生窗口（macOS、Windows、Linux） | 仍处于 beta；功能与 CLI 对齐 |
| SDK | 集成到自己的应用 | 跟随 CLI 公共 API |
如果只使用 CLI 和 TUI，可以原地升级。如果同时使用 Web 或 Desktop，建议一起升级，保持行为一致。
配置迁移
OpenCode 保留大多数配置的向后兼容，但部分键名已经替换或重命名。常见例子：
- 旧的
tools布尔配置已合并到permission。旧键仍然被接受，但会输出弃用警告。可按需迁移到permission。 ~/.opencode/中的自定义工具与命令遵循 Commands 和 Tools 中的当前 schema。
如果 opencode doctor 或 TUI 输出弃用警告，请在下一个 major 版本前完成迁移。
模型替换
模型可用性会频繁变化。升级前：
- 查看 Models 总览，了解目标版本中新增的弃用模型。
- 将写死的模型 ID（如带日期的
<provider>/<model>）替换为稳定别名或 provider 当前推荐名称。 - 如果使用 OpenCode Zen，请在 opencode.ai/zen 查看当前目录与定价。
升级步骤
具体命令取决于安装方式。按平台选择：
- macOS / Linux（安装脚本）：重新运行脚本，会检测当前版本并原地替换。
curl -fsSL https://opencode.ai/install | bash - Homebrew：
brew upgrade anomalyco/tap/opencode（若使用官方 formula，则升级opencode）。 - npm / pnpm / yarn：
npm i -g opencode-ai@latest（或对应包管理器）。 - Scoop / Chocolatey：
scoop update opencode或choco upgrade opencode。 - Docker：拉取新镜像并重启容器；Docker 指南 列出支持的 tag。
- 桌面应用：使用应用内更新（Help → Check for Updates），或从 下载页 重新安装。
升级完成后：
- 运行
opencode --version确认新版本。 - 运行
opencode doctor（如可用）或 TUI，查看任何配置警告。 - 重新执行一个小型代表性任务，再恢复日常使用。
回滚
如果升级后关键工作流失败：
- 使用相同的安装方式重新安装上一个版本。
- 还原已备份的
opencode.json和~/.opencode/中的自定义配置。 - 若新默认模型与你的 provider 不兼容，重新锁定模型 ID。
- 在 GitHub issues 提交问题，包含失败版本、复现步骤和错误输出。
何时可以跳过升级
你不必每次发布都升级。在以下情况可以跳过：
- 发布说明中没有影响你的变更。
- 你依赖的关键插件或 provider 集成尚未在新版本上验证。
- 你正在处理事故，而新版本不包含与该事故相关的修复。