OpenCode Guide
Navigate: Menu

Introduction

Oh My OpenCode

Getting Started

Guides & Integrations

Reference

Comparisons

Agent Configuration

This page documents all supported agent configuration options in OpenCode.
Agent configuration controls:
  • Tool availability
  • Skill access
  • Permission boundaries
  • Agent-specific overrides
This is a reference page. For conceptual guidance, see:

Configuration locations

Agent configuration can appear in two places:

1. Built-in agents

Configured in opencode.json:
{
  "agent": {
    "<agent-name>": {
      // agent configuration
    }
  }
}

2. Custom agents

Defined using YAML frontmatter in agent files:
---
# agent configuration
---

permission

Controls what an agent is allowed to access.

Schema

permission:
  <resource-type>:
    <pattern>: allow | deny | ask

Supported resource types

ResourceDescription
skillAgent skills
toolTools (including MCP tools)
Unknown resource types are ignored.

Patterns

Patterns are matched by name and support wildcards.
PatternMatches
*All resources
internal-*internal-docs, internal-tools
review-*review-code, review-security

Values

ValueBehavior
allowResource is immediately available
denyResource is hidden and inaccessible
askUser approval required before access

Example

permission:
  skill:
    "*": allow
    "internal-*": deny
  tool:
    "browser": ask

tools

Enables or disables tools for the agent.

Schema

tools:
  <tool-name>: true | false
If a tool is set to false, it is completely disabled and hidden.

Example

tools:
  skill: true
  browser: false

Overrides and precedence

Configuration is merged in the following order (lowest → highest priority):
  1. Global configuration
  2. Built-in agent configuration
  3. Custom agent configuration
Higher-priority settings override lower ones.

Built-in agent override example

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      },
      "tools": {
        "skill": true
      }
    }
  }
}

Custom agent example

---
permission:
  skill:
    "documents-*": allow
    "experimental-*": ask
tools:
  skill: true
---

Disable all skills for an agent

To prevent an agent from using skills entirely:
tools:
  skill: false
When disabled, skills are omitted from the agent’s tool list.

Notes and constraints

  • Permission patterns are evaluated per resource type
  • deny always hides a resource
  • Tool disablement overrides permission rules
  • Unknown fields are ignored
  • Invalid patterns are skipped silently

Related references