mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 08:39:02 +03:00
docs(www): fix outdated V2 docs (#58280)
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
{
|
||||
|
||||
@@ -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",
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user