进阶 opencode.ai 2026-11-11 16:13:22 · 20 阅读

第5章 OpenCode V1 至 V2 迁移指南:破坏性变更与配置兼容

从 V1 迁移 OpenCode 1 和 OpenCode 2 均使用 opencode 命令,且默认不再允许两者并行安装。安装 V2 前请先卸载由包管理器安装的 V1 版本;V2 的 curl 安装脚本会替换掉 V1 二进制文件。

V2 包含三项有意的破坏性变更:

- 插件使用全新的 Plugin API。 - 服务端 API 及客户端引入了新的接口契约。 - 终端客户端配置从分层的 tui.json(c) 文件迁移至单一的全局 cli.json 文件(支持自动迁移)。

除上述区域外,V1 支持的功能旨在与 V1 保持兼容。部分 V1 schema 中接受的字段在 V2 中无对应项并被有意忽略,详见“已接受但不支持的字段”。.opencode/ 目录下的现有受支持服务端配置字段、agent 定义、命令定义、技能及其他文件应无需修改即可继续工作。如果本指南中描述的受支持行为在 V2 中失效,请将其视为兼容性 bug,而非预期的迁移要求。

按照安装说明安装 V2 终端客户端。 无需在启动 V2 前重写所有配置。实际的迁移流程如下:

- 保留现有配置和基于文件的定义。 - 启动 V2,验证模型、凭据、agent、权限及 MCP 服务器。 - 移植插件,因为 V1 的插件实现无法在 V2 中运行。 - 移植调用服务端 API 的集成。 - 在准备就绪时,将配置转换为原生 V2 格式。此步骤是可选的。

在验证迁移期间,请保留一份 V1 配置的副本。由于 V1 和 V2 使用相同的配置路径,将文件转换为仅适用于原生 V2 的格式后,请勿再让 V1 指向这些文件。

本节涵盖 .opencode/ 下的 JSON/JSONC 配置和基于文件的定义。

V2 从与 V1 相同的路径读取现有的系统级、全局和项目级配置: /Library/Application Support/opencode/opencode.json(c) /etc/opencode/opencode.json(c) %ProgramData%\opencode\opencode.json(c) /Library/Managed Preferences//ai.opencode.managed.plist /Library/Managed Preferences/ai.opencode.managed.plist ~/.config/opencode/opencode.json(c) /opencode.json(c) /.opencode/opencode.json(c) V2 在内存中规范化受支持的 V1 和原生 V2 字段,而不重写源文件。现有的受支持 V1 配置旨在继续工作,因此尝试或采用 V2 时不需要将其转换。 与 V1 一样,系统配置和 macOS 托管偏好具有最高优先级,其设置会覆盖全局和项目文件。它们的策略(包括迁移后的 enabled_providers 和 disabled_providers)也优于全局和项目策略。覆盖某项设置无法阻止用户添加 provider、MCP 服务器、agent 或插件,因此应以策略形式表达管理员强制的限制,而非 permissions 等普通设置。

V1 配置格式仍受支持。原生 V2 格式是可选的,使某些设置更加显式和易用。 推荐的迁移路径是让 OpenCode 自动更新配置: “将我的 OpenCode 配置(包括基于文件的定义)从 V1 格式迁移到原生 V2 格式。保留其行为及所有无关设置。” OpenCode 可以检查完整文件,应用以下相关更改,并避免重写无需更改的设置。转换无需一次性完成:受支持的 V1 和原生 V2 字段可以在顶层共存。当两种格式设置了相同的规范值时,无论 JSON 键的顺序如何,有效的原生 V2 值都优先。嵌套混用受到有意限制。OpenCode 识别 mcp、compaction 和 experimental 中混合的 V1 和 V2 成员,但不会在单个 agents、providers、commands 或 models 内部递归推断格式。请保持这些嵌套条目完全使用一种格式。受支持的 V1 语法本身保持静默;格式错误的值、不支持的旧字段以及冲突的 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" } ] } 权限操作也发生了变化:bash 现为 shell,task 现为 subagent,write 和 patch 现为 edit。 请参阅“Permissions”了解有序的 V2 规则格式。 V2 中 Todos 默认关闭。若要开启,请使用 experimental 标志。该标志可能在未来的发行版中更改或移除;请参阅“Experimental”。 JSONC { "experimental": { "todo": true, }, }

单数 agent 和已弃用的 mode 映射变为 agents。Agent 字段变得更加一致,与 V2 配置的其他部分保持一致: JSONC // V1 { "agent": { "reviewer": { "prompt": "Review for correctness and missing tests.", "model": "anthropic/claude-sonnet-5-5", "variant": "high", "disable": false, "permission": { "edit": "deny" } } } }

// V2 { "agents": { "reviewer": { "system": "Review for correctness and missing tests.", "model": "anthropic/claude-sonnet-5-5#high", "disabled": false, "permissions": [ { "action": "edit", "resource": "*", "effect": "deny" } ] } } } prompt 变为 system,disable 变为 disabled,单独的 variant 在 # 之后合并到模型引用中。 maxSteps 变为 steps。旧 mode 映射中的条目变为 primary agents。 Agent 的 request.body 保留但不会发送给模型,因此 V1 中的 temperature、top_p 和 options 在此处无效。改为在模型变体上设置。DeepSeek 仅在关闭 thinking 时应用 temperature,因此此变体也关闭 thinking: opencode.jsonc { "providers": { "opencode": { "models": { "deepseek-v4.1-flash": { "variants": [{ "id": "review", "body": { "thinking": { "type": "disabled" }, "temperature": 0.2 } }], }, }, }, }, "agents": { "reviewer": { "model": "opencode/deepseek-v4.1-flash#review" }, }, } 使用 body 设置 provider JSON 字段,使用 settings 设置 provider 包选项。请参阅“model options”。

将单数 snapshot 字段重命名为 snapshots。其布尔值不变: JSONC // V1 { "snapshot": false }

// V2 { "snapshots": false }

将单数 attachment 对象重命名为 media。嵌套的 image 设置保留原名称: JSONC // V1 { "attachment": { "image": { "auto_resize": true } } }

// V2 { "media": { "image": { "auto_resize": true } } }

V2 将服务器分组在 mcp.servers 下,用 disabled 替代 enabled,并分离超时用途: JSONC // V1 { "mcp": { "playwright": { "type": "local", "command": ["npx", "@playwright/mcp"], "enabled": true, "timeout": 30000 } } }

// V2 { "mcp": { "servers": { "playwright": { "type": "local", "command": ["npx", "@playwright/mcp"], "disabled": false, "timeout": { "catalog": 30000, "execution": 30000 } } } } } 远程 OAuth 字段使用 snake case:clientId 变为 client_id,clientSecret 变为 client_secret,callbackPort 变为 callback_port,redirectUri 变为 redirect_uri。V1 的 experimental.mcp_timeout 值也变为 mcp.timeout.catalog 和 mcp.timeout.execution 的默认值。请参阅“MCP 服务器”。

V2 将保留上下文的 token 预算分组在 keep 下,并赋予 reserve 更清晰的名称: JSONC // V1 { "compaction": { "preserve_recent_tokens": 8000, "reserved": 20000 } }

// V2 { "compaction": { "keep": { "tokens": 8000 }, "buffer": 20000 } } V1 的 token 数量原样保留。V2 还接受模型窗口大小的百分比,例如 "buffer": "15%",这适用于不同窗口大小的模型。 auto 保留其名称。V2 没有原生的 tail_turns 或 prune 字段;这两个旧字段会被忽略并产生警告。改为通过 token 预算保留最近的上下文。请参阅“Compaction”。

V1 将额外的技能路径和 URL 分开。V2 将两者合并为一个有序数组: JSONC // V1 { "skills": { "paths": ["./team-skills"], "urls": ["https://example.com/skills/"] } }

// V2 { "skills": ["./team-skills", "https://example.com/skills/"] } 现有的技能文件和自动的 .opencode/skills/ 发现机制不变。请参阅“Skills”。

将单数 command 映射重命名为 commands,subtask 重命名为 subagent。将单独的模型变体合并到模型引用中: JSONC // V1 { "command": { "review": { "template": "Review the current changes.", "model": "anthropic/claude-sonnet-5-5", "variant": "high", "subtask": true } } }

// V2 { "commands": { "review": { "template": "Review the current changes.", "model": "anthropic/claude-sonnet-5-5#high", "subagent": true } } } template、description 和 agent 保留原名称。旧的 subtask 仍被接受;委托的命令现在自动在后台运行,并将结果报告给父会话。现有的 Markdown 命令定义继续受支持。 请参阅“Commands”。

将已弃用的单数 reference 映射重命名为 references: JSONC // V1 { "reference": { "docs": "../docs" } }

// V2 { "references": { "docs": "../docs" } } V1 已经接受 references,因此当文件使用它时无需更改。Reference 条目保留相同的结构。请参阅“References”。

将单数 provider 映射重命名为 providers。V2 分离运行时包、端点和请求设置: JSONC // V1 { "provider": { "acme": { "npm": "@ai-sdk/openai-compatible", "api": "https://llm.example.com/v1", "options": { "apiKey": "{env:ACME_API_KEY}" } } } }

// V2 { "providers": { "acme": { "package": "aisdk:@ai-sdk/openai-compatible", "settings": { "baseURL": "https://llm.example.com/v1", "apiKey": "{env:ACME_API_KEY}" } } } } V1 的 npm 变为 package,AI SDK 包添加 aisdk: 前缀。api 变为 settings.baseURL。Provider 选项根据其请求角色分离为 settings、headers 和 body。options.setCacheKey 变为 provider 上的 compatibility.supportsPromptCacheKey。请参阅“Providers”。 V2 整合了两个旧的 provider 命名空间: V1 Provider ID | V2 规范 Provider ID azure-cognitive-services | azure google-vertex-anthropic | google-vertex 对无歧义的 V1 provider、agent、command 和 provider-filter 字段的迁移使用这些规范 ID。共享的顶级 model 字段保留其确切的 provider ID,因为相同的语法在原生 V2 配置中有效;迁移旧内置 provider 时,请将该字段更新为规范 ID。

Models 仍嵌套在其 provider 下,但多个模型字段变得更加显式:

- id 变为 modelID。 - tool_call 和 modalities 变为 capabilities.tools、capabilities.input 和 capabilities.output。 - 状态 "deprecated" 变为 disabled: true。 - 缓存成本从 cache_read 和 cache_write 移到 cache.read 和 cache.write。 - Provider 特定选项变为 settings。 - V1 的 variants 对象变为带有 id 的 V2 数组。

JSONC // V1 { "variants": { "high": { "reasoningEffort": "high" } } }

// V2 { "variants": [ { "id": "high", "settings": { "reasoningEffort": "high" } } ] } 请参阅“Models”了解完整的原生模型结构。

大多数保留相同结构的字段(包括 shell、model、default_agent、watcher、formatter、instructions、enterprise 和 tool_output)无需迁移。 V2 接受并保留 lsp 配置,但不运行语言服务器、不暴露 LSP 工具或不生成 LSP 诊断。请将依赖这些功能的工作流替换为项目的 lint、typecheck 或编译命令。 V1 的 provider 过滤器没有一对一的原生 V2 配置字段,但其行为仍通过策略支持:

- enabled_providers 变为内部默认拒绝的 provider 策略,随后允许列出的 provider。 - disabled_providers 变为针对列出 provider 的内部拒绝策略。 - autoupdate 变为 update: false 映射到 "disable","notify" 映射到 "notify",true 映射到 "auto"。 - small_model 变为内置 title agent 的模型选择。原生 V2 配置应使用 agents.title.model。

可以保留这些字段在 V1 语法中。OpenCode 会规范化它们而不发出警告。

V1 schema 还接受了没有受支持 V2 行为的字段。V2 忽略这些值并发出警告,以免误认为是活跃配置:

- logLevel:启动 OpenCode 时使用 OPENCODE_LOG_LEVEL。 - server:使用 V2 服务和显式的服务器选项;服务端 API 是有意的破坏性变更。 - 顶级 subagent_depth:改用 experimental.subagent_depth。 - compaction.tail_turns 和 compaction.prune:V2 改用 compaction.keep.tokens 和基于检查点的压缩。 - V1 JSON 配置中的 agent 名称。 - 没有 type 的仅启用 V1 MCP 条目。 - V1 experimental 字段 batch_tool、openTelemetry、primary_tools 和 continue_loop_on_deny。 - V1 provider 字段 id、whitelist 和 blacklist。 - V1 provider-model 字段 release_date、attachment、reasoning、temperature、experimental、非弃用 status 和布尔值 interleaved。

忽略这些字段是有意为之,并非兼容性倒退。如果 V2 未保留本指南其他部分中识别为受支持的行为,请遵循“Troubleshooting”中的问题报告指南。

V1 agent 文件可能使用 agent/、agents/、mode/ 或 modes/。V2 仍会发现这四个目录。推荐的 V2 位置是: .opencode/agents/.md 位于 V1 mode/ 或 modes/ 目录下的文件代表 primary agents。将其移动到 agents/ 时,请在前置元数据中添加 mode: primary。位于 agent/ 下的文件可以移动到 agents/ 而无需更改由路径派生的 ID。 将前置元数据转换为原生 V2 字段时:

- 保留 Markdown 正文作为 agent 的系统指令。 - 在 JSON 配置中出现时将 prompt 重命名为 system;文件正文不需要 system 字段。 - 将 disable 重命名为 disabled,permission 重命名为 permissions。 - 将 model 和 variant 合并为 provider/model#variant。 - 如上文所示,在模型变体上设置采样和 provider 选项。

V1 agent 前置元数据已弃用但仍会自动转换。每个文件被视为一种格式。使用 permissions、request、system 或 disabled 中任意一个的文件被读取为 V2,其中的 V1 字段(如 name、tools、permission 或 temperature)会被忽略并在日志中发出警告。使用 V1 字段的其他文件被读取为 V1。请将文件的前置元数据一次性转换,而非混合两种格式。请参阅“Agents”。

V1 命令文件可能使用 command/ 或 commands/。V2 发现两者。推荐位置是: .opencode/commands/.md 将 command/ 中的文件移动到 commands/ 下的相同相对路径以保留命令名称。Markdown 正文保持为命令模板,description 和 agent 前置元数据保留原名称。将 subtask 重命名为 subagent 以使用后台委托的原生名称。如果前置元数据有单独的 model 和 variant 字段,请将 variant 附加到 model 并移除 variant: YAML # V1 model: anthropic/claude-sonnet-5-5 variant: high subtask: true

# V2 model: anthropic/claude-sonnet-5-5#high subagent: true 请参阅“Commands”。

V2 从 .opencode/skill/ 和 .opencode/skills/ 发现技能。推荐的布局是: .opencode/skills//SKILL.md 移动完整的技能目录,而不仅仅是 SKILL.md,以确保相对脚本、引用和其他支持文件可用。保持目录名称稳定以保留技能 ID。现有的技能前置元数据和 Markdown 正文不需要 V2 重写。请参阅“Skills”。

现有的 AGENTS.md 文件保留在原位。V2 发现全局 ~/.config/opencode/AGENTS.md 以及从当前目录到家目录的环境 AGENTS.md 文件。对于 home 目录外部的项目,发现止于项目根目录。 如果 V1 配置依赖 CLAUDE.md 回退机制,请将该指导移至适用的 AGENTS.md。V2 目前仅发现 AGENTS.md;鉴于非 API 的 V1 行为旨在保持兼容,请同时提交包含受影响项目详情的兼容性问题。请参阅“Instructions”。

V2 用单一的全局终端客户端配置文件替代分层的 V1 tui.json(c) 文件: ~/.config/opencode/cli.json 终端客户端拥有此文件;后台服务不加载它。当 cli.json 不存在时,首次启动 V2 终端客户端会迁移受支持的全局 tui.json 设置和持久化偏好,同时保持 V1 文件不变。不迁移项目本地客户端配置,因为 V2 客户端配置是全局的。请参阅“CLI settings”了解当前客户端设置参考。

将 plugin 重命名为 plugins。用对象替换包和选项元组: JSONC // V1 { "plugin": ["opencode-example-plugin", ["./plugin/local.ts", { "enabled": true }]] }

// V2 { "plugins": [ "opencode-example-plugin", { "package": "./plugin/local", "options": { "enabled": true } } ] } V2 从 .opencode/plugin/ 和 .opencode/plugins/ 发现本地插件;对 V2 文件使用 .opencode/plugins/。配置的本地路径必须是目录,因此请将移植的插件移至 ./plugin/local/index.ts。

使用专门的插件迁移指南移植入口点、钩子、工具、事件和包导出。

OpenCode 2 拥有修订过的、更易用的服务端 API 和一组新的客户端。调用 V1 服务端 API 的集成必须迁移到 V2 API。 使用 @opencode/client 包访问已发布的 V2 API。请参阅生成的 API 参考了解其端点、请求类型和响应。

V2 服务器仍使用 HTTP Basic 认证,包含以下变更:

- OPENCODE_PASSWORD 设置密码。OPENCODE_SERVER_PASSWORD 仍然有效。 - 不再支持 OPENCODE_SERVER_USERNAME。用户名始终为 opencode。

Terminal # V1 OPENCODE_SERVER_USERNAME=alice OPENCODE_SERVER_PASSWORD=secret opencode serve

# V2 OPENCODE_PASSWORD=secret opencode serve 请参阅“Web”。

在依赖 V2 进行常规工作之前,请在项目中验证您的模型、provider 凭据、agent、权限、MCP 服务器和插件。在确认所需的 V2 行为之前,请保留您的 V1 配置,并且不要让 V1 指向已转换为原生 V2 格式的配置。

评论 (0)