opencode-map
中文
← guides/

Configuring opencode: opencode.json in depth

IntermediateLast updated: Oct 21, 2026

opencode is configured by opencode.json or opencode.jsonc (JSON with comments). Add $schema and your editor gets validation and autocomplete:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": { "port": 4096 }
}

Locations and precedence

Configs are merged, not replaced. Later sources win only on conflicting keys. Load order (later overrides earlier):

  1. Remote config — .well-known/opencode on a domain, for org defaults
  2. Global config — ~/.config/opencode/opencode.json
  3. Custom path — OPENCODE_CONFIG env var
  4. Project config — opencode.json in the project root
  5. .opencode directories — agents/, commands/, modes/, plugins/, skills/, themes/, tools/ (plural names; singular also works)
  6. Custom directory — OPENCODE_CONFIG_DIR env var: a whole extra config directory, loaded after global + .opencode dirs
  7. Inline config — OPENCODE_CONFIG_CONTENT env var
  8. Managed config — admin-controlled files
  9. macOS managed preferences — MDM, highest priority

So: global defaults → project overrides → managed policies on top.

The keys that matter

  • model / small_model — default model and the cheap model for small tasks, in provider/model form.
  • provider — provider-specific options (API keys can also come from env vars; see the providers doc).
  • agent — define or override agents; default_agent picks the primary one.
  • mcp — MCP server definitions (local command-based or remote URL-based).
  • plugin — npm plugin packages loaded at startup (see the plugin guide).
  • permission — granular tool permissions (edit, shell, webfetch, etc. — the shell tool was renamed from bash; see the permissions guide).
  • formatter — code formatters per language.
  • lsp — LSP server overrides.
  • tools — enable/disable individual built-in tools.
  • command — define or override slash commands inline (see the commands guide).
  • snapshot — file snapshot/revert tracking.
  • autoupdate — self-update on launch.
  • theme, keybinds, tui — deprecated inside opencode.json; migrated automatically (see below).
  • disabled_providers / enabled_providers — restrict the provider list.
  • instructions — extra instruction files beyond AGENTS.md.

TUI config is a separate file

Interface settings live in tui.json / tui.jsonc — scroll speed, diff style, cursor style, mouse, and desktop attention notifications:

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "cursor": { "style": "block", "blinking": true },
  "attention": { "enabled": true, "notifications": true, "sound": true }
}

Point OPENCODE_TUI_CONFIG at a custom path to override. Legacy theme/keybinds/tui keys in opencode.json are auto-migrated where possible.

Team tips

  • Commit project opencode.json for shared defaults; keep personal overrides in the global file.
  • A domain can publish org defaults at /.well-known/opencode — merged under global config.
  • Environment variables can carry secrets so keys stay out of committed files.

Further reading