OpenCode — Configuration Reference
Complete OpenCode configuration reference. Covers opencode.json settings, MCP server integration, skills system, .opencode/ directory conventions, and environment variables.
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:
| Key | Description |
|---|---|
apiKey | API key (use ${ENV_VAR} syntax to avoid hardcoding) |
baseUrl | API endpoint URL |
defaultModel | Model to use when this provider is selected |
headers | Custom HTTP headers for the API request |
timeout | Request timeout in ms (default: 120000) |
Permission Modes
| Mode | Behavior |
|---|---|
ask | Ask before every command (default) |
auto | Auto-approve trusted commands, ask for others |
acceptEdits | Auto-approve file edits, ask for commands |
bypassPermissions | Full 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:
For the cross-tool Agent Skills standard (SKILL.md format), see the Agent Skills guide.
# 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
Claude Code — Getting Started
Install and configure Claude Code, Anthropic's terminal-based AI coding agent. Covers installation, API key setup, project configuration, and first session walkthrough.
Prompt Engineering in OpenCode
Master prompt engineering for OpenCode. AGENTS.md conventions, /slash commands, plan mode workflows, provider-switching strategies, and multi-model prompt patterns.
Herdr Gave Me One Terminal for the Whole Herd — and I'm Not Going Back to tmux
Herdr is a new open-source agent multiplexer that brings tmux-like persistence together with real-time agent state awareness. No Electron, no web dashboard, just a Rust binary that lives in your terminal. Here's why it's the first tool in months that's genuinely changed how I work with AI coding agents.