OpenCode Configuration Schema Reference

This document defines the schema and valid values for opencode.json. Run opencode models to list models currently available to your installation, or browse the full registry at https://models.dev/ (API: curl https://models.dev/api.json). The Model ID field in that registry is the identifier format used in OpenCode config.

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": {},
}

model_configuration

model / small_model

{
  "model": "anthropic/claude-3-5-sonnet-20241022",
  "small_model": "anthropic/claude-3-5-haiku-20241022",
}

Format: provider/model-id. Run opencode models to list available models, or look up the Model ID field at https://models.dev/ (machine-readable: curl https://models.dev/api.json).

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"],
}

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,
  },
}

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",
    },
  },
}

agent_configuration

Define agents in config:

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

commands

Custom slash commands:

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

Use $ARGUMENTS for user input after command.

instructions

Include additional instruction files:

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

Supports glob patterns.

formatters

Configure code formatters:

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

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 ..." },
    },
  },
}

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-4o": {
          "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"] |

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}",
      },
    },
  },
}

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