Back to Details

opencode-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenCode Configuration

OpenCode配置

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>
通过引导用户完成配置文件和规则的设置，帮助用户配置OpenCode。
<question_tool>
**批量规则：**仅用于2个及以上相关问题；单个问题请使用纯文本。
**语法约束：**标题最多12个字符，标签为1-5个词，默认选项标记为
(推荐)
。
**用途：**明确配置范围（模型/权限/规则）、验证配置方案并处理多种有效选项。
</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>
类型全局路径项目路径
配置文件
~/.config/opencode/opencode.json
./opencode.json
规则文件
~/.config/opencode/AGENTS.md
./AGENTS.md
**优先级：**项目级配置 > 全局级配置。配置会进行合并，而非替换。
</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.
**批量处理：**针对2个及以上相关问题使用
question
工具。单个问题直接使用纯文本。
语法：
header
长度≤12字符，
label
为1-5个词，默认选项添加“(推荐)”标记。
**何时使用：**当用户请求模糊（如“配置OpenCode”）、涉及权限/安全变更，或存在多种有效配置选项时。

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>
询问用户想要配置的内容：
  1. “你想要设置什么内容？”
    • 配置文件（模型、工具、权限、主题）
    • 规则（通过AGENTS.md设置项目说明）
</workflow>
<config_file>

Config File (opencode.json)

配置文件（opencode.json）

Basic Setup

基础设置

jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "theme": "opencode",
  "autoupdate": true
}
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"
选项用途示例
model
默认模型
"anthropic/claude-sonnet-4-20250514"
small_model
轻量任务模型
"anthropic/claude-3-5-haiku-20241022"
theme
UI主题
"opencode"
, 
"catppuccin"
, 
"dracula"
autoupdate
自动更新OpenCode
true
/ 
false
share
会话共享
"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"
    }
  }
}
使用
permission
字段控制需要审批的操作。
jsonc
{
  "permission": {
    "edit": "allow",           // "allow" | "ask" | "deny"
    "bash": {
      "npm *": "allow",        // 模式匹配
      "git *": "allow",
      "rm *": "ask",
      "*": "ask"               // 该工具的默认规则
    },
    "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.
Agent偶尔会处理使用过时配置字段（如
tools
、
maxSteps
）的遗留项目。遇到此类情况，必须将其修正为现代的
permission
和
steps
字段。

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>
添加额外的指令文件：
jsonc
{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}
**完整Schema参考：**请查看
references/config-schema.md
</config_file>
<rules_file>

Rules (AGENTS.md)

规则文件（AGENTS.md）

Project instructions for all agents. Similar to CLAUDE.md or Cursor rules.
所有Agent的项目说明文件，与CLAUDE.md或Cursor规则类似。

Create with /init

通过/init命令创建

Run 
/init
in OpenCode to auto-generate based on project analysis.
在OpenCode中运行
/init
命令，基于项目分析自动生成该文件。

Manual Creation

手动创建

markdown
undefined
markdown
undefined

Project Name

项目名称

This is a [framework] project using [language].
这是一个基于[框架]的[语言]项目。

Project Structure

项目结构

  • src/
    - Source code
  • tests/
    - Test files
  • src/
    - 源代码目录
  • tests/
    - 测试文件目录

Code Standards

代码规范

  • Use TypeScript strict mode
  • Prefer functional patterns
  • Write tests for all features
  • 使用TypeScript严格模式
  • 优先使用函数式编程模式
  • 为所有功能编写测试用例

Commands

常用命令

  • npm run build
    - Build project
  • npm test
    - Run tests
undefined
  • npm run build
    - 构建项目
  • npm test
    - 运行测试
undefined

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>
  • 应明确说明项目的编程模式
  • 应包含常用命令
  • 应记录所有非显而易见的约定
  • 应保持简洁（Agent的上下文处理能力有限）
</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.
OpenCode支持JSONC（带注释的JSON）。应注释掉未使用的配置而非直接删除：
jsonc
{
  "plugin": [
    "opencode-openai-codex-auth@latest",
    //"@tarquinen/opencode-dcp@latest",     // 暂时禁用
    //"@howaboua/pickle-thinker@0.4.0",     // 仅适用于GLM-4.6
    "@ramtinj95/opencode-tokenscope@latest"
  ]
}
**原因：**后续可能需要重新启用该配置，同时也能记录你尝试过的配置内容。

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>
编辑opencode.json后，你必须运行以下验证命令（而非仅建议用户执行）：
bash
opencode run "test"
请自行执行该命令（使用Bash工具），再告知用户配置变更已完成。
如果配置存在问题，你会看到包含行号的明确错误信息：
Error: Config file at ~/.config/opencode/opencode.json is not valid JSON(C):
--- Errors ---
CommaExpected at line 464, column 5
   Line 464:     "explore": {
              ^
--- End ---
常见JSONC错误：
  • 对象后缺少逗号（尤其是添加新配置段后）
  • }
    前存在多余逗号
  • 未闭合的括号
</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"
  }
}
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"]
}
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>
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>
问题解决方案
配置未加载检查JSON语法，确保路径正确
未找到Skill验证
SKILL.md
文件（需大写），检查文件头
意外出现权限拒绝检查全局与项目配置的优先级
</troubleshooting>

References

参考资料

  • references/config-schema.md
    - Full config options
  • references/config-schema.md
    - 完整配置选项