Opencode Config

OpenCode Configuration

Help users configure OpenCode through guided setup of config files and rules.

<question_tool>

Batching Rule: Use only for 2+ related questions; single questions use plain text.

Syntax Constraints: header max 12 chars, labels 1-5 words, mark defaults with (Recommended).

Purpose: Clarify config scope (models/permissions/rules), validate approach, and handle multiple valid options.

</question_tool>

<reference>

File Locations

Precedence: Project > Global. Configs are merged, not replaced.

</reference>

<workflow>

Question Tool

Batching: Use the question tool for 2+ related questions. Single questions → plain text.

Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.

When to ask: Vague request ("configure opencode"), permission/security changes, or multiple valid options exist.

Workflow

Ask the user what they want to configure:

1. "What would you like to set up?"

• Config file (models, tools, permissions, theme)
• Rules (project instructions via AGENTS.md)

Then guide them through the relevant section below.

</workflow>

<config_file>

Config File (opencode.json)

Basic Setup

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "theme": "opencode",
  "autoupdate": true
}

Key Options

Permissions

Control what requires approval using the permission field.

{
  "permission": {
    "edit": "allow",           // "allow" | "ask" | "deny"
    "bash": {
      "npm *": "allow",        // pattern matching
      "git *": "allow",
      "rm *": "ask",
      "*": "ask"               // default for this tool
    },
    "webfetch": "allow",
    "skill": {
      "*": "allow",
      "dangerous-*": "deny"
    }
  }
}

Legacy Configuration

Agents may occasionally work on legacy projects using outdated configuration fields (e.g., tools, maxSteps). You MUST correct these to the modern permission and steps fields when encountered.

Custom Instructions

Include additional instruction files:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

Full schema reference: See references/config-schema.md

</config_file>

<rules_file>

Rules (AGENTS.md)

Project instructions for all agents. Similar to CLAUDE.md or Cursor rules.

Create with /init

Run /init in OpenCode to auto-generate based on project analysis.

Manual Creation

# Project Name

This is a [framework] project using [language].

## Project Structure
- `src/` - Source code
- `tests/` - Test files

## Code Standards
- Use TypeScript strict mode
- Prefer functional patterns
- Write tests for all features

## Commands
- `npm run build` - Build project
- `npm test` - Run tests

Tips

• SHOULD be specific about your project's patterns
• SHOULD include common commands
• SHOULD document any non-obvious conventions
• SHOULD keep it concise (agents have limited context)

</rules_file>

<config_tips>

Comment Out, Don't Delete

OpenCode supports JSONC (JSON with comments). SHOULD comment out unused configs instead of deleting:

{
  "plugin": [
    "opencode-openai-codex-auth@latest",
    //"@tarquinen/opencode-dcp@latest",     // disabled for now
    //"@howaboua/pickle-thinker@0.4.0",     // only for GLM-4.6
    "@ramtinj95/opencode-tokenscope@latest"
  ]
}

Why: You might want to re-enable later. Keeps a record of what you've tried.

Validate After Major Changes

After editing opencode.json, you MUST run this validation (not just suggest it):

opencode run "test"

Execute it yourself using the Bash tool before telling the user the change is complete.

If broken, you'll see a clear error with line number:

Error: Config file at ~/.config/opencode/opencode.json is not valid JSON(C):
--- Errors ---
CommaExpected at line 464, column 5
   Line 464:     "explore": {
              ^
--- End ---

Common JSONC mistakes:

• Missing comma after object (especially after adding new sections)
• Trailing comma before }
• Unclosed brackets

</config_tips>

<common_configurations>

Minimal Safe Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Power User Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "autoupdate": true,
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "allow",
      "rm -rf *": "deny",
      "sudo *": "ask"
    }
  },
  "instructions": ["CONTRIBUTING.md"]
}

Team Project Config

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "share": "auto",
  "instructions": [
    "docs/development.md",
    "docs/api-guidelines.md"
  ]
}

</common_configurations>

<troubleshooting>

</troubleshooting>

References

• references/config-schema.md - Full config options

OpenCode Configuration Schema Reference (Q4 2025)

<instructions> This document defines the schema and valid values for opencode.json. You MUST adhere strictly to these definitions. You MUST NOT use deprecated model identifiers. </instructions>

<critical_warning>

STRICTLY PROHIBITED MODELS

The following models are DEPRECATED and MUST NOT be used:

• OpenAI: gpt-4o, gpt-4-turbo, o1-mini, o1-preview
• Anthropic: claude-3-5-sonnet, claude-3-opus
• Google: gemini-1.5-pro, gemini-2.0-flash
• Meta: llama-3, llama-3.1

Use current frontier models: GPT-5.2, Claude 4.5, Gemini 3, GLM-4.7, Kimi K2, MiniMax M2.1, Mistral Large 3. </critical_warning>

<top_level_options>

{
  "$schema": "https://opencode.ai/config.json",

  // Model Configuration
  "model": "provider/model-id",
  "small_model": "provider/model-id",
  "provider": {},
  "disabled_providers": ["openai", "gemini"],

  // UI & Updates
  "theme": "opencode",
  "autoupdate": true,
  "tui": { "scroll_speed": 3 },
  "keybinds": {},

  // Sharing
  "share": "manual", // "manual" | "auto" | "disabled"

  // Tools & Permissions
  "tools": {},
  "permission": {},

  // Agents & Commands
  "agent": {},
  "command": {},

  // Instructions & MCP
  "instructions": [],
  "mcp": {},

  // Formatters
  "formatter": {},
}

</top_level_options>

<model_configuration>

model / small_model

{
  "model": "anthropic/claude-4-5-sonnet-20250929",
  "small_model": "anthropic/claude-4-5-haiku-20251015",
}

Format: provider/model-id. Run opencode models to list available models.

provider

Configure custom providers or override settings:

{
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
      },
    },
  },
}

disabled_providers

Prevent providers from loading even if credentials exist:

{
  "disabled_providers": ["openai", "gemini"],
}

</model_configuration>

<tools_configuration>

Enable/disable tools globally:

{
  "tools": {
    "bash": true,
    "edit": true,
    "write": true,
    "read": true,
    "glob": true,
    "grep": true,
    "list": true,
    "patch": true,
    "webfetch": true,
    "todowrite": true,
    "todoread": true,
    "skill": true,
  },
}

Wildcards supported for MCP tools:

{
  "tools": {
    "mymcp_*": false,
  },
}

</tools_configuration>

<permissions>

Simple Permissions

{
  "permission": {
    "edit": "allow", // "allow" | "ask" | "deny"
    "webfetch": "ask",
  },
}

Pattern-Based Bash Permissions

{
  "permission": {
    "bash": {
      "*": "allow", // Default for all
      "rm *": "ask", // Ask before delete
      "rm -rf *": "deny", // Block recursive delete
      "sudo *": "deny", // Block sudo
      "git push": "ask", // Ask before push
      "npm run *": "allow", // Allow npm scripts
    },
  },
}

Skill Permissions

{
  "permission": {
    "skill": {
      "*": "allow",
      "dangerous-*": "deny",
      "experimental-*": "ask",
    },
  },
}

</permissions>

<agent_configuration>

Define agents in config:

{
  "agent": {
    "my-agent": {
      "description": "What triggers this agent",
      "mode": "subagent",
      "model": "anthropic/claude-4-5-sonnet-20250929",
      "prompt": "System prompt or {file:./prompt.txt}",
      "temperature": 0.3,
      "maxSteps": 25,
      "disable": false,
      "tools": {
        "bash": false,
      },
      "permission": {
        "edit": "ask",
      },
    },
  },
}

</agent_configuration>

<commands>

Custom slash commands:

{
  "command": {
    "test": {
      "template": "Run tests and show failures. $ARGUMENTS",
      "description": "Run test suite",
      "agent": "build",
      "model": "anthropic/claude-4-5-sonnet-20250929",
    },
  },
}

Use $ARGUMENTS for user input after command.

</commands>

<instructions>

Include additional instruction files:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "packages/*/AGENTS.md",
  ],
}

Supports glob patterns.

</instructions>

<formatters>

Configure code formatters:

{
  "formatter": {
    "prettier": {
      "disabled": true,
    },
    "custom": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": { "NODE_ENV": "development" },
      "extensions": [".js", ".ts", ".jsx", ".tsx"],
    },
  },
}

</formatters>

<mcp_servers>

Configure Model Context Protocol servers:

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "@org/package"],
      "environment": { "KEY": "VALUE" },
    },
    "remote-name": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ..." },
    },
  },
}

</mcp_servers>

<model_variants>

Model Variants (ctrl+t)

Variants allow you to define multiple parameter sets for a single model, cycleable via ctrl+t.

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5.2": {
          "variants": {
            "high": {
              "reasoningEffort": "high",
              "reasoningSummary": "detailed",
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "low",
            },
          },
        },
      },
    },
  },
}

Functional Variant Properties

| Property | Provider | Values | | ------------------ | ----------------- | ------------------------------------------- | ------- | | reasoningEffort | OpenAI/Azure | minimal, low, medium, high, xhigh | | reasoningSummary | OpenAI/Azure | auto, detailed | | textVerbosity | OpenAI Compatible | low, medium, high | | thinking | Anthropic | { type: "enabled", budgetTokens: number } | | thinkingLevel | Google | "low" | "high" | | include | OpenAI/Azure | ["reasoning.encrypted_content"] |

</model_variants>

<variable_substitution>

Environment Variables

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
      },
    },
  },
}

File Contents

{
  "agent": {
    "custom": {
      "prompt": "{file:./prompts/custom.txt}",
    },
  },
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{file:~/.secrets/anthropic-key}",
      },
    },
  },
}

</variable_substitution>

<misc_options>

TUI Options

{
  "tui": {
    "scroll_speed": 3,
  },
}

Sharing Options

{
  "share": "manual", // "manual" | "auto" | "disabled"
}

• manual - Share via /share command (default)
• auto - Auto-share new conversations
• disabled - No sharing

</misc_options>