Configuration File Details

Understanding Opencode's configuration system is key to advanced usage. This article will detail configuration file locations, priority rules, and core configuration options.

Configuration File Locations

Opencode supports two levels of configuration:

Config FileLocationScope
Global Config~/.config/opencode/opencode.jsonAll projects
Project Config./opencode.json or ./.opencode/opencode.jsonCurrent project

Windows Users Note: Global config is located at %USERPROFILE%\.config\opencode\opencode.json

Configuration Format: JSONC

Opencode supports JSONC format (JSON with Comments), allowing you to add comments in config files:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Theme configuration
  "theme": "opencode-dark",
  
  /* Main model settings */
  "model": "anthropic/claude-sonnet-4-5",
  
  // Auto update
  "autoupdate": true
}

Configuration Priority

When multiple config files exist, Opencode merges configurations by priority (low to high):

  1. Remote Organization Config - .well-known/opencode (lowest)
  2. Global Config - ~/.config/opencode/opencode.json
  3. Environment Variable Config - OPENCODE_CONFIG environment variable
  4. Project Config - ./opencode.json
  5. Project Directory Config - ./.opencode/
  6. Runtime Config - OPENCODE_CONFIG_CONTENT environment variable (highest)

Important: Configurations are merged, not replaced. Later configurations only override conflicting fields.

Core Configuration Options

1. Model Configuration

{
  // Main model (for complex tasks)
  "model": "anthropic/claude-sonnet-4-5",
  
  // Small model (for simple tasks)
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Enabled providers
  "enabled_providers": ["anthropic", "openai"],
  
  // Disabled providers (higher priority)
  "disabled_providers": ["ollama"]
}

2. Permission Configuration

{
  "permission": {
    // File read permissions
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    
    // File edit permissions
    "edit": "ask",
    
    // Command execution permissions
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "rm -rf": "deny"
    }
  }
}

Permission values:

  • "allow" - Direct pass
  • "ask" - Ask each time
  • "deny" - Direct deny

3. File Watcher Configuration

{
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "*.log"
    ]
  }
}

4. Agent Configuration

{
  "agent": {
    "code-reviewer": {
      "description": "Code review expert",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code review expert focusing on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Practical Configuration Templates

Minimal Configuration

{
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Production-Grade Configuration

{
  "model": "anthropic/claude-opus-4-5",
  "small_model": "deepseek/deepseek-coder",
  
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.key": "deny"
    },
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow"
    }
  },
  
  "watcher": {
    "ignore": ["node_modules/**", "dist/**"]
  }
}

Configuration Validation

# Check current model
opencode config get model

# View all configurations
opencode config list

# Validate config file syntax
opencode config validate

Next Steps

Compiled by the OpenCodex community.

Last Updated: