> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure OpenCode with custom models, providers, LSP servers, MCP servers, and themes

## Overview

OpenCode uses a JSON configuration file to customize behavior, AI models, providers, integrations, and more. The configuration system supports both global and local (project-specific) settings with automatic merging.

## Configuration locations

OpenCode searches for configuration files in the following order:

<Tabs>
  <Tab title="Global configuration">
    **macOS/Linux:**

    * `~/.opencode.json` (primary location)
    * `$XDG_CONFIG_HOME/opencode/.opencode.json`
    * `~/.config/opencode/.opencode.json`

    **Windows:**

    * `%USERPROFILE%\.opencode.json`
    * `%LOCALAPPDATA%\opencode\.opencode.json`
  </Tab>

  <Tab title="Local configuration">
    **Project-level:**

    * `.opencode.json` in your project root directory

    Local configuration is merged with global configuration, with local settings taking precedence.
  </Tab>
</Tabs>

## Configuration structure

Here's a complete example configuration file:

```json theme={null}
{
  "data": {
    "directory": ".opencode"
  },
  "wd": "/path/to/working/directory",
  "agents": {
    "coder": {
      "model": "claude-4-sonnet",
      "maxTokens": 50000,
      "reasoningEffort": "medium"
    },
    "task": {
      "model": "gpt-4.1-mini",
      "maxTokens": 5000
    },
    "title": {
      "model": "gpt-4o-mini",
      "maxTokens": 80
    }
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "disabled": false
    },
    "openai": {
      "apiKey": "sk-...",
      "disabled": false
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
      "type": "stdio"
    }
  },
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "disabled": false
    }
  },
  "contextPaths": [
    ".github/copilot-instructions.md",
    ".cursorrules",
    "opencode.md"
  ],
  "tui": {
    "theme": "opencode"
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "debug": false,
  "debugLSP": false,
  "autoCompact": true
}
```

## Configuration options

### Data storage

<ParamField path="data.directory" type="string" default=".opencode">
  Directory where OpenCode stores session data, history, and databases.
</ParamField>

### Working directory

<ParamField path="wd" type="string">
  Override the default working directory for OpenCode operations.
</ParamField>

### Agents

Agents are specialized AI assistants for different tasks. OpenCode supports three agent types:

<AccordionGroup>
  <Accordion title="coder" icon="code">
    Main coding agent for writing, editing, and debugging code.

    <ParamField path="agents.coder.model" type="string" required>
      Model ID for the coder agent (e.g., `claude-4-sonnet`, `gpt-4.1`)
    </ParamField>

    <ParamField path="agents.coder.maxTokens" type="integer" default="5000">
      Maximum tokens for coder agent responses
    </ParamField>

    <ParamField path="agents.coder.reasoningEffort" type="string">
      Reasoning effort level for models that support it (OpenAI o-series, Anthropic extended thinking)

      **Options:** `low`, `medium`, `high`
    </ParamField>
  </Accordion>

  <Accordion title="task" icon="list-check">
    Task agent for code search, analysis, and exploration.

    <ParamField path="agents.task.model" type="string" required>
      Model ID for the task agent (typically a faster/cheaper model)
    </ParamField>

    <ParamField path="agents.task.maxTokens" type="integer" default="5000">
      Maximum tokens for task agent responses
    </ParamField>

    <ParamField path="agents.task.reasoningEffort" type="string">
      Reasoning effort level (if supported by model)
    </ParamField>
  </Accordion>

  <Accordion title="title" icon="heading">
    Title agent for generating conversation summaries (auto-configured, maxTokens locked to 80).

    <ParamField path="agents.title.model" type="string" required>
      Model ID for the title agent
    </ParamField>
  </Accordion>
</AccordionGroup>

### Providers

Configure API credentials for AI providers. See [AI Models](/core-concepts/ai-models) for supported providers.

<ParamField path="providers.{providerName}.apiKey" type="string">
  API key for the provider. Can also be set via environment variables.
</ParamField>

<ParamField path="providers.{providerName}.disabled" type="boolean" default="false">
  Disable this provider even if credentials are available.
</ParamField>

**Supported providers:**

* `anthropic` - Anthropic API (Claude models)
* `openai` - OpenAI API (GPT, o-series models)
* `gemini` - Google Gemini API
* `groq` - Groq API (Llama, Qwen models)
* `azure` - Azure OpenAI Service
* `bedrock` - AWS Bedrock
* `vertexai` - Google Cloud Vertex AI
* `openrouter` - OpenRouter (multi-provider proxy)
* `copilot` - GitHub Copilot (uses GitHub token)

### MCP servers

Model Context Protocol servers extend OpenCode with additional capabilities.

<ParamField path="mcpServers.{name}.command" type="string" required>
  Command to execute the MCP server
</ParamField>

<ParamField path="mcpServers.{name}.args" type="array">
  Command-line arguments for the MCP server
</ParamField>

<ParamField path="mcpServers.{name}.env" type="array">
  Environment variables for the MCP server (format: `KEY=value`)
</ParamField>

<ParamField path="mcpServers.{name}.type" type="string" default="stdio">
  MCP server type

  **Options:** `stdio`, `sse`
</ParamField>

<ParamField path="mcpServers.{name}.url" type="string">
  URL for SSE-type MCP servers
</ParamField>

<ParamField path="mcpServers.{name}.headers" type="object">
  HTTP headers for SSE-type MCP servers
</ParamField>

**Example MCP server configurations:**

```json theme={null}
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
      "type": "stdio"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": ["GITHUB_PERSONAL_ACCESS_TOKEN=ghp_..."],
      "type": "stdio"
    },
    "sse-server": {
      "command": "curl",
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}
```

### LSP (Language Server Protocol)

Configure language servers for enhanced code intelligence.

<ParamField path="lsp.{language}.command" type="string" required>
  Command to start the language server
</ParamField>

<ParamField path="lsp.{language}.args" type="array">
  Command-line arguments for the language server
</ParamField>

<ParamField path="lsp.{language}.disabled" type="boolean" default="false">
  Disable this language server
</ParamField>

<ParamField path="lsp.{language}.options" type="object">
  Additional LSP server options
</ParamField>

**Example LSP configurations:**

```json theme={null}
{
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "command": "pylsp",
      "args": []
    },
    "go": {
      "command": "gopls",
      "args": ["serve"]
    },
    "rust": {
      "command": "rust-analyzer",
      "args": []
    }
  }
}
```

### Context paths

<ParamField path="contextPaths" type="array">
  Files and directories to automatically include as context for the AI.

  **Default paths:**

  * `.github/copilot-instructions.md`
  * `.cursorrules`
  * `.cursor/rules/`
  * `CLAUDE.md`, `CLAUDE.local.md`
  * `opencode.md`, `opencode.local.md`
  * `OpenCode.md`, `OpenCode.local.md`
  * `OPENCODE.md`, `OPENCODE.local.md`
</ParamField>

### Terminal UI (TUI)

<ParamField path="tui.theme" type="string" default="opencode">
  Visual theme for the terminal interface

  **Available themes:**

  * `opencode` (default)
  * `catppuccin`
  * `dracula`
  * `flexoki`
  * `gruvbox`
  * `monokai`
  * `onedark`
  * `tokyonight`
  * `tron`
</ParamField>

### Shell configuration

<ParamField path="shell.path" type="string" default="$SHELL or /bin/bash">
  Path to the shell used by the bash tool
</ParamField>

<ParamField path="shell.args" type="array" default="[&#x22;-l&#x22;]">
  Arguments passed to the shell
</ParamField>

### Debug options

<ParamField path="debug" type="boolean" default="false">
  Enable debug mode for verbose logging
</ParamField>

<ParamField path="debugLSP" type="boolean" default="false">
  Enable LSP debug mode for language server diagnostics
</ParamField>

<ParamField path="autoCompact" type="boolean" default="true">
  Automatically compact conversation history to manage context size
</ParamField>

## Environment variables

OpenCode supports environment variables for sensitive data:

### Provider API keys

```bash theme={null}
# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google Gemini
export GEMINI_API_KEY="..."

# Groq
export GROQ_API_KEY="gsk_..."

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."

# xAI (Grok)
export XAI_API_KEY="..."

# Azure OpenAI
export AZURE_OPENAI_ENDPOINT="https://....openai.azure.com/"
export AZURE_OPENAI_API_KEY="..."  # Optional with Entra ID

# AWS Bedrock (uses standard AWS credentials)
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# Google Cloud Vertex AI
export VERTEXAI_PROJECT="my-project"
export VERTEXAI_LOCATION="us-central1"
# Or use GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_REGION

# GitHub Copilot (auto-detected from GitHub CLI or environment)
export GITHUB_TOKEN="ghp_..."
```

### Debug options

```bash theme={null}
# Enable development debug mode (writes to .opencode/debug.log)
export OPENCODE_DEV_DEBUG="true"
```

## Configuration precedence

OpenCode merges configuration from multiple sources in this order (later sources override earlier ones):

1. **Built-in defaults** - Hardcoded defaults in the application
2. **Global config file** - `~/.opencode.json` or XDG config directory
3. **Environment variables** - API keys and debug flags
4. **Local config file** - `.opencode.json` in project directory
5. **Command-line flags** - Runtime flags (e.g., `--debug`)

## Auto-configuration

OpenCode automatically configures default models based on available providers, checking in this order:

1. **GitHub Copilot** (if GitHub token found)
2. **Anthropic** (if `ANTHROPIC_API_KEY` set)
3. **OpenAI** (if `OPENAI_API_KEY` set)
4. **Google Gemini** (if `GEMINI_API_KEY` set)
5. **Groq** (if `GROQ_API_KEY` set)
6. **OpenRouter** (if `OPENROUTER_API_KEY` set)
7. **AWS Bedrock** (if AWS credentials available)
8. **Azure OpenAI** (if `AZURE_OPENAI_ENDPOINT` set)
9. **Google Cloud Vertex AI** (if `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` set)

If no providers are configured, OpenCode will prompt you to set up credentials.

## Validation

OpenCode validates your configuration on startup:

* **Model IDs** - Ensures configured models are supported
* **Provider credentials** - Checks that required API keys are present
* **Token limits** - Validates maxTokens doesn't exceed model context windows
* **LSP servers** - Verifies LSP command paths exist
* **MCP servers** - Validates MCP server configurations

Invalid configurations are automatically corrected with warnings logged to help you fix issues.

## Example configurations

<Accordion title="Minimal configuration (using environment variables)">
  ```json theme={null}
  {
    "agents": {
      "coder": {
        "model": "claude-4-sonnet"
      }
    }
  }
  ```

  Set your API key via environment:

  ```bash theme={null}
  export ANTHROPIC_API_KEY="sk-ant-..."
  ```
</Accordion>

<Accordion title="Multi-provider setup">
  ```json theme={null}
  {
    "agents": {
      "coder": {
        "model": "claude-4-sonnet",
        "maxTokens": 50000,
        "reasoningEffort": "high"
      },
      "task": {
        "model": "gpt-4.1-mini",
        "maxTokens": 5000
      }
    },
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-..."
      },
      "openai": {
        "apiKey": "sk-..."
      }
    }
  }
  ```
</Accordion>

<Accordion title="Full featured setup with MCP and LSP">
  ```json theme={null}
  {
    "agents": {
      "coder": {
        "model": "gpt-4.1",
        "maxTokens": 20000,
        "reasoningEffort": "medium"
      },
      "task": {
        "model": "gpt-4.1-mini",
        "maxTokens": 5000
      }
    },
    "providers": {
      "openai": {
        "apiKey": "sk-..."
      }
    },
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
        "type": "stdio"
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": ["GITHUB_PERSONAL_ACCESS_TOKEN=ghp_..."],
        "type": "stdio"
      }
    },
    "lsp": {
      "typescript": {
        "command": "typescript-language-server",
        "args": ["--stdio"]
      },
      "python": {
        "command": "pylsp"
      }
    },
    "contextPaths": [
      ".github/copilot-instructions.md",
      "docs/architecture.md",
      "CONTRIBUTING.md"
    ],
    "tui": {
      "theme": "tokyonight"
    },
    "debug": false,
    "autoCompact": true
  }
  ```
</Accordion>

## Related topics

* [AI Models](/core-concepts/ai-models) - Complete list of supported models and providers
* [Architecture](/core-concepts/architecture) - How OpenCode's configuration system works internally