OpenCode Config Reference (opencode.json)

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with Anomaly. Tables are generated from the OpenCode source at v1.18.33 (v1.18.33). Official documentation: opencode.ai.

OpenCode reads opencode.json or opencode.jsonc from ~/.config/opencode, from every directory between the project root and the working directory, and from .opencode/ folders, then deep-merges them with the nearest file winning. Both names are parsed as JSONC. The schema is published at https://opencode.ai/config.json, and unknown keys are silently ignored.

Where is opencode.json located?#

Sources merge from lowest to highest precedence, so a later row overrides an earlier one:

The global directory is $XDG_CONFIG_HOME/opencode, ~/.config/opencode by default. Project files are looked up from the working directory up to the worktree root and applied from the root down. Within one directory opencode.jsonc loads after opencode.json, so it wins when both exist. The same config directories also supply Markdown agents from agent/ or agents/, Markdown commands from command/ or commands/, and plugin files from plugin/ or plugins/.

Merging is a deep merge: nested objects combine key by key and arrays are replaced, except instructions, which concatenates and removes duplicates, and plugin, which collects entries from every file and keeps one copy per package.

Which environment variables change config loading?#

Two substitutions run on the raw text of every config file before parsing: {env:NAME} inserts an environment variable (empty when unset) and {file:path} inserts a file's contents.

opencode.json vs opencode.jsonc#

Both are parsed by the same JSONC parser, which accepts comments and trailing commas, so the extension changes nothing about syntax. The difference is precedence within a directory (.jsonc wins) and how OpenCode writes settings changed from the app: global changes go to the first of opencode.jsonc, opencode.json, config.json that exists, and a .jsonc file is edited in place so its comments survive.

What are all the opencode.json keys?#

theme, keybinds and tui are not opencode.json keys in this release: OpenCode drops them when it loads the file and migrates them to a tui.json beside it.

How do I configure agents?#

Each entry under agent is keyed by agent name. A name matching a built-in agent overrides it; any other name creates an agent. Keys OpenCode does not recognise inside an agent are moved into its options.

How do I add a provider or a custom model?#

Each entry under provider is keyed by provider id. options accepts any extra keys beyond the ones listed; models is keyed by model id and accepts the model fields (name, limit, cost, modalities, options, headers, variants and others).

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "qwen3-coder": { "name": "Qwen3 Coder" } }
    }
  },
  "model": "local/qwen3-coder"
}

How do I configure MCP servers?#

Each entry under mcp is keyed by server name and is either a local server started as a subprocess or a remote server reached over HTTP. { "enabled": false } on its own disables a server defined in another config file.

Can OpenCode 1.x read an OpenCode 2 config?#

Partly. 1.x lowers several OpenCode 2 keys to their 1.x names, ignores keys with no 1.x meaning, and refuses a v2 permissions array outright.

Frequently asked questions#

Where is the OpenCode config file?#

The global file is ~/.config/opencode/opencode.json (or opencode.jsonc, or the older config.json). A project file is opencode.json or opencode.jsonc in the repository, at any level from the root to the working directory, or inside a .opencode/ folder. OPENCODE_CONFIG adds one more file and OPENCODE_CONFIG_DIR one more directory.

Should I use opencode.json or opencode.jsonc?#

Either. OpenCode parses both as JSONC, so comments and trailing commas work in both. If a directory has both, opencode.jsonc is merged last and wins on conflicting keys. Editing settings from the app preserves comments only in a .jsonc file, because a .json file is rewritten as plain JSON.

What is the OpenCode config merge order?#

From lowest to highest: remote well-known config from opencode auth login, the global config, OPENCODE_CONFIG, project files from the repository root down to the working directory, .opencode/ folders, OPENCODE_CONFIG_CONTENT, Console organization config, the system managed directory, and finally macOS MDM managed preferences, which override everything.

Where is the OpenCode config schema?#

At https://opencode.ai/config.json. OpenCode writes "$schema": "https://opencode.ai/config.json" into any config file it loads that lacks one, and creates the global file with only that line on first run, so editors that read $schema get completion and validation without setup. Keybinds and themes are validated against a separate schema, https://opencode.ai/tui.json, in tui.json.

Why does OpenCode ignore a key in opencode.json?#

Unknown keys are dropped silently when the file is decoded, so a typo produces no error. theme, keybinds and tui moved to tui.json. OpenCode 2 names such as plugins, providers, websearch and warming are ignored with a warning in the log, while permissions makes the whole file fail to load.

How do I configure MCP servers in opencode.json?#

Add an entry under mcp: { "type": "local", "command": ["npx", "-y", "my-server"] } for a subprocess, or { "type": "remote", "url": "https://..." } for HTTP. The default request timeout is 5000 ms, enabled: false keeps a server defined but stopped, and remote servers detect OAuth automatically unless oauth is false.

Release-by-release changes: OpenCode version tracker. All OpenCode pages: OpenCode reference index.