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

5installs
Sourceigorwarzocha/opencode-workflows
Added on

NPX Install

npx skill4agent add igorwarzocha/opencode-workflows opencode-config

Tags

Translated version includes tags in frontmatter
opencode-configurationagent-permissionsmodel-setupconfig-filesworkflow-guidance

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>
<reference>

File Locations

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

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

Key Options

OptionPurposeExample
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>
<troubleshooting>
IssueSolution
Config not loadingCheck JSON syntax, ensure valid path
Skill not foundVerify 
SKILL.md
(uppercase), check frontmatter
Permission denied unexpectedlyCheck global vs project config precedence
</troubleshooting>

References

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