OpenCode: OpenCode Configuration File

Last updated: 2026-08-31

OpenCode manages all settings through the opencode.json configuration file, including models, agents, tools, themes, and more.

1. What You Will Learn

• Configuration file locations and priority
• Complete opencode.json structure
• Common configuration options
• Environment variable configuration

2. Configuration File Locations

OpenCode loads configuration in this priority order (later overrides earlier):

3. Complete Configuration Structure

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": {},
  "agent": {},
  "tools": {},
  "permission": {},
  "theme": {},
  "tui": {}
}

(1) provider

Configure custom model providers:

{
  "provider": {
    "my-provider": {
      "name": "My Custom Provider",
      "baseURL": "https://api.example.com/v1",
      "apiKey": "sk-xxx"
    }
  }
}

(2) model

Set the default model:

{
  "model": {
    "default": "anthropic/claude-sonnet-4-20250514"
  }
}

(3) agent

Configure custom agents (see Lesson 13 for details):

{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

(4) tools

Global tool toggles:

{
  "tools": {
    "write": true,
    "edit": true,
    "bash": true
  }
}

(5) permission

Fine-grained permission control:

{
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "grep *": "allow"
    }
  }
}

Permission values:

(6) tui

Terminal UI settings:

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

4. AGENTS.md (Project Rules)

AGENTS.md is the project-level rules file placed in the project root directory, defining AI behavior constraints.

(1) Creation

In TUI enter:

/init

Or manually create an AGENTS.md file.

(2) Content Example

# Project Rules

- Always use TypeScript for new files
- Follow ESLint configuration
- Write unit tests for all new functions
- Use conventional commits format

5. Environment Variables

❓ FAQ

📖 Summary

• Config loads by priority: global < project < environment variables
• opencode.json is the core config covering models, agents, tools, permissions
• AGENTS.md defines project rules in natural language
• Environment variables suit temporary overrides and CI/CD

📝 Exercises

1. Basic: Create a global opencode.json with your preferred model provider.

2. Intermediate: Create a project-level .opencode/opencode.json with project-specific tool permissions.

3. Advanced: Write an AGENTS.md defining coding standards and AI behavior constraints, then have OpenCode follow it.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us