文档
English Docs
Config

Configuration

OpenCode utilizes a JSON configuration system for customization. The configuration schema is defined at opencode.ai/config.json, enabling editor validation and autocomplete support.

Format Support

OpenCode accepts both JSON and JSONC (JSON with Comments) formats.

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

Configuration Locations & Precedence

Settings are merged together rather than replaced. The load order (later sources override conflicts):

  1. Remote config – Organizational defaults from .well-known/opencode
  2. Global config – User preferences at ~/.config/opencode/opencode.json
  3. Custom config – OPENCODE_CONFIG environment variable
  4. Project config – opencode.json in project root
  5. .opencode directories – Agents, commands, plugins
  6. Inline config – OPENCODE_CONFIG_CONTENT environment variable

Global Configuration

Place user-wide preferences in ~/.config/opencode/opencode.json:

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

Project Configuration

Add opencode.json to your project root for project-specific settings.

Custom Path

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

Configuration Schema

TUI Settings

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Server Settings

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}

Tools Configuration

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

Models & Providers

{
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Agents

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer...",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Custom Commands

{
  "command": {
    "test": {
      "template": "Run full test suite with coverage report.",
      "description": "Run tests with coverage",
      "agent": "build"
    }
  }
}

Permissions

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Context Compaction

{
  "compaction": {
    "auto": true,
    "prune": true
  }
}

MCP Servers

{
  "mcp": {}
}

Plugins

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

Variable Substitution

Environment Variables

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

File Contents

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}
IntroductionProviders