opencode-config

OpenCode 配置

通过引导用户设置配置文件和规则，帮助他们配置 OpenCode。

<question_tool>

批处理规则： 仅对 2 个或更多相关问题使用；单个问题使用纯文本。

语法限制： 标题最多 12 个字符，标签为 1-5 个词，默认选项标记为 (Recommended)。

目的： 明确配置范围（模型/权限/规则）、验证方案，并处理多个有效选项。

</question_tool>

文件位置

类型	全局	项目
配置	~/.config/opencode/opencode.json	./opencode.json
规则	~/.config/opencode/AGENTS.md	./AGENTS.md

优先级： 项目 > 全局。配置会合并，而不是替换。

问题工具

批处理： 对 2 个或更多相关问题使用 question 工具。单个问题 → 纯文本。

语法： header ≤12 个字符，label 为 1-5 个词，默认选项添加 "(Recommended)"。

何时提问：请求含糊（“配置 opencode”）、涉及权限/安全更改，或存在多个有效选项时。

工作流

询问用户想要配置什么：

1. “你想设置什么？”
   • 配置文件（模型、工具、权限、主题）
   • 规则（通过 AGENTS.md 设置项目指令）

然后引导他们查看下面的相关部分。

<config_file>

配置文件（opencode.json）

基本设置

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

关键选项

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

权限

使用 permission 字段控制哪些操作需要审批。

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

旧版配置

Agent 有时可能会处理使用过时配置字段（例如 tools、maxSteps）的旧版项目。遇到这些字段时，MUST 将其更正为现代的 permission 和 steps 字段。

自定义指令

添加其他指令文件：

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

完整架构参考： 请参阅 references/config-schema.md

</config_file>

<rules_file>

规则（AGENTS.md）

适用于所有 Agent 的项目指令。类似于 CLAUDE.md 或 Cursor 规则。

使用 /init 创建

在 OpenCode 中运行 /init，根据项目分析自动生成。

手动创建

# 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

提示

• SHOULD 明确说明项目的模式
• SHOULD 包含常用命令
• SHOULD 记录任何不明显的约定
• SHOULD 保持简洁（Agent 的上下文有限）

</rules_file>

<config_tips>

注释掉，不要删除

OpenCode 支持 JSONC（带注释的 JSON）。SHOULD 注释掉未使用的配置，而不是删除：

{
  "plugin": [
    "opencode-openai-codex-auth@latest",
    //"@tarquinen/opencode-dcp@latest",     // disabled for now
    //"@howaboua/[email protected]",     // only for GLM-4.6
    "@ramtinj95/opencode-tokenscope@latest"
  ]
}

原因： 你可能之后想重新启用。这样也能保留尝试过的配置记录。

重大更改后进行验证

编辑 opencode.json 后，MUST 运行以下验证（不能只建议用户运行）：

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>

最简安全配置

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

高级用户配置

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

团队项目配置

{
  "$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（大写），检查 frontmatter
意外出现权限被拒	检查全局配置与项目配置的优先级

参考资料

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