docs(www): fix outdated V2 docs (#58280)

This commit is contained in:
DS
2026-10-22 22:02:38 -04:00
committed by GitHub
Unverified
parent 51599c4934
commit 1b0c1302e6
8 changed files with 153 additions and 59 deletions
+12 -8
View File
@@ -57,16 +57,20 @@ HTTP and HTTPS attachment URLs are not supported. See the generated
Current V2 sessions make these attachment types visible to the model:
| Input | Model receives | Example |
| ----------------------- | -------------------------------------------------------------- | ------------------ |
| UTF-8 text file | Filename and decoded text | `README.md` |
| Directory | Non-recursive listing of immediate files and directories | `file:///home/me/` |
| PNG, JPEG, GIF, or WebP | Image media | `diagram.png` |
| Input | Model receives | Example |
| ----------------------- | -------------------------------------------------------- | ------------------ |
| UTF-8 text file | Filename and decoded text | `README.md` |
| Directory | Non-recursive listing of immediate files and directories | `file:///home/me/` |
| PNG, JPEG, GIF, or WebP | Image media | `diagram.png` |
| PDF | Document media | `report.pdf` |
SVG is treated as text. PDF, AVIF, BMP, audio, video, and other binary prompt
PDFs need a model with PDF input. If the model does not support an attachment's
type, OpenCode sends a short note in its place.
SVG is treated as text. AVIF, BMP, audio, video, and other binary prompt
attachments are not included in the model request. Convert an unsupported
binary to text or a supported image first; for example, export a PDF page as
`page-1.png` before attaching it.
binary to text or a supported image first; for example, convert a BMP image to
PNG before attaching it.
OpenCode reads each attachment before admitting the prompt. It rejects invalid
URLs, unreadable paths, paths other than files or directories, and decoded
@@ -62,6 +62,18 @@ Run with a specific agent.
$ opencode run --agent build "Fix the failing test"
```
Continue a specific session.
```bash
$ opencode run --session ses_4f2a1c "Check edge cases"
```
Auto-approve permissions that are not explicitly denied.
```bash
$ opencode run --auto "Fix the failing test"
```
View all subcommands and flags.
```bash
@@ -88,6 +100,12 @@ Start with a model and an initial prompt.
$ opencode mini --model anthropic/claude-sonnet-4-5 --prompt "Summarize this repository"
```
Continue a specific session.
```bash
$ opencode mini --session ses_4f2a1c
```
View all subcommands and flags.
```bash
@@ -182,6 +200,13 @@ Switch the active account for an integration.
$ opencode auth switch anthropic work
```
Export saved credentials and import them on another machine. The file contains secrets.
```bash
$ opencode auth export anthropic > credentials.json
$ opencode auth import credentials.json
```
View all subcommands and flags.
```bash
@@ -328,6 +353,12 @@ Print JSON instead of a report.
$ opencode stats --json
```
Show only the current project.
```bash
$ opencode stats --project .
```
View all subcommands and flags.
```bash
+4 -2
View File
@@ -32,8 +32,10 @@ There is no project-local CLI settings file. Add the published JSON Schema for v
}
```
OpenCode adds `$schema` when it creates or migrates this file. Unknown settings are rejected, and valid edits reload
while the TUI is running.
OpenCode adds `$schema` when it creates or migrates this file. Valid edits reload while the TUI is running.
Unknown settings are ignored, but an invalid value makes OpenCode ignore the whole file and use defaults, so keep
`$schema` for editor validation. Valid `OPENCODE_CLI_CONFIG_CONTENT` overrides still apply.
## Inline config
+49 -34
View File
@@ -76,7 +76,8 @@ Use an object for event behavior:
}
```
Unknown command IDs are rejected.
Unknown command IDs are ignored. An invalid binding makes OpenCode ignore the whole file; see
[CLI settings](/cli/config).
## Application
@@ -97,6 +98,7 @@ Unknown command IDs are rejected.
| `opencode.settings` | `none` | Open settings |
| `server.pair` | `none` | Pair device |
| `service.restart` | `none` | Restart service |
| `location.reload` | `none` | Reload configuration |
## Mini
@@ -128,44 +130,49 @@ Right-click a file in the sidebar or its diff heading for **Mark complete** (or
The shifted `diff.help` alternatives support terminals that report the Shift modifier when you press `?`.
| ID | Default | Description |
| ----------------------- | ------------------- | ---------------------------------------- |
| `diff.open` | `none` | Open diff viewer |
| `diff.close` | `escape,q` | Close diff viewer |
| `diff.down` | `j,down` | Move diff viewer down |
| `diff.up` | `k,up` | Move diff viewer up |
| `diff.page.down` | `pagedown,ctrl+f` | Page diff viewer down |
| `diff.page.up` | `pageup,ctrl+b` | Page diff viewer up |
| `diff.half_page.down` | `ctrl+d` | Scroll diff viewer down half a page |
| `diff.half_page.up` | `ctrl+u` | Scroll diff viewer up half a page |
| `diff.first` | `gg,home` | Go to the start of the diff |
| `diff.last` | `shift+g,end` | Go to the end of the diff |
| `diff.next_hunk` | `]` | Jump to next diff hunk |
| `diff.previous_hunk` | `[` | Jump to previous diff hunk |
| `diff.next_file` | `n,alt+down` | Jump to next diff file |
| `diff.previous_file` | `p,alt+up` | Jump to previous diff file |
| `diff.toggle_file_tree` | `b` | Toggle diff viewer file tree |
| `diff.single_patch` | `s` | Toggle single patch view |
| `diff.switch_source` | `d` | Choose the diff review scope |
| `diff.toggle_view` | `v` | Toggle diff viewer split or unified view |
| `diff.mark_reviewed` | `m` | Toggle selected diff file reviewed |
| `diff.help` | `?,shift+?,shift+/` | Show more diff viewer shortcuts |
| ID | Default | Description |
| ------------------------ | ------------------- | ---------------------------------------- |
| `diff.open` | `none` | Open diff viewer |
| `diff.close` | `escape,q` | Close diff viewer |
| `diff.down` | `j,down` | Move diff viewer down |
| `diff.up` | `k,up` | Move diff viewer up |
| `diff.page.down` | `pagedown,ctrl+f` | Page diff viewer down |
| `diff.page.up` | `pageup,ctrl+b` | Page diff viewer up |
| `diff.half_page.down` | `ctrl+d` | Scroll diff viewer down half a page |
| `diff.half_page.up` | `ctrl+u` | Scroll diff viewer up half a page |
| `diff.first` | `gg,home` | Go to the start of the diff |
| `diff.last` | `shift+g,end` | Go to the end of the diff |
| `diff.next_hunk` | `]` | Jump to next diff hunk |
| `diff.previous_hunk` | `[` | Jump to previous diff hunk |
| `diff.next_file` | `n,alt+down` | Jump to next diff file |
| `diff.previous_file` | `p,alt+up` | Jump to previous diff file |
| `diff.toggle_file_tree` | `b` | Toggle diff viewer file tree |
| `diff.single_patch` | `s` | Toggle single patch view |
| `diff.switch_source` | `d` | Choose the diff review scope |
| `diff.toggle_view` | `v` | Toggle diff viewer split or unified view |
| `diff.toggle_fullscreen` | `f` | Toggle diff viewer full screen |
| `diff.mark_reviewed` | `m` | Toggle selected diff file reviewed |
| `diff.help` | `?,shift+?,shift+/` | Show more diff viewer shortcuts |
The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, and `diff.switch_focus` configuration entries are still accepted, but no longer register shortcuts.
## Appearance And Navigation
| ID | Default | Description |
| -------------------------- | ----------- | ---------------------------------------- |
| `prompt.editor` | `<leader>e` | Open external editor |
| `theme.switch` | `none` | List available themes |
| `theme.switch_mode` | `none` | Switch between light and dark theme mode |
| `theme.mode.lock` | `none` | Lock or unlock theme mode |
| `session.sidebar.toggle` | `<leader>b` | Toggle sidebar |
| `terminal.toggle` | `<leader>t` | Toggle terminal pane |
| `session.toggle.scrollbar` | `none` | Toggle session scrollbar |
| `opencode.status` | `<leader>s` | View status |
| `opencode.debug` | `none` | View debug info |
| ID | Default | Description |
| -------------------------- | --------------- | ---------------------------------------- |
| `prompt.editor` | `<leader>e` | Open external editor |
| `theme.switch` | `none` | List available themes |
| `theme.switch_mode` | `none` | Switch between light and dark theme mode |
| `theme.mode.lock` | `none` | Lock or unlock theme mode |
| `session.sidebar.toggle` | `<leader>b` | Toggle sidebar |
| `pane.focus.left` | `<leader>left` | Focus session pane |
| `pane.focus.right` | `<leader>right` | Focus right pane |
| `terminal.select` | `<leader>down` | Select terminal |
| `terminal.toggle` | `<leader>t` | Toggle terminal pane |
| `terminal.close` | `<leader>up` | Close terminal pane |
| `session.toggle.scrollbar` | `none` | Toggle session scrollbar |
| `opencode.status` | `<leader>s` | View status |
| `opencode.debug` | `none` | View debug info |
## Sessions
@@ -173,6 +180,7 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an
| ------------------------------------- | ----------------------- | ---------------------------------------- |
| `session.export` | `<leader>x` | Export session to editor |
| `session.copy` | `none` | Copy session transcript |
| `session.copy.id` | `none` | Copy session ID |
| `session.move` | `none` | Move session |
| `session.new` | `<leader>n` | Create a new session |
| `session.list` | `<leader>l` | List all sessions |
@@ -198,6 +206,7 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an
| `queued_prompt.undo` | `ctrl+u` | Undo queued prompt |
| `queued_prompt.delete` | `ctrl+d` | Delete queued prompt |
| `session.toggle.exploration_grouping` | `none` | Toggle related tool call grouping |
| `session.verbosity.cycle` | `none` | Cycle transcript verbosity |
| `session.child.first` | `down` | Toggle subagent picker |
| `session.child.next` | `right` | Go to next child session |
| `session.child.previous` | `left` | Go to previous child session |
@@ -335,6 +344,9 @@ The retired `diff.toggle`, `diff.expand`, `diff.expand_all`, `diff.collapse`, an
| `composer.shell.down` | `down` | Next shell |
| `composer.shell.select` | `return` | View shell output |
| `composer.shell.kill` | `ctrl+d` | Kill shell command |
| `composer.terminal.up` | `up,k` | Previous terminal |
| `composer.terminal.down` | `down,j` | Next terminal |
| `composer.terminal.select` | `return` | Select terminal |
Select a running command in the **Shell** tab and press **Enter**, or click it, to view captured stdout and stderr.
Use **↑/↓**, **Page Up/Down**, or **Home** to scroll, **End** to follow new output, and **Esc** to return without stopping the command.
@@ -352,6 +364,8 @@ The viewer shows recent output and stays open after exit; output redirected to a
| `dialog.select.end` | `end` | Move to last dialog item |
| `dialog.select.submit` | `return` | Submit selected dialog item |
| `dialog.prompt.submit` | `return` | Submit dialog prompt |
| `dialog.integration.rename` | `ctrl+r` | Rename integration account |
| `dialog.integration.delete` | `ctrl+d` | Delete integration account |
| `dialog.worktree.generate` | `tab` | Generate worktree name |
| `dialog.move_session.new` | `ctrl+a` | New worktree |
| `dialog.move_session.move` | `ctrl+m` | Move session to worktree |
@@ -365,6 +379,7 @@ The viewer shows recent output and stays open after exit; output redirected to a
| `permission.prompt.fullscreen` | `ctrl+f` | Toggle permission prompt fullscreen |
| `plugins.toggle` | `return` | Toggle plugin |
| `dialog.mcp.toggle` | `space` | Toggle MCP server |
| `dialog.plugins.error` | `space` | View plugin error |
| `dialog.plugins.update` | `ctrl+u` | Update plugin from plugin dialog |
| `dialog.plugins.check` | `ctrl+r` | Check for plugin updates |
+18 -3
View File
@@ -88,10 +88,25 @@ Add `compaction` to any [OpenCode configuration file](/config):
`keep.tokens` and `buffer` accept non-negative integers.
## Model
By default OpenCode writes the summary itself, using the session's model. Set
`agents.compaction.model` to use another model for summaries:
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"agents": {
"compaction": { "model": "anthropic/claude-sonnet-5-5" },
},
}
```
If that model cannot be resolved, OpenCode falls back to the session's model.
## Providers
By default OpenCode writes the summary itself, using the session's model. Some
providers can compact the conversation on their side instead. Enable it per
Some providers can compact the conversation on their side instead. Enable it per
provider or model with `settings.compaction`:
```jsonc title="opencode.jsonc"
@@ -153,7 +168,7 @@ session's baseline; see [Instructions](/instructions).
| Limit | Result |
| --- | --- |
| Model | Compaction uses the session's model. There is no separate compaction model. |
| Model | Summary compaction honors `agents.compaction.model`; otherwise it uses the session's model. Native compaction always uses the session's model. |
| History | Compaction needs older conversation to replace. It cannot create room when a request is mostly fixed instructions and tool schemas. |
| Size | If the conversation to compact is itself too long, OpenCode sends a shortened text version and may leave out the oldest exchanges. |
| Recovery | A request rejected as too long is compacted and retried once. A second rejection is returned as an error. |
+27 -4
View File
@@ -176,8 +176,30 @@ V2 config:
```
`prompt` becomes `system`, `disable` becomes `disabled`, and a separate `variant` joins the model reference after `#`.
`temperature`, `top_p`, and provider-specific `options` move under `request.body`. `maxSteps` becomes `steps`. Entries from
the old `mode` map become primary agents.
`maxSteps` becomes `steps`. Entries from the old `mode` map become primary agents.
Agent [`request.body`](/agents#request) is kept but not sent to the model, so V1 `temperature`, `top_p`, and `options`
have no effect there. Set them on a model variant instead. DeepSeek only applies `temperature` with thinking off, so
this variant turns thinking off too:
```jsonc title="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" },
},
}
```
Use `body` for provider JSON fields and `settings` for provider package options. See [model options](/models#options).
### Snapshots
@@ -477,7 +499,7 @@ When converting the frontmatter to native V2 fields:
- Rename `prompt` to `system` when it appears in JSON configuration; file bodies do not need a `system` field.
- Rename `disable` to `disabled` and `permission` to `permissions`.
- Join `model` and `variant` as `provider/model#variant`.
- Move `temperature`, `top_p`, and provider-specific options under `request.body`.
- Set sampling and provider options on a model variant, as shown [above](#agents-and-modes).
V1 agent frontmatter is deprecated but still translated automatically. Each file is read as one format. A file that
uses any of `permissions`, `request`, `system`, or `disabled` is read as V2, and V1 fields in it, such as `name`,
@@ -559,7 +581,7 @@ Rename `plugin` to `plugins`. Replace a package-and-options tuple with an object
"plugins": [
"opencode-example-plugin",
{
"package": "./plugin/local.ts",
"package": "./plugin/local",
"options": { "enabled": true }
}
]
@@ -567,6 +589,7 @@ Rename `plugin` to `plugins`. Replace a package-and-options tuple with an object
```
V2 discovers local plugins from both `.opencode/plugin/` and `.opencode/plugins/`; use `.opencode/plugins/` for V2 files.
Configured local paths must be directories, so move the ported plugin to `./plugin/local/index.ts`.
<Callout type="warning">
V1 plugin implementations do not run in V2. Moving a file or renaming its config entry is not enough.
+10 -6
View File
@@ -14,8 +14,8 @@ Add published packages, versioned packages, scoped packages, or local plugin dir
"opencode-acme-plugin@1.2.0",
"@acme/opencode-plugin",
"./plugins/local",
"../shared/plugin.ts",
"/absolute/path/plugin.ts",
"../shared/plugin",
"/absolute/path/plugin",
"file:///home/me/plugins/local",
{
"package": "@acme/opencode-plugin",
@@ -28,8 +28,12 @@ Add published packages, versioned packages, scoped packages, or local plugin dir
}
```
Relative paths resolve from the config file containing the entry. Plugin arrays from applicable config files are applied
from lowest to highest precedence instead of replacing one another.
Relative paths resolve from the config file containing the entry.
Configured local paths must be directories. OpenCode loads the directory's `server` or `index` module, such as
`index.ts`. A path to a single file is skipped.
Plugin arrays from applicable config files are applied from lowest to highest precedence instead of replacing one another.
```text
~/.config/opencode/opencode.jsonc
@@ -56,8 +60,8 @@ Global plugins use the same discovery layout under the OpenCode config directory
~/.config/opencode/plugins/
```
A `plugins/` directory beside a project-root `opencode.json(c)` is not discovered automatically; configure its files
explicitly or move it under `.opencode/`.
A `plugins/` directory beside a project-root `opencode.json(c)` is not discovered automatically; configure its plugin
directories explicitly or move it under `.opencode/`.
```jsonc title="opencode.jsonc"
{
+2 -2
View File
@@ -134,7 +134,7 @@ Both fields can also be set on a model or variant when only part of a provider's
## Timeouts
HTTP requests wait up to five minutes for response headers and up to five minutes between streamed response chunks.
HTTP requests wait up to five minutes for response headers and up to fifteen minutes between streamed response chunks.
Set the provider's `settings.headerTimeout` or `settings.chunkTimeout` to a number of milliseconds to change a limit,
or to `false` to disable it. `settings.timeout` additionally bounds the whole request from send until the response
completes; it has no default. These configuration settings apply provider-wide, not per model or variant. On a
@@ -556,7 +556,7 @@ OpenRouter account, then refer to models with the full OpenRouter model ID after
```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
"model": "openrouter/anthropic/claude-sonnet-4",
"model": "openrouter/anthropic/claude-sonnet-5.5",
}
```