How to Configure OpenCode Settings and Open the opencode.json Config File

Apr 21, 2026

I wanted to customize OpenCode’s default model, set up custom agents, and adjust permissions, but I couldn’t find where the configuration file was stored. After digging through the documentation, I discovered OpenCode uses opencode.json for configuration, with different locations for global and project-level settings.

Configuration File Locations

OpenCode stores configuration in opencode.json at two levels:

Global configuration applies to all projects:

Mac/Linux: ~/.config/opencode/opencode.json
Windows: %USERPROFILE%\.config\opencode\opencode.json

Project configuration overrides global settings for a specific project:

Located in your project root as ./opencode.json

┌─────────────────────────────────────────────────────────┐
│  1. Remote Config (Organization Defaults)              │
│     ↓                                                   │
│  2. Global Config (~/.config/opencode/opencode.json)    │
│     ↓                                                   │
│  3. Environment Variable (OPENCODE_CONFIG)              │
│     ↓                                                   │
│  4. Project Config (./opencode.json)                   │
│     ↓                                                   │
│  5. Managed Config (Enterprise-Enforced) ← HIGHEST     │
└─────────────────────────────────────────────────────────┘

Opening the Global Config File

Mac and Linux

Open with VS Code:

code ~/.config/opencode/opencode.json

Open with default editor:

open ~/.config/opencode/opencode.json

Create the config if it doesn’t exist:

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json
open ~/.config/opencode/opencode.json

Mac Finder method:

Open Finder
Press Cmd + Shift + G (Go to Folder)
Enter: ~/.config/opencode
Double-click opencode.json to open with default editor

Windows

Open with Notepad:

notepad $env:USERPROFILE\.config\opencode\opencode.json

Open with VS Code:

code $env:USERPROFILE\.config\opencode\opencode.json

Create the config if missing:

New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.config\opencode
New-Item -ItemType File -Force -Path $env:USERPROFILE\.config\opencode\opencode.json
notepad $env:USERPROFILE\.config\opencode\opencode.json

Windows Explorer method:

Open File Explorer
Type in address bar: %USERPROFILE%\.config\opencode
Press Enter
Double-click opencode.json

Opening the Project Config File

Project-level config is straightforward—just open the file in your project root:

open ./opencode.json
# or with VS Code
code ./opencode.json

notepad .\opencode.json
# or with VS Code
code .\opencode.json

Using OpenCode’s Built-in Editor Command

OpenCode provides a universal /editor command that works on any OS:

/editor ~/.config/opencode/opencode.json

/editor %USERPROFILE%\.config\opencode\opencode.json

Global Configuration Structure

The global config controls your default OpenCode settings:

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

Project Configuration Structure

Project config overrides global settings for a specific project:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "instructions": ["docs/guidelines.md", ".cursor/rules/*.md"],
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"]
    }
  }
}

TUI Appearance Configuration

OpenCode stores TUI (Terminal User Interface) appearance settings separately in tui.json:

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

Advanced Configuration Examples

Custom Agents

Create specialized agents for specific tasks:

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

Use the custom agent: @code-reviewer review this function

Custom Commands

Create reusable command templates:

{
  "command": {
    "test": {
      "template": "Run the full test suite and generate coverage report, focus on failed tests and provide fix suggestions.",
      "description": "Run tests",
      "agent": "build"
    },
    "component": {
      "template": "Create a React component named $ARGUMENTS using TypeScript with proper types and basic structure.",
      "description": "Create component"
    }
  }
}

Use the commands: /test or /component UserCard

Permission Controls

Configure when OpenCode should ask for permission:

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

Common Mistakes

When working with OpenCode configuration, avoid these pitfalls:

Editing project config when you need global changes — If you want a setting to apply to all projects, edit ~/.config/opencode/opencode.json, not ./opencode.json in your project root.

Creating the config file in the wrong location — Double-check the path. On Mac/Linux, it’s ~/.config/opencode/opencode.json, not ~/.opencode/opencode.json.

Forgetting to commit project-level configuration — When you create a project-specific opencode.json, remember to commit it to Git along with AGENTS.md so your team can use the same configuration.

Not understanding the priority hierarchy — Project config overrides global config. If a setting isn’t working as expected, check if there’s a project-level opencode.json overriding your global settings.

Why Configuration Matters

Proper configuration lets you optimize OpenCode for your workflow:

Set your preferred default model instead of changing it every session
Restrict permissions for security-sensitive projects
Create custom agents and commands to automate repetitive tasks
Share consistent settings across your team through project-level config

Summary

In this post, I explained where OpenCode stores its configuration files and how to open them on Mac, Linux, and Windows. I covered the priority hierarchy from remote config down to managed config, showed practical examples for global, project, and TUI configurations, and demonstrated advanced features like custom agents, commands, and permission controls.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 OpenCode Configuration Documentation
👨‍💻 OpenCode Custom Agents Guide
👨‍💻 OpenCode Permissions Reference

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!