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
- [MCP Setup in OpenCode](/mcp/implementation-guide/opencode) — step-by-step MCP configuration
- [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
CLI-First Development with Antigravity Image Pipeline
Use fast CLI tools for all coding, then switch to Antigravity for Nano Banana image generation. Both under one Google AI Pro plan with no per-image fees.
Prompt Engineering in GitHub Copilot
Prompt patterns for GitHub Copilot chat, inline edits, and agent mode. Master workspace context, slash commands, step-by-step feature patterns, PR-focused prompting, and common pitfalls.
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.