mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-19 09:33:30 +00:00
89 lines
3.2 KiB
Text
89 lines
3.2 KiB
Text
---
|
|
title: "Overview"
|
|
description: "Move from OpenCode V1 to the OpenCode 2.0 beta."
|
|
---
|
|
|
|
<Warning>
|
|
OpenCode 2.0 is in beta. Back up important configuration and data before migrating. Beta data may be wiped, features may
|
|
break, and configuration and plugin APIs may change.
|
|
</Warning>
|
|
|
|
During the beta, OpenCode V1 and V2 use different executable names. You can keep using `opencode` for V1 while trying V2
|
|
with `opencode2`.
|
|
|
|
## Install the beta
|
|
|
|
Install the beta from the `next` distribution tag:
|
|
|
|
```bash
|
|
npm install -g @opencode-ai/cli@next
|
|
```
|
|
|
|
Start it in your project with:
|
|
|
|
```bash
|
|
opencode2
|
|
```
|
|
|
|
## Back up your configuration
|
|
|
|
Before making changes, back up your global and project configuration files:
|
|
|
|
```text
|
|
~/.config/opencode/opencode.json(c)
|
|
<project>/opencode.json(c)
|
|
<project>/.opencode/opencode.json(c)
|
|
```
|
|
|
|
V2 reads these same locations. It detects V1-shaped configuration and translates supported fields in memory without
|
|
rewriting the source file. Keep shared files in their V1 shape while evaluating both versions; V1 does not understand the
|
|
native plural V2 fields and may silently ignore them.
|
|
|
|
## Update configuration
|
|
|
|
Automatic translation is a compatibility aid, not a guarantee that every V1 setting behaves identically. Convert your
|
|
configuration to the native V2 shape only when you no longer need V1 to read those same files.
|
|
|
|
<Note>
|
|
Do not mix V1 and V2 field names in one file. Back up the V1 file, update the complete working file to the V2 shape, and
|
|
validate it against the current schema. Restore the V1 copy before using V1 again.
|
|
</Note>
|
|
|
|
The main field changes are:
|
|
|
|
| V1 | V2 |
|
|
| --- | --- |
|
|
| `permission` | `permissions` |
|
|
| `agent` and `mode` | `agents` |
|
|
| `snapshot` | `snapshots` |
|
|
| `attachment` | `attachments` |
|
|
| `command` | `commands` |
|
|
| `reference` | `references` |
|
|
| `plugin` | `plugins` |
|
|
| `provider` | `providers` |
|
|
| Servers directly under `mcp` | Servers under `mcp.servers` |
|
|
| `skills.paths` and `skills.urls` | A single `skills` array |
|
|
|
|
Permission actions also changed: `bash` is now `shell`, `task` is now `subagent`, and `write` and `patch` are now `edit`.
|
|
See [Permissions](/permissions) for the ordered V2 rule format.
|
|
|
|
V1-only fields including `logLevel`, `server`, `layout`, `disabled_providers`, `enabled_providers`, and `small_model` are
|
|
not carried into the native V2 configuration. Remove them and use the current [Config](/config) and
|
|
[Providers](/providers) guides to configure their replacements where applicable.
|
|
|
|
## Review extensions
|
|
|
|
V2 continues to discover file-based agents, commands, and skills from OpenCode configuration directories. Their schemas
|
|
have changed, so review each extension against the current [Agents](/agents), [Commands](/commands), and
|
|
[Skills](/skills) guides.
|
|
|
|
<Warning>
|
|
V1 plugins are not guaranteed to work with V2. The plugin API is changing during beta; review and port each plugin using
|
|
the [V2 plugin guide](/plugins).
|
|
</Warning>
|
|
|
|
## Verify your setup
|
|
|
|
Start `opencode2` in a project and verify your model, provider credentials, agents, permissions, MCP servers, and plugins
|
|
before relying on the beta for regular work. Keep your V1 setup and backups until you have confirmed the V2 behavior you
|
|
need, and do not point V1 at configuration that you have converted to the native V2 shape.
|