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>

通过引导用户完成配置文件和规则的设置，帮助用户配置OpenCode。

<question_tool>

**批量规则：**仅用于2个及以上相关问题；单个问题请使用纯文本。

**语法约束：**标题最多12个字符，标签为1-5个词，默认选项标记为

(推荐)

。

**用途：**明确配置范围（模型/权限/规则）、验证配置方案并处理多种有效选项。

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

类型	全局路径	项目路径
配置文件	`~/.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:

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

询问用户想要配置的内容：

“你想要设置什么内容？”
- 配置文件（模型、工具、权限、主题）
- 规则（通过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

关键选项

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

选项	用途	示例
`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>

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>

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>

问题	解决方案
配置未加载	检查JSON语法，确保路径正确
未找到Skill	验证 `SKILL.md` 文件（需大写），检查文件头
意外出现权限拒绝	检查全局与项目配置的优先级

</troubleshooting>

References

参考资料

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

```
references/config-schema.md
```
- 完整配置选项