OpenCode TUI 完全使用教程

外观

附录 E · 从 OpenCode V1 迁移到 V2 ​

本附录帮助仍在使用 OpenCode 1.x 的用户平滑升级到 V2。核心结论先行：绝大多数配置和文件无需改动即可继续工作，真正必须处理的只有「插件」和「调用服务端 API 的集成」。

一、先建立正确认知 ​

V1 与 V2 使用同一个 opencode 命令，默认不再并行安装。三个有意为之的破坏性变更：

  1. 插件 API 重写 —— V1 插件不能在 V2 运行，必须移植；
  2. 服务端 API 与客户端契约变更 —— 调用服务端 API 的集成要改；
  3. 终端客户端配置从分层的 tui.json(c) 收敛为单个全局 cli.json（会自动迁移）。

除此之外，受支持的服务端配置、Agent / Command 定义、Skills、.opencode/ 下的文件应当无需改动继续生效。若官方迁移指南承诺兼容的行为在 V2 失效，应视为兼容性 bug，去报 issue，而不是自己硬改。

二、推荐迁移顺序 ​

不必重写一切再启动 V2。务实路径：

  1. 保留现有配置与基于文件的定义，直接启动 V2；
  2. 验证模型、凭证、Agent、权限、MCP 服务；
  3. 移植插件（V1 插件无法运行）；
  4. 移植调用服务端 API 的集成；
  5. （可选）准备好后再把配置转换成 V2 原生形态。

⚠️ 验证期间保留一份 V1 环境。V1 与 V2 使用相同配置位置，一旦把文件改成 V2 独有形态，就不要再让 V1 读取它们。

三、指令文件：CLAUDE.md → AGENTS.md ​

这是本教程读者最该注意的一点：

  • 现有的 AGENTS.md 保持原位：V2 会发现全局 ~/.config/opencode/AGENTS.md，以及从当前目录向上直到 home 的各级 AGENTS.md（家目录之外的项目，发现止步于项目根）。
  • 如果 V1 时期依赖 CLAUDE.md 兜底，请把其中规则迁移到对应的 AGENTS.md——V2 只识别 AGENTS.md，没有 CLAUDE.md 回退。

四、终端客户端配置：tui.json → cli.json ​

  • V2 用单个全局 ~/.config/opencode/cli.json 取代 V1 分层的 tui.json(c)；
  • 该文件归终端客户端所有，后台服务不加载；
  • cli.json 缺失时，首次启动 V2 客户端会自动迁移受支持的全局 tui.json 设置与持久偏好，且不改动 V1 原文件；
  • 项目本地的客户端配置不会迁移，因为 V2 的客户端配置是全局的。

五、权限：按工具分组 → 有序数组 ​

V1 按工具分组写效果，V2 改为一个有序 permissions 数组，优先级与例外更清晰：

jsonc
// V1
{
  "permission": { "bash": { "git push *": "ask" }, "edit": "allow" },
  "tools": { "websearch": false }
}

// V2
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

六、共享策略：autoshare → share ​

jsonc
// V1
{ "autoshare": true }
// V2
{ "share": "auto" }   // 可选：manual / auto / disabled

七、供应商：命名空间与过滤器 ​

  • V2 合并了两个历史供应商命名空间，迁移时使用规范化的 V2 供应商 ID；
  • 模型仍嵌套在其供应商下，模型 ID 采用 provider/model#variant，供应商专属选项放在对应字段；
  • V1 的 enabled_providers / disabled_providers 没有一对一的原生字段，其行为通过内部 Policies（默认 deny + 逐条 allow，或对所列者 deny）继续支持。

八、配置转换的注意事项 ​

  • V2 在内存中规范化受支持的 V1 字段，不重写源文件，可先不转换；
  • 推荐让 OpenCode 帮你转换：「把我的 OpenCode 配置（含文件定义）从 V1 迁移到 V2 原生形态，保持行为与无关设置不变」；
  • V1 与 V2 顶层字段可共存，同一规范值都设置时，合法的 V2 值优先；
  • 嵌套混用有边界：mcp / compaction / experimental 内可混用，但单个 Agent / Provider / Command / Model 条目必须整体只用一种格式；
  • 某些 V1 schema 接受、但 V2 无对应项的字段会被有意忽略（见官方「Accepted but unsupported fields」）。

九、上线前自检清单 ​

  • [ ] 模型与默认模型正确
  • [ ] 各供应商凭证有效
  • [ ] Agent 定义与权限符合预期
  • [ ] MCP 服务可连接
  • [ ] 插件已移植到新 API
  • [ ] CLAUDE.md 规则已并入 AGENTS.md
  • [ ] 关键任务在真实项目里跑通一遍

完成这些，你就可以放心把日常工作切换到 V2。