从 OpenCode 1 迁移到 2
资料核验：2026-10-15。 依据官方 V1 → V2 迁移文档↗；本站未运行上游迁移程序。下面是迁移前后需要核对的步骤。
# 1. 保存可回退的 V1 环境#
记录 opencode --version、安装渠道和可执行文件路径，备份全局配置、项目 opencode.json(c)、.opencode/ 和需要保留的数据。凭据备份应保留在本机私有位置，不要提交到 Git。
V1 / V2 都使用 opencode。包管理器安装的 V1 应先由原渠道卸载；V2 curl 安装器会替换 V1 二进制。安装命令见 V2 安装。需要回退时，通过原渠道恢复 V1，并恢复 V1 备份；不要让 V1 读取已经转成 V2 专用结构的文件。恢复数据前先关闭有关进程，不要用旧备份覆盖仍在写入的数据。
# 2. 先保留兼容配置，再按需转换#
V2 继续读取全局 ~/.config/opencode/opencode.json(c)、项目 opencode.json(c) 等既有位置，并在内存中规范化受支持的 V1 字段，不要求先重写源文件。官方配置文档↗使用 JSON / JSONC；编辑 V2 原生配置时应采用 V2 Schema 和字段，不能直接套用 V1 示例。
先在一个项目核对模型、凭据、代理、权限、MCP 与 Skills。V1 文件可读并不等于所有功能都保留：当前迁移文档明确说 lsp 配置会被接受，但 V2 不运行语言服务器或 LSP 诊断；应改用项目的类型检查、编译和 lint。V2 分享文档↗也明确说目前不支持会话分享，不能由 share 字段被接受推导分享功能可用。
# 3. 分清三种配置文件#
| 文件 | 用途 | 主版本 |
|---|---|---|
opencode.json / opencode.jsonc | 模型、提供商、权限等运行时设置 | V1 / V2（字段兼容范围有区别） |
tui.json / tui.jsonc | 分层终端设置 | V1 |
~/.config/opencode/cli.json | 单一全局终端设置 | V2 |
V2 的 cli.json 支持 $XDG_CONFIG_HOME/opencode/cli.json，没有项目级 CLI 配置文件。它不存在时，首次启动 V2 终端客户端会迁移受支持的全局 TUI 设置与已保存偏好，保留 V1 文件；项目本地终端设置不参与迁移。V1 v1.19.0 从旧 opencode.json(c) 拆出 tui.json 是另一套迁移，见 V1 TUI 说明。
例如 V2 全局 cli.json 的主题设置为对象：
json1{ 2 "$schema": "https://opencode.ai/v2/cli.json", 3 "theme": { 4 "name": "tokyonight", 5 "mode": "system" 6 } 7}
其结构、热重载和有效字段以 V2 CLI 设置↗为准；不要把 V1 的主题字符串、快捷键表或滚动字段整块复制进去。
# 4. 逐项确认兼容边界#
- 插件： V2 更换插件 API。V1 插件实现不能直接运行，修改
plugin/plugins键名或移动目录并不足够；先确认作者提供了适配版。 - 服务器集成： V1 API 与客户端契约变化，调用方应迁移到 V2 API；不能只替换服务地址。
- Skills 和文件定义： 受支持的既有代理、命令和 Skills 可继续使用。移动 Skill 时保留完整目录，避免丢失相对引用的脚本和资源。
- 认证： 支持的旧
auth.json凭据会在数据库迁移时导入；新凭据存入服务器 SQLite，不再回写旧文件，见认证排障。
逐项验证通过后再决定是否转换为 V2 原生字段。若只希望先试用，不必同时重写所有配置。需要迁移插件或 API 时，应按官方对应指南单独验证。