--- title: "Config" description: "Configure OpenCode." --- You shouldn't have to configure OpenCode manually. Ask OpenCode to update its configuration for you. ## Format OpenCode supports both **JSON** and **JSONC** (JSON with Comments) configuration files. ```jsonc title="opencode.jsonc" { "$schema": "https://opencode.ai/config.json", "model": "openai/gpt-5.2-custom", "providers": { "openai": { "models": { "gpt-5.2-custom": { "modelID": "gpt-5.2", "name": "GPT-5.2 Custom" } } } } } ``` ## Locations OpenCode loads global configuration from: ```text ~/.config/opencode/opencode.json(c) ``` Project-specific configuration can use either form: ```text /home/user/projects/my-app/opencode.json(c) /home/user/projects/my-app/.opencode/opencode.json(c) ``` When OpenCode starts, it searches for configuration files from the current directory upward to the project root. The files are merged, and configuration closer to the current directory takes precedence. For example, consider a monorepo with OpenCode started from `/home/user/projects/acme/packages/web`: ```text ~/.config/opencode/opencode.json /home/user/projects/acme/ ├── opencode.json └── packages/ └── web/ ├── opencode.json └── src/ ``` OpenCode applies these files from lowest to highest precedence: 1. `~/.config/opencode/opencode.json` 2. `/home/user/projects/acme/opencode.json` 3. `/home/user/projects/acme/packages/web/opencode.json` Settings in the package config override matching settings from the repository config, which override matching settings from the global config. Settings that do not conflict are preserved from every file. ## Schema The complete OpenCode configuration schema is available at [opencode.ai/config.json](https://opencode.ai/config.json). Add the `$schema` field to your configuration file to enable validation and autocomplete in editors that support JSON Schema: ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json" } ``` Use the schema as the source of truth for available fields, accepted values, and nested configuration shapes. ### Shell Set the shell used by the terminal and shell tools. ```jsonc { "shell": "/bin/zsh" } ``` ### Model Set the default model in `provider/model` format. Add `#variant` to select a specific model variant. ```jsonc { "model": "anthropic/claude-sonnet-4-5#high" } ``` See the [models guide](https://opencode.ai/docs/models/) for model selection and local models. ### Default agent Choose the primary agent used when a session does not select one explicitly. ```jsonc { "default_agent": "build" } ``` See the [agents guide](https://opencode.ai/docs/agents/) for built-in and custom agents. ### Autoupdate Control automatic updates. Set this to `false` to disable updates or `"notify"` to receive update notifications. ```jsonc { "autoupdate": false } ``` ### Sharing Control whether sessions can be shared manually, shared automatically, or not shared at all. ```jsonc { "share": "manual" } ``` See the [sharing guide](https://opencode.ai/docs/share/) for more details. ### Username Set the username displayed in conversations. ```jsonc { "username": "alice" } ``` ### Permissions Define ordered rules that allow, deny, or ask before an agent uses a tool on a matching resource. ```jsonc { "permissions": [ { "action": "bash", "resource": "git push *", "effect": "ask" } ] } ``` See the [permissions guide](https://opencode.ai/docs/permissions/) for rule matching and available actions. ### Agents Override built-in agents or define specialized agents with their own model, instructions, mode, and permissions. ```jsonc { "agents": { "reviewer": { "description": "Review changes without editing files", "mode": "subagent", "system": "Focus on correctness, security, and missing tests.", "permissions": [ { "action": "edit", "resource": "*", "effect": "deny" } ] } } } ``` See the [agents guide](https://opencode.ai/docs/agents/) for all agent options and file-based agents. ### Snapshots Enable or disable the snapshots used by undo and revert behavior. ```jsonc { "snapshots": false } ``` ### Watcher Ignore files and directories that should not trigger filesystem updates. ```jsonc { "watcher": { "ignore": ["dist/**", "coverage/**"] } } ``` ### Formatter Enable built-in formatters, disable formatting entirely, or configure formatter commands by name. ```jsonc { "formatter": { "prettier": { "command": ["bunx", "prettier", "--write", "$FILE"], "extensions": [".js", ".ts", ".tsx"] } } } ``` See the [formatters guide](https://opencode.ai/docs/formatters/) for built-in formatters and custom commands. ### LSP Enable built-in language servers, disable them, or configure servers by name. ```jsonc { "lsp": { "typescript": { "command": ["typescript-language-server", "--stdio"], "extensions": [".ts", ".tsx"] } } } ``` See the [LSP guide](https://opencode.ai/docs/lsp/) for language server setup. ### Attachments Control how oversized image attachments are resized or rejected before they are sent to a model. ```jsonc { "attachments": { "image": { "auto_resize": true, "max_width": 2000, "max_height": 2000, "max_base64_bytes": 5242880 } } } ``` ### Tool output Set the maximum number of lines and bytes retained from a tool result. ```jsonc { "tool_output": { "max_lines": 2000, "max_bytes": 51200 } } ``` ### MCP Configure local and remote Model Context Protocol servers. Global timeouts can be overridden by an individual server. ```jsonc { "mcp": { "servers": { "playwright": { "type": "local", "command": ["bunx", "@playwright/mcp"] } } } } ``` See the [MCP guide](https://opencode.ai/docs/mcp-servers/) for remote servers, OAuth, environment variables, and timeouts. ### Compaction Control automatic context compaction and how much recent context it preserves. ```jsonc { "compaction": { "auto": true, "keep": { "tokens": 8000 }, "buffer": 20000 } } ``` ### Skills Add directories or URLs that OpenCode should search for agent skills. ```jsonc { "skills": ["./team-skills", "https://example.com/.well-known/skills/"] } ``` See the [skills guide](https://opencode.ai/docs/skills/) for skill structure and automatic discovery under `.opencode/skills/`. ### Commands Define reusable slash commands as named prompt templates. ```jsonc { "commands": { "review": { "description": "Review the current changes", "template": "Review the current diff for correctness and missing tests." } } } ``` See the [commands guide](https://opencode.ai/docs/commands/) for arguments, models, agents, and file-based commands. ### Instructions Load additional instruction files, globs, or URLs into the agent's context. ```jsonc { "instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"] } ``` See the [rules guide](https://opencode.ai/docs/rules/) for project instructions and `AGENTS.md`. ### References Make local directories or Git repositories available as named supporting context. ```jsonc { "references": { "docs": { "path": "../product-docs", "description": "Product behavior and terminology" }, "effect": { "repository": "Effect-TS/effect", "branch": "main" } } } ``` See the [references guide](https://opencode.ai/docs/references/) for shorthand, visibility, and path resolution. ### Plugins Load plugins from packages or local files. Use the object form when a plugin accepts options. ```jsonc { "plugins": [ "opencode-example-plugin", { "package": "./plugins/local.ts", "options": { "enabled": true } } ] } ``` See the [plugins guide](/plugins) for plugin development and configuration. ### Providers Configure providers and add or override their models, request settings, headers, and model variants. ```jsonc { "providers": { "openai": { "models": { "gpt-5.2-custom": { "modelID": "gpt-5.2", "name": "GPT-5.2 Custom", "limit": { "context": 200000, "output": 32000 } } } } } } ``` See the [providers guide](https://opencode.ai/docs/providers/) for credentials, custom endpoints, provider packages, and model configuration.