Status: Planned for dev.
OpenCode V1 and OpenCode V2 read configuration from the same global and project paths. OpenCode V2 commands continue to
write native V2 fields. A user can therefore start with a valid V1 file, run a V2 command such as opencode2 mcp add, and
produce a mixed document that V2 accepts but V1 cannot load.
The V1 decoder already ignores unknown object properties. Most V2-only top-level fields therefore do not cause a failure; they are simply unavailable to V1. Failures occur when both versions recognize the same key but assign it incompatible shapes. The important examples are:
- V1 treats
mcpas a flat server map, while V2 uses an object containingserversandtimeout. - V1 accepts a string
model, while V2 also accepts an explicit model-selection object. - V1 accepts a
{ paths, urls }skillsobject, while V2 accepts a string array.
V1 currently validates each parsed document as one ConfigV1.Info value. One incompatible recognized field rejects the
whole document, including unrelated valid V1 settings.
The V1 runtime on dev should load V1, V2, and mixed V1/V2 configuration without rewriting the source document.
V1 should:
- Preserve existing V1 behavior for valid V1 fields.
- Lower recognizable V2 fields when V1 can provide equivalent or useful behavior.
- Ignore unsupported V2 fields instead of rejecting the complete document.
- Continue rejecting malformed values that match neither valid V1 nor recognizable V2 syntax.
- Apply the same behavior to every configuration source and preserve existing source precedence.
Compatibility is best effort, not an exact V2-to-V1 round trip. V1 cannot implement V2-only runtime features.
- V2 commands will not write V1 syntax.
- The compatibility path will not edit, migrate, or reformat configuration files.
- V1 will not emulate V2-only runtime features.
- The complete current V2 schema will not be copied into
dev. - The older V2 schema already present in
packages/coreondevwill not define this compatibility contract. It is not synchronized with the current V2 format.
The V1 loader has pre-existing behavior that may create a global config or insert $schema when it is absent. That behavior
is independent of this compatibility work.
This is a read-time adapter for the legacy application, so its implementation belongs under:
packages/opencode/src/config/v2-compat.ts
It should not be added to the newer Core config loader. The adapter is invoked only by the V1 application.
The integration point is loadConfig in packages/opencode/src/config/config.ts, after variable substitution and JSONC
parsing but before ConfigV1.Info decoding:
const parsed = ConfigParse.jsonc(expanded, source)
const lowered = ConfigV2Compat.lower(parsed)
const data = ConfigParse.schema(ConfigV1.Info, lowered.value, source)This placement applies compatibility independently to each source before sources are merged. It covers global, project, explicit, environment-content, remote, account, and managed configuration while retaining the existing precedence model.
The destination remains the existing ConfigV1.Info schema. It is the final authority on values consumed by V1.
The adapter defines only permissive input schemas for current V2 shapes that can be lowered. These schemas are not a second complete V2 config schema. They are narrow decoders such as:
ModelSelectionV2
PermissionRuleV2
AgentV2
CommandV2
PluginV2
McpConfigV2
McpServerV2
ProviderV2
ProviderModelV2
Each input field is decoded independently. Unknown members are ignored. A malformed or unsupported member does not prevent other supported members of the same document from loading.
The adapter must not decode the entire document through the older Config.Info on dev. That schema predates the current
V2 format and would reject or misinterpret newer valid values.
Within one document, a successfully lowered V2 value takes precedence over the V1 form of the same canonical setting. This matches the current V2 mixed-config policy and treats explicitly written native V2 syntax as the newer intent.
If the V2 value is malformed or cannot be lowered at all, a valid V1 value remains in effect. Unsupported leaves inside an otherwise usable V2 entry are omitted without discarding the complete entry.
Configuration source precedence remains unchanged because lowering happens before the existing source merge.
These fields already have compatible encoded shapes. They remain in place and are validated by ConfigV1.Info:
| V2 field | V1 behavior |
|---|---|
$schema |
Preserved. |
shell |
Preserved. |
default_agent |
Preserved. |
autoupdate |
Preserved when the value is accepted by V1. |
share |
Preserved. |
enterprise |
Preserved for fields understood by V1. |
username |
Preserved. |
watcher |
Preserved for the shared shape. |
formatter |
Preserved for entries accepted by V1. |
lsp |
Preserved when the entry satisfies V1 requirements. |
tool_output |
Preserved. |
instructions |
Preserved. |
references |
Preserved. |
These V2 fields have a V1 representation for their supported current shape:
| V2 field | V1 output | Notes |
|---|---|---|
snapshots |
snapshot |
Boolean value is unchanged. |
media |
attachment |
Image settings are retained. |
commands |
command |
template, description, agent, subtask, and representable model selection are retained. |
plugins |
plugin |
Strings remain strings; { package, options } becomes [package, options]. |
| Basic local MCP server | Flat mcp[name] |
command, cwd, and environment are retained. |
| Basic remote MCP server | Flat mcp[name] |
url, headers, and representable OAuth settings are retained. |
MCP disabled |
MCP enabled |
The boolean is inverted. |
| OAuth snake-case keys | OAuth camel-case keys | client_id, client_secret, callback_port, and redirect_uri are renamed. |
compaction.keep.tokens |
compaction.preserve_recent_tokens |
Numeric value is retained. |
compaction.buffer |
compaction.reserved |
Numeric value is retained. |
compaction.auto |
compaction.auto |
Boolean value is unchanged. |
These fields are lowered entry by entry. Unsupported leaves are omitted while useful V1 behavior is retained:
| V2 field | V1 output | Limitation |
|---|---|---|
Top-level model object |
model: "provider/model" |
A top-level variant has no V1 representation and is ignored. String selections already remain compatible. |
skills array |
skills.paths and skills.urls |
HTTP(S) URLs are classified as URLs; other values are paths. V2 ordering between paths and URLs cannot be preserved. |
agents |
agent |
Basic identity, prompt, model, permissions, color, mode, visibility, and step settings are lowered. |
Agent system |
Agent prompt |
Content is retained. |
Agent disabled |
Agent disable |
Boolean value is retained. |
Agent request.body |
Agent options |
Body values are retained, but their original V1 spelling cannot be recovered. |
| Agent model selection | Agent model and variant |
Representable without loss. |
permissions |
permission |
Rules are grouped by action and resource. Exact ordering is not always representable. |
Permission shell |
Permission bash |
Action is renamed. |
Permission subagent |
Permission task |
Action is renamed. |
| MCP server timeout | Scalar server timeout |
Emitted only when catalog and execution agree and no incompatible startup value is required. |
| Global MCP timeout | experimental.mcp_timeout |
Emitted only when one scalar safely represents the configured phases. |
providers |
provider |
Basic provider and model metadata, options, headers, limits, modalities, and known package mappings are lowered. |
| Provider model selection/package | V1 provider/model fields | Only package identities usable by V1 are retained. |
| Provider model variants | V1 variant map | Only unique, settings-only variants are representable. |
experimental.policies |
enabled_providers or disabled_providers |
Only the canonical provider allowlist/denylist patterns are lowered. |
For repeated V2 permission rules targeting the same action and resource, the final matching rule wins. The adapter must not claim to preserve arbitrary ordered-rule semantics after grouping rules into the V1 object format.
These current settings have no reliable V1 equivalent. Their presence must not reject the document:
| V2 field | Reason |
|---|---|
websearch |
V1 has no equivalent provider-selection configuration. |
warming |
V1 has no equivalent warming policy. |
experimental.portable_shell_scanner |
V1 has no corresponding behavior. |
MCP codemode |
V1 cannot expose MCP tools through V2 Code Mode. |
| Independent MCP timeout phases | V1 supports only one scalar timeout. |
Agent request.headers |
V1 agents have no equivalent request-header field. |
| Arbitrary ordered provider policies | V1 only supports provider allow and deny lists. |
| Current-only plugin directives or built-in IDs | V1 may misinterpret them as package specifications. |
| Provider/model transport compatibility flags | V1 cannot reproduce current transport behavior. |
| Provider/model request body overlays without a safe V1 mapping | Treating them as ordinary options could change semantics. |
| Multiple provider cost tiers | V1 cannot represent the general current tier model. |
| Model response-WebSocket capability | V1 has no equivalent capability. |
| Model compatibility fields without V1 equivalents | Includes current-only token and finish-reason behavior. |
Unknown V2 top-level fields continue to be ignored by the existing excess-property decoding policy.
The adapter distinguishes recognizable V2 syntax from malformed V1 syntax:
- A valid V2-shaped collision is lowered or ignored instead of reaching the incompatible V1 field decoder.
- A valid V1-shaped value continues through unchanged.
- A value matching neither shape continues to fail V1 validation.
- A malformed entry inside a V2-only plural map is skipped without rejecting valid sibling entries.
- Discarded or lossy values produce path-based diagnostics in logs without changing the source file.
This policy prevents V2 additions from making V1 unusable without turning all V1 configuration mistakes into silent failures.
- Add integration fixtures on
devthat reproduce V1 failures for current V2mcp, objectmodel, and arrayskills. - Add the adapter and field-level schemas under
packages/opencode/src/config/v2-compat.ts. - Invoke it from
loadConfigbeforeConfigV1.Infodecoding. - Implement collision handling first so recognizable V2 shapes cannot reject complete documents.
- Add direct renames and fully lowerable fields.
- Add agents, commands, plugins, permissions, and skills with explicit lossy behavior.
- Add conservative provider/model lowering separately because it has the largest compatibility surface.
- Add path-based diagnostics for ignored and lossy values.
- Add mixed V1/V2 conflict tests and preserve native V2 precedence.
- Verify the
devV1 binary against isolated current-V2 fixtures, including a file modified byopencode2 mcp add.
Tests should establish these invariants:
- Every lowered result decodes successfully as
ConfigV1.Info. - Valid V1 configuration has unchanged decoded behavior.
- Recognizable V2-only fields never reject an otherwise usable document.
- Malformed V1 values still fail.
- Mixed flat V1 and enveloped V2 MCP servers both load.
- V2 wins only when its value was successfully lowered.
- Unsupported leaves do not discard supported sibling settings.
- Lowering is pure and does not mutate the parsed input or source file.
- Per-source lowering preserves existing global/project/managed precedence.