Basic Configuration with opencode.json

Beginner⏱45 min📖2 min readLesson 5 of 5

Basic Configuration with opencode.json

Configure OpenCode using opencode.json. Learn the configuration schema, agents, providers, permissions, and how to customize behavior for your projects.

Configuration File Locations

OpenCode searches for configuration in this order:

Priority	Location	Purpose
1	`.opencode/config.json`	Project-specific (preferred)
2	`opencode.json`	Project-specific (legacy)
3	`~/.config/opencode/config.json`	User-wide defaults

💡Tip

For new projects, use .opencode/config.json. The root opencode.json is kept for backward compatibility.

Basic Configuration Structure

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {},
  "providers": {},
  "permissions": [],
  "skills": {}
}

Configuring Agents

Agents are AI assistants with specific models and behaviors.

Simple Agent

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "General-purpose coding assistant"
    }
  }
}

Multiple Agents

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "General-purpose coding assistant"
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Code review specialist"
    },
    "fast": {
      "model": "gpt-4o-mini",
      "description": "Quick tasks and simple questions"
    }
  }
}

Agent with Custom Prompt

json

{
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Senior software engineer",
      "prompt": "You are a senior software engineer with 10+ years of experience. Focus on clean, maintainable code. Always consider edge cases and error handling."
    }
  }
}

Configuring Providers

Providers define how OpenCode connects to LLM services.

OpenAI

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "gpt-4o"
    }
  }
}

Anthropic

json

{
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Multiple Providers

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "google": {
      "apiKey": "${GOOGLE_API_KEY}"
    }
  }
}

Configuring Permissions

Permissions control what actions agents can perform.

Basic Permissions

json

{
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pip *"],
      "deny": ["rm -rf /", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "docs/**"],
      "deny": [".env", "secrets/**"]
    }
  ]
}

Permission Rules

Rule	Description
`tool`	The tool to control
`allow`	Patterns that are permitted
`deny`	Patterns that are blocked
Order	Deny rules are checked first

Configuring Skills

Skills are reusable instruction packages.

json

{
  "skills": {
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx"
    },
    "python-helper": {
      "manifest": "skills/python-helper/skill.yaml",
      "autoLoad": false
    }
  }
}

Option	Description
`manifest`	Path to skill manifest file
`autoLoad`	Load automatically when pattern matches
`matchPattern`	Regex pattern to trigger auto-load

Configuring MCP Servers

MCP servers connect OpenCode to external tools and services.

json

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["mcp-server-fs.js"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects"
      }
    },
    "database": {
      "command": "python",
      "args": ["mcp-server-db.py"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Complete Example

Here's a complete opencode.json for a typical project:

json

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "default": {
      "model": "gpt-4o",
      "description": "Primary coding assistant",
      "prompt": "You are a senior developer. Focus on clean, testable code."
    },
    "reviewer": {
      "model": "claude-sonnet-4-20250514",
      "description": "Code review specialist"
    }
  },
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    },
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *", "pytest *"],
      "deny": ["rm -rf *", "sudo *"]
    },
    {
      "tool": "write",
      "allow": ["src/**", "tests/**", "docs/**"],
      "deny": [".env", "secrets/**", "*.key"]
    }
  ],
  "skills": {
    "customize-opencode": {
      "manifest": ".opencode/skills/customize-opencode/skill.yaml"
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Validation

OpenCode validates your configuration on startup. Common errors:

Error	Cause	Solution
"Invalid JSON"	Syntax error	Check JSON formatting
"Unknown provider"	Unsupported provider	Check provider documentation
"Invalid model"	Wrong model name	Verify model exists
"Permission conflict"	Overlapping rules	Review permission order

Environment Variable Substitution

Use ${VARIABLE_NAME} to reference environment variables:

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}

This keeps sensitive data out of your configuration files.