Configuration

OpenCode uses a JSON config file for customization. This page covers the config format, file locations, and key options.

Format

OpenCode supports both JSON and JSONC (JSON with Comments) formats:

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

The $schema field enables IDE autocompletion and validation.

Config Locations

Config files are loaded in the following order. Later sources override earlier ones:

Priority	Location	Purpose
1 (lowest)	Remote (.well-known/opencode)	Organizational defaults
2	Global (~/.config/opencode/opencode.json)	User preferences
3	Custom (OPENCODE_CONFIG env var)	Custom overrides
4 (highest)	Project (opencode.json in project root)	Project-specific settings

Additionally, .opencode directories and OPENCODE_CONFIG_CONTENT (inline config) can provide runtime overrides.

TIP

Configuration files are merged together, not replaced. Non-conflicting settings from all locations are preserved. Conflicting keys are resolved by priority.

Global Config

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

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

Project Config

Add opencode.json in your project root for project-specific settings. This is safe to commit to Git:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

Key Options

Model Selection

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

• model — The primary model for coding tasks
• small_model — A cheaper model for lightweight tasks like title generation

Provider Configuration

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000
      }
    }
  }
}

• timeout — Request timeout in milliseconds (default: 300000)
• chunkTimeout — Timeout between streamed response chunks

Tools

Enable or disable tools the LLM can use:

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

Permissions

Control tool behavior — allow, deny, or require approval:

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

Wildcards are supported for batch configuration:

{
  "permission": {
    "mymcp_*": "ask"
  }
}

Instructions (Rules)

Point to instruction files that guide the AI:

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Agents

Define specialized agents for specific tasks:

{
  "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
      }
    }
  }
}

Custom Commands

Create reusable commands for repetitive tasks:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.",
      "description": "Run tests with coverage",
      "agent": "build"
    }
  }
}

Sharing

{
  "share": "manual"
}

Options: "manual" (default), "auto", or "disabled".

Compaction

Control context compaction when the conversation gets long:

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

Snapshot

OpenCode uses snapshots to track file changes, enabling undo/redo. Disable for large repos:

{
  "snapshot": false
}

Autoupdate

{
  "autoupdate": false
}

Set to "notify" to be notified of updates without auto-downloading.

MCP Servers

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true
    }
  }
}

Plugins

Load plugins from npm or local files:

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

Variable Substitution

Environment Variables

Use {env:VARIABLE_NAME} to reference environment variables:

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

File Contents

Use {file:path/to/file} to include file contents:

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

TUI Config

TUI-specific settings use a separate tui.json file:

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "diff_style": "auto"
}

Place it alongside your opencode.json (globally or per-project).

Further Reading

• Official Config Documentation
• Config JSON Schema
• TUI JSON Schema