YouTipA Minimal Working Configuration Example
\n\n{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5", "autoupdate": true, "theme": "default"}\nCommon global configuration items:\n\n| Configuration Item | \nType | \nDescription | \n
|---|---|---|
model | \nstring | \nDefault main model | \n
small_model | \nstring | \nLightweight task model (e.g., for title generation) | \n
autoupdate | \nboolean / "notify" | \nAuto-update policy | \n
theme | \nstring | \nUI theme | \n
provider | \nobject | \nModel provider configuration | \n
Provider example:
\n\n{ "provider": { "anthropic": { "options": { "timeout": 600000, "setCacheKey": true } } }}\nUnderstanding the Configuration "Merge Mechanism"
\n\nOpenCode's configuration is not overwritten, but layered and merged.
\n\nLoading Order (from lowest to highest)
\n\n| Order | \nSource | \nDescription | \n
|---|---|---|
| 1 | \nRemote .well-known/opencode | \nOrganization default configuration | \n
| 2 | \nGlobal configuration | \n~/.config/opencode/opencode.json | \n
| 3 | \nCustom path | \nOPENCODE_CONFIG | \n
| 4 | \nProject configuration | \nopencode.json in the project | \n
| 5 | \n.opencode/ directory | \nExtended capabilities | \n
| 6 | \nInline configuration | \nOPENCODE_CONFIG_CONTENT | \n
Merge Rules
\n\n- \n
- Non-conflicting fields: all retained \n
- Conflicting fields: the latter overwrites the former \n
Example
\n\nGlobal configuration:
\n\n{ "autoupdate": true}\nProject configuration:
\n\n{ "model": "anthropic/claude-sonnet-4-5"}\nFinal result:
\n\n{ "autoupdate": true, "model": "anthropic/claude-sonnet-4-5"}\n\n\n\n
Project Configuration
\n\nCreate in the project root directory:
\n\nopencode.json\nPurpose:
\n\n- \n
- Define project-specific AI behavior \n
- Can be committed to Git \n
- Override global configuration \n
Example: Project-level Configuration
\n\n{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5", "tools": { "write": true, "bash": true }}\n\n\n\n
Core Configuration Modules Explained
\n\n{ "model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5"}\nModel and Provider
\n\n{ "model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5"}\n| Field | \nDescription | \n
|---|---|
model | \nMain task model | \n
small_model | \nLow-cost task model | \n
Tool Control
\n\n{ "tools": { "write": false, "bash": false }}\n| Tool | \nPurpose | \n
|---|---|
| write | \nWrite files | \n
| bash | \nExecute commands | \n
This is the first layer of security control.
\n\nPermission Control
\n\n{ "permission": { "edit": "ask", "bash": "ask" }}\n| Value | \nMeaning | \n
|---|---|
| allow | \nAuto-execute | \n
| ask | \nConfirm each time | \n
| deny | \nProhibit | \n
Agent (Core Capability)
\n\n{ "agent": { "code-reviewer": { "description": "Code review", "model": "anthropic/claude-sonnet-4-5", "prompt": "You are a code reviewer", "tools": { "write": false } } }}\nEssence: Defining roles + capability scope for AI
\n\nCommand (Automated Prompt)
\n\n{ "command": { "test": { "template": "Run tests and fix failures", "description": "Run tests" } }}\nEssence: Prompt template system
\n\nTUI Configuration
\n\n{ "tui": { "scroll_speed": 3, "scroll_acceleration": { "enabled": true }, "diff_style": "auto" }}\nServer Configuration (API / Web)
\n\n{ "server": { "port": 4096, "hostname": "0.0.0.0", "mdns": true }}\nContext Compression (Token Optimization)
\n\n{ "compaction": { "auto": true, "prune": true, "reserved": 10000 }}\nPlugin System
\n\n{ "plugin": [ "opencode-helicone-session", "@my-org/custom-plugin" ]}\nMCP (Extended Ecosystem)
\n\n{ "mcp": {}}\nUsed to connect external tools (such as Jira, databases, etc.)
\n\nInstruction System (AI Rules)
\n\n{ "instructions": [ "CONTRIBUTING.md", "docs/*.md" ]}\nProvider Control
\n\n{ "enabled_providers": , "disabled_providers": }\nPriority:
\n\ndisabled > enabled
\n\nVariable System
\n\nEnvironment Variables:
\n\n{ "model": "{env:OPENCODE_MODEL}"}\nFile Reference
\n\n{ "apiKey": "{file:~/.secrets/key}"}\n\n\n\n
Directory Extension Mechanism
\n\nOpenCode is not just JSON configuration, it also supports directory extensions:
\n\n.opencode/βββ agents/βββ commands/βββ plugins/βββ tools/βββ themes/\nPurpose:
\n\n- \n
- Markdown-defined agents \n
- File-level commands \n
- Plugin extensions \n
\n\n
Recommended Starter Configuration
\n\n{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5", "autoupdate": "notify", "tools": { "write": true, "bash": true }, "permission": { "bash": "ask" }, "compaction": { "auto": true, "prune": true }}\n\n\n\n
Summary (Architecture Perspective)
\n\nYou can understand OpenCode configuration as a four-layer structure:
\n\nConfiguration layer (multi-level merge)
\nβ
\nCapability layer (agent / tools / mcp)
\nβ
\nExecution layer (model / provider)
\nβ
\nInteraction layer (tui / server / web)
Essentially, it is not a simple configuration file, but rather:
\n\nA configuration center for a programmable AI Agent operating system
\n \n