opencode-config

Original：🇺🇸 English

Translated

Edit opencode.json, AGENTS.md, and config files. Use proactively for provider setup, permission changes, model config, formatter rules, or environment variables. Examples: - user: "Add Anthropic as a provider" → edit opencode.json providers, add API key baseEnv var, verify with opencode run test - user: "Restrict this agent's permissions" → add permission block to agent config, set deny/allow for tools/fileAccess - user: "Set GPT-5 as default model" → edit global or agent-level model preference, verify model name format - user: "Disable gofmt formatter" → edit formatters section, set languages.gofmt.enabled = false

2installs

Sourceigorwarzocha/opencode-workflows

Added on2026-02-10

NPX Install

npx skill4agent add igorwarzocha/opencode-workflows opencode-config

SKILL.md Content

View Translation Comparison →

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>

File Locations

Type	Global	Project
Config	`~/.config/opencode/opencode.json`	`./opencode.json`
Rules	`~/.config/opencode/AGENTS.md`	`./AGENTS.md`

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:

"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

jsonc

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

Key Options

Option	Purpose	Example
`model`	Default model	`"anthropic/claude-sonnet-4-20250514"`
`small_model`	Lightweight tasks	`"anthropic/claude-3-5-haiku-20241022"`
`theme`	UI theme	`"opencode"` , `"catppuccin"` , `"dracula"`
`autoupdate`	Auto-update OpenCode	`true` / `false`
`share`	Session sharing	`"manual"` / `"auto"` / `"disabled"`

Permissions

Control what requires approval using the

permission

field.

jsonc

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

jsonc

{
  "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

markdown

# 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:

jsonc

{
  "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):

bash

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

jsonc

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

Power User Config

jsonc

{
  "$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

jsonc

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

</common_configurations>

Issue	Solution
Config not loading	Check JSON syntax, ensure valid path
Skill not found	Verify `SKILL.md` (uppercase), check frontmatter
Permission denied unexpectedly	Check global vs project config precedence

</troubleshooting>

References

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

opencode-config

NPX Install

Tags

SKILL.md Content

OpenCode Configuration

File Locations

Question Tool

Workflow

Config File (opencode.json)

Basic Setup

Key Options

Permissions

Legacy Configuration

Custom Instructions

Rules (AGENTS.md)

Create with /init

Manual Creation

Tips

Comment Out, Don't Delete

Validate After Major Changes

Minimal Safe Config

Power User Config

Team Project Config

References