Opencode Config

OpenCode Configuration

> 📚 Official Docs: For the latest information, always refer to the official documentation: > https://opencode.ai/docs/config/

OpenCode uses JSON-based configuration files to control runtime behavior, TUI appearance, server settings, tool permissions, agent definitions, and provider connections. This skill covers every aspect of configuration: file format, locations, precedence, merging, all available fields, TUI config, variable substitution, enterprise managed settings, environment variables, and troubleshooting.

---

Table of Contents

• [Format](#format)
• [Config Locations & Precedence](#config-locations--precedence)
• [Config Merging Behavior](#config-merging-behavior)
• [All Config Fields](#all-config-fields)
• [TUI Config (tui.json)](#tui-config-tuijson)
• [Variable Substitution](#variable-substitution)
• [Managed Settings (Enterprise)](#managed-settings-enterprise)
• [Provider-Specific Options](#provider-specific-options)
• [Environment Variables](#environment-variables)
• [Debugging & Verification](#debugging--verification)
• [Troubleshooting](#troubleshooting)

---

Format

OpenCode supports both JSON and JSONC (JSON with Comments) formats for all configuration files.

Schema

Every config file should include a $schema field for editor validation and autocomplete:

• Server/runtime config: "$schema": "https://opencode.ai/config.json"
• TUI config: "$schema": "https://opencode.ai/tui.json"

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

Schemas enable autocompletion in VS Code, JetBrains editors, and other JSON-aware editors. Omitting the schema is valid but not recommended.

---

Config Locations & Precedence

Configuration files are merged together, not replaced. Settings from multiple locations are combined. Later sources override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.

Precedence Order (lowest to highest)

Config sources are loaded in this order (later sources override earlier ones):

| Priority | Source | Description | |----------|--------|-------------| | 1 (lowest) | Remote config | Organizational defaults from .well-known/opencode | | 2 | Global config | User preferences at ~/.config/opencode/opencode.json | | 3 | Custom config | Custom overrides via OPENCODE_CONFIG env var | | 4 | Project config | Project-specific settings at opencode.json in project root | | 5 | .opencode directories | Agents, commands, modes, plugins, skills, tools, themes | | 6 | Inline config | Runtime overrides via OPENCODE_CONFIG_CONTENT env var | | 7 | Managed config files | Admin-controlled files in platform-specific directories | | 8 (highest) | macOS managed preferences | .mobileconfig via MDM — not user-overridable |

For example, if your global config sets autoupdate: true and your project config sets model: "anthropic/claude-sonnet-4-5", the final configuration will include both settings. If both set the same key, the project config wins.

Remote Config

Organizations can provide default configuration via the .well-known/opencode endpoint. This is fetched automatically when you authenticate with a provider that supports it.

Remote config is loaded first, serving as the base layer. All other config sources (global, project, managed) can override these defaults.

// Remote config from .well-known/opencode
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Override in your local config:

// opencode.json (project or global)
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global Config

Place your global OpenCode config in ~/.config/opencode/opencode.json. Use global config for user-wide server/runtime preferences like providers, models, and permissions.

For TUI-specific settings, use ~/.config/opencode/tui.json.

Global config overrides remote organizational defaults.

Project Config

Add opencode.json in your project root. Project config has the highest precedence among standard config files — it overrides both global and remote configs.

When OpenCode starts up, it first looks for a config file in the current directory, then traverses up to the nearest Git directory. This file is safe to check into Git and uses the same schema as the global one.

Custom Config Path (OPENCODE_CONFIG)

Specify a custom config file path using the OPENCODE_CONFIG environment variable:

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Custom config is loaded between global and project configs in the precedence order.

Custom Config Directory (OPENCODE_CONFIG_DIR)

Specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable. This directory will be searched for agents, commands, modes, and plugins just like the standard .opencode directory:

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

The custom directory is loaded after the global config and .opencode directories, so it can override their settings.

.opencode Directories

The .opencode and ~/.config/opencode directories use plural names for subdirectories: agents/, commands/, modes/, plugins/, skills/, tools/, and themes/. Singular names (e.g., agent/) are also supported for backwards compatibility.

Inline Config (OPENCODE_CONFIG_CONTENT)

Pass configuration directly as a JSON string via the OPENCODE_CONFIG_CONTENT environment variable. Useful for runtime overrides without touching files:

export OPENCODE_CONFIG_CONTENT='{"model": "anthropic/claude-sonnet-4-5"}'
opencode run "Hello world"

---

Config Merging Behavior

Configs are merged, not replaced. When two config sources define the same key, the merge behavior depends on the value type:

• Scalar values (strings, numbers, booleans): later source wins
• Objects: recursively merged; later source keys override earlier ones
• Arrays: later source replaces the entire array (not appended)

Example flow:

1. Global sets autoupdate: true
2. Project sets model: "anthropic/claude-sonnet-4-5"
3. Final config: both autoupdate: true AND model: "anthropic/claude-sonnet-4-5" are present

Example with arrays (important caveat):

1. Global sets instructions: ["CONTRIBUTING.md"]
2. Project sets instructions: ["docs/guidelines.md"]
3. Final config: instructions: ["docs/guidelines.md"] — the global array is replaced, not merged

---

All Config Fields

$schema

JSON Schema URL for editor validation and autocomplete.

{
  "$schema": "https://opencode.ai/config.json"
}

model

The primary LLM model used for conversations. Format: provider/model-name.

{
  "model": "anthropic/claude-sonnet-4-5"
}

small_model

A separate model for lightweight tasks like title generation and compaction summaries. By default, OpenCode tries to use a cheaper model from your provider, falling back to the main model.

{
  "small_model": "anthropic/claude-haiku-4-5"
}

provider

Provider configuration with API keys, endpoints, and options. Each key is a provider ID (e.g., anthropic, openai, amazon-bedrock, ollama).

{
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

Provider options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeout | number \| false | 300000 | Request timeout in milliseconds. Set to false to disable. | | chunkTimeout | number | — | Timeout in ms between streamed response chunks. Aborts if no chunk arrives in time. | | setCacheKey | boolean | — | Ensure a cache key is always set for the provider. | | baseURL | string | — | Custom base URL for the provider (useful for proxies, gateways, local servers). | | headers | object | — | Custom HTTP headers sent with provider requests. |

Custom provider (npm):

Use any OpenAI-compatible provider by specifying an npm package:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

plugin

Load plugins from npm packages or local paths:

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Plugins can also be placed in .opencode/plugins/ or ~/.config/opencode/plugins/ as JavaScript/TypeScript files, which are loaded automatically at startup.

mcp

MCP (Model Context Protocol) server configurations for adding external tools:

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "@my-org/mcp-server"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      }
    },
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Local MCP options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | type | "local" | Yes | Must be "local" | | command | array | Yes | Command and arguments to run the MCP server | | environment | object | No | Environment variables for the server process | | enabled | boolean | No | Enable/disable the server on startup | | timeout | number | No | Timeout in ms for fetching tools (default: 5000) |

Remote MCP options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | type | "remote" | Yes | Must be "remote" | | url | string | Yes | URL of the remote MCP server | | enabled | boolean | No | Enable/disable the server on startup | | headers | object | No | HTTP headers for the request | | oauth | object \| false | No | OAuth config or false to disable OAuth auto-detection | | timeout | number | No | Timeout in ms for fetching tools (default: 5000) |

Remote MCP OAuth options:

| Option | Type | Description | |--------|------|-------------| | clientId | string | OAuth client ID. If not provided, dynamic client registration is attempted. | | clientSecret | string | OAuth client secret, if required. | | scope | string | OAuth scopes to request. |

tools

Enable/disable tools globally. Set a tool to false to disable it, or true to enable it:

{
  "tools": {
    "write": false,
    "bash": false
  }
}

Glob patterns are supported for MCP tool names:

{
  "tools": {
    "my-mcp*": false
  }
}

As of v1.1.1, the legacy tools boolean config is deprecated and has been merged into permission.

permission

Granular permission rules for tool execution. Controls whether actions require user approval, are auto-approved, or are blocked.

{
  "permission": {
    "*": "ask",
    "bash": "ask",
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/*.mdx": "allow"
    }
  }
}

Permission values:

| Value | Description | |-------|-------------| | "allow" | Run without approval | | "ask" | Prompt user for approval | | "deny" | Block the action |

Available permission keys:

| Key | Matches | |-----|---------| | read | File reads (matches file path) | | edit | All file modifications (edit, write, patch) | | glob | File globbing (matches glob pattern) | | grep | Content search (matches regex pattern) | | bash | Shell commands (matches parsed commands) | | task | Subagent launches (matches subagent type) | | skill | Skill loading (matches skill name) | | lsp | LSP queries (currently non-granular) | | question | User questions during execution | | webfetch | URL fetching (matches URL) | | websearch | Web search (matches query) | | external_directory | Tool calls touching paths outside project root | | doom_loop | Triggered when same tool call repeats 3x with identical input | | * | Catch-all for any permission |

Granular rules (object syntax):

Rules are evaluated by pattern match, with the last matching rule winning. Use "*" as catch-all first, then specific patterns after.

• * matches zero or more of any character
• ? matches exactly one character
• All other characters match literally

Home directory expansion:

Use ~ or $HOME at the start of a pattern to reference your home directory:

• ~/projects/* → /Users/username/projects/*
• $HOME/projects/* → /Users/username/projects/*

External directory access:

Use external_directory to allow tool calls that touch paths outside the working directory:

{
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

Defaults (if nothing is specified):

• Most permissions default to "allow"
• doom_loop and external_directory default to "ask"
• read defaults to "allow" but .env files are denied:

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

What "Ask" does:

When OpenCode prompts for approval, three outcomes are offered:

• once — approve just this request
• always — approve future requests matching suggested patterns (rest of session)
• reject — deny the request

Agent-level permissions:

Permissions can be overridden per agent. Agent permissions merge with global config, and agent rules take precedence:

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git commit *": "ask",
          "git push *": "deny"
        }
      }
    }
  }
}

agent

Define specialized agents for specific tasks. Each agent can have its own model, prompt, tools, permissions, and other settings.

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      },
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Agents can also be defined as markdown files in ~/.config/opencode/agents/ or .opencode/agents/:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
Only analyze code and suggest changes.

default_agent

Set the default agent used when none is explicitly specified. Must be a primary agent (not a subagent). Can be a built-in agent ("build", "plan") or a custom agent. Falls back to "build" with a warning if the specified agent doesn't exist or is a subagent.

{
  "default_agent": "plan"
}

This setting applies across all interfaces: TUI, CLI (opencode run), desktop app, and GitHub Action.

share

Configure the conversation sharing feature:

{
  "share": "manual"
}

| Value | Description | |-------|-------------| | "manual" | Allow manual sharing via /share command (d

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Timmy6942025
• Source: Timmy6942025/opencode-builder-skill
• License: MIT

Install and usage instructions live in the source repository linked above.