OpenCode — Configuration Reference

Complete OpenCode configuration reference. Covers opencode.json settings, MCP server integration, skills system, .opencode/ directory conventions, and environment variables.

opencodeconfigurationmcpskillssettings

OpenCode — Configuration Reference

OpenCode uses opencode.json for project settings and ~/.config/opencode/ for global configuration. The .opencode/ directory contains project-specific skills, MCP configs, and conventions.

opencode.json

Project root or ~/.config/opencode/opencode.json:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "baseUrl": "https://api.anthropic.com/v1",
      "defaultModel": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "defaultModel": "gpt-5"
    },
    "deepseek": {
      "apiKey": "${DEEPSEEK_API_KEY}",
      "baseUrl": "https://api.deepseek.com/v1",
      "defaultModel": "deepseek-v4-pro"
    },
    "google": {
      "apiKey": "${GOOGLE_API_KEY}",
      "defaultModel": "gemini-2.5-pro"
    },
    "openrouter": {
      "apiKey": "${OPENROUTER_API_KEY}",
      "baseUrl": "https://openrouter.ai/api/v1"
    },
    "ollama": {
      "baseUrl": "http://localhost:11434/api",
      "defaultModel": "llama4"
    }
  },
  "permissions": {
    "defaultMode": "ask",
    "trustedCommands": [
      "npm run *",
      "npx vitest *",
      "git status",
      "git diff *"
    ],
    "blockedCommands": [
      "git push *",
      "npm install *",
      "rm -rf *",
      "sudo *"
    ]
  },
  "autoApprove": false,
  "mcp": {
    "servers": {}
  }
}

Provider Configuration

Each provider block supports:

KeyDescription
apiKeyAPI key (use ${ENV_VAR} syntax to avoid hardcoding)
baseUrlAPI endpoint URL
defaultModelModel to use when this provider is selected
headersCustom HTTP headers for the API request
timeoutRequest timeout in ms (default: 120000)

Permission Modes

OpenCode Permission Modes
ModeBehavior
askAsk before every command (default)
autoAuto-approve trusted commands, ask for others
acceptEditsAuto-approve file edits, ask for commands
bypassPermissionsFull auto-approve (use with caution)

Trusted Commands

Glob patterns that auto-approve when auto mode is active:

{
  "permissions": {
    "defaultMode": "auto",
    "trustedCommands": [
      "npm run dev",
      "npm run build",
      "npm run lint",
      "npx vitest *",
      "git status",
      "git diff *",
      "git log *"
    ],
    "blockedCommands": [
      "git push *",
      "npm install *",
      "npm uninstall *",
      "rm *",
      "sudo *"
    ]
  }
}

MCP Server Configuration

Set up MCP tools in opencode.json:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-filesystem", "./"],
        "env": {}
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      },
      "brave-search": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-brave-search"],
        "env": {
          "BRAVE_API_KEY": "${BRAVE_API_KEY}"
        }
      }
    }
  }
}

Skills System

Skills are markdown documents loaded as context. They live in .opencode/skills/ and ~/.config/opencode/skills/:

.opencode/skills/
├── our-auth-patterns.md     # Auth conventions
├── our-api-design.md        # API design rules
├── our-testing-guide.md     # Testing conventions
└── our-deployment.md        # Deployment workflow

Skill file format:

# Auth Patterns for Acme App

## Overview
Authentication uses Clerk with JWT templates for the API.

## Conventions
- All protected routes use the `auth()` helper from `@/lib/auth`
- Role checks use `hasRole(user, 'admin')` — never check role manually
- API endpoints verify JWT in Next.js middleware, not inline

## Common Patterns
```ts
// Server component auth
const { userId } = await auth();
if (!userId) redirect('/sign-in');

Pitfalls

  • Don't call auth() inside loops — it's a network call
  • Clerk sessions expire after 24h — handle gracefully in API routes

Load skills with `/skill <name>`:

/skill our-auth-patterns Add role-based access to the dashboard. Use our existing auth patterns.


## .opencode/ Directory

.opencode/ ├── opencode.json # Project config ├── AGENTS.md # Project system prompt ├── skills/ # Project-specific skills │ ├── auth.md │ └── api-conventions.md ├── rules/ # Additional rules files (like .cursorrules) │ └── backend.md └── env.local # Local environment variables (git-ignored)


## Environment Variables

| Variable | Purpose |
|---|---|
| `ANTHROPIC_API_KEY` | Anthropic provider |
| `OPENAI_API_KEY` | OpenAI provider |
| `GOOGLE_API_KEY` | Google Gemini provider |
| `DEEPSEEK_API_KEY` | DeepSeek provider |
| `OPENROUTER_API_KEY` | OpenRouter provider |
| `OPCODE_PROVIDER` | Override default provider |
| `OPCODE_MODEL` | Override default model |

## Related Pages

- [OpenCode Getting Started](/tools/opencode/getting-started) — Installation and setup
- [Prompt Engineering in OpenCode](/tools/opencode/prompt-engineering) — AGENTS.md and prompts
- [MCP Section](/mcp) — Browse all MCP servers
- [Cursor Rules Configuration](/cursorrules/configuration) — Similar rules concept (cross-reference)

Related Articles

AI Coding Tool Comparison — Which One Should You Use?

Detailed comparison of Claude Code, OpenCode, Gemini CLI, Cursor, and GitHub Copilot. Pricing, context windows, MCP support, prompt patterns, and decision guide for every stack.

Prompt Engineering in Gemini CLI

Master prompt engineering for Gemini CLI. The Ralph loop, system instruction files, sandbox-aware prompting, Google extension patterns, and 1M context strategies.

AI Coding Tools — Prompt Engineering & Configuration

Complete guides for Claude Code, OpenCode, Gemini CLI, Cursor, GitHub Copilot, and more. Tool-specific prompt patterns, configuration files, and setup guides for every major AI coding assistant.