---
title: "04 · 配置、Rules 与自定义命令"
description: "基于官方 OpenCode Config、Rules、Commands 教程，面向新手讲清配置、规则和命令各自沉淀什么经验。"
verifiedAt: "2026-05-09"
---

OpenCode 的长期价值不在“这次回答得不错”，而在“这次沉淀下来的经验，下次能自动生效”。配置、Rules 和 Commands 就是三种沉淀方式。

这一篇先把三者分清：配置决定 OpenCode 怎么运行，Rules 决定 agent 在项目里应该遵守什么，自定义命令把重复流程变成 `/xxx` 入口。分不清这三者，后面 agents、skills、plugins 会越写越乱。

> [!NOTE]
> **这一篇解决什么问题**：把一次性提示词变成可复用项目资产。读完你应该能判断：某条经验应该写进 `opencode.json`、`AGENTS.md`、`instructions`，还是 `.opencode/commands/`。

## 沉淀层级图

从一次性提示词到运行时扩展，维护成本会逐层上升。先用最低层解决问题。

```mermaid
flowchart LR
  Prompt["一次性提示词"] --> Rules["Rules / AGENTS.md<br/>长期项目约束"]
  Rules --> Config["Config<br/>模型 / 权限 / share / formatter"]
  Rules --> Commands["Commands<br/>重复流程入口"]
  Commands --> Agents["Agents<br/>角色和权限边界"]
  Agents --> Skills["Skills<br/>跨项目流程包"]
  Skills --> Plugins["Plugins / custom tools<br/>运行时或工具扩展"]

  style Rules fill:#dbeafe,stroke:#3b82f6
  style Commands fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Plugins fill:#fee2e2,stroke:#ef4444
```

同一条提醒说了三次，才值得沉淀；沉淀前先判断它是运行策略、长期约束，还是重复流程。

## 1. 三者先分工

先用一句话拆开：

```text
Config      机器怎么运行
Rules       Agent 在这个项目里怎么做事
Commands    重复任务怎么一键触发
```

| 类型 | 解决的问题 | 典型文件 |
| --- | --- | --- |
| Config | 默认模型、provider、permission、MCP、formatter、server、share 怎么配置 | `opencode.json` / `opencode.jsonc` |
| TUI config | 主题、快捷键、滚动、diff 样式等终端界面行为 | `tui.json` / `tui.jsonc` |
| Rules | 项目结构、测试命令、包管理器、目录边界、编码约定 | `AGENTS.md` |
| Instructions | 复用已有规则文件，不重复复制内容 | `opencode.json` 的 `instructions` |
| Commands | review diff、修失败测试、写 release note 这类重复流程 | `.opencode/commands/*.md` |

> [!IMPORTANT]
> **不要混用**：运行参数进 config，长期约束进 rules，重复流程进 commands。把所有东西塞进一个超长 `AGENTS.md`，看似省事，实际会让模型抓不住重点。

## 2. Config 管运行，不管任务

OpenCode 支持 JSON / JSONC 配置。官方文档说明配置会按多个来源合并，后面的配置覆盖前面的冲突项，但非冲突项会保留。

你最常用的配置位置：

| 位置 | 适合放什么 |
| --- | --- |
| `~/.config/opencode/opencode.json` | 个人默认 provider、模型、权限偏好 |
| 项目根目录 `opencode.json` | 项目默认模型、权限、MCP、formatter、share 策略 |
| `.opencode/` | 项目级 agents、commands、plugins、skills、tools、themes |
| `tui.json` | TUI 主题、快捷键、滚动、diff 样式 |

项目级 `opencode.json` 的优先级高于全局配置，适合放团队共识。但不要把 API key、token、cookie 写进去。

一个项目级配置的思路示例：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",

  // 模型号请按官方当前推荐 + `/models` 命令为准，不要把"今天最强"硬编码到团队配置里
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",

  "permission": {
    "*": "ask",
    "read": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "git push*": "deny"
    }
  },
  "share": "manual",
  "instructions": ["CONTRIBUTING.md", "docs/development.md"]
}
```

这段配置的重点不是推荐你原样复制，而是展示分层：模型、权限、分享和额外 instructions 都属于“运行时策略”，不属于某一次任务。具体可用模型号会随 provider 上新和淘汰漂移，团队配置里写一个**当前还在的、稳定可用**的模型即可，但要把"看 [官方 models 页](https://opencode.ai/docs/models)" 这条核验路径写进 README 或 AGENTS.md，让下一个接手的人知道怎么自己更新。

## 3. Rules 不是百科，是项目约束

OpenCode 的 Rules 文档核心是 `AGENTS.md`。你可以用 `/init` 创建或更新它。官方建议把项目级 `AGENTS.md` 提交到 Git，因为它是团队共享的 agent 项目说明。

适合写进 `AGENTS.md` 的内容：

- 项目技术栈和目录结构。
- build、lint、test 命令。
- 包管理器约定，例如只用 `pnpm` 或只用 `bun`。
- 修改前必须阅读的项目文档。
- 禁止修改的目录和文件。
- 错误处理、命名、测试、发布边界。
- 已有 Cursor / Copilot / Claude Code 规则的引用方式。

不适合写进去的内容：

- 一次性任务目标。
- 真实 API key 或内部账号。
- 长篇项目百科。
- 已经过期的历史争论。
- 可以通过文件结构自动看出来的废话。

> [!TIP]
> **判断标准**：如果这条规则未来 10 次任务都应该遵守，写进 `AGENTS.md`；如果只对这一次任务有效，不要污染 Rules。

## 4. AGENTS.md 和 CLAUDE.md 的关系

OpenCode 支持 `AGENTS.md`，也兼容 Claude Code 的 `CLAUDE.md` 约定。官方 Rules 文档说明：

- 项目规则优先读当前目录向上查找的 `AGENTS.md` / `CLAUDE.md`。
- 如果同一位置同时有 `AGENTS.md` 和 `CLAUDE.md`，`AGENTS.md` 优先。
- 全局规则优先使用 `~/.config/opencode/AGENTS.md`，再兼容 `~/.claude/CLAUDE.md`。
- OpenCode 还会兼容 `.claude/skills/` 当成 Skills 来源（详见 05 篇）。

这对从 Claude Code 迁移的人很重要。不要同时维护两份不同规则。更稳的做法是选一个主入口，再让另一个兼容引用或保持一致。

如果你想完全关掉对 Claude Code 文件的兼容，OpenCode 提供了三个环境变量，按需选粒度：

```bash
export OPENCODE_DISABLE_CLAUDE_CODE=1          # 一刀切：禁所有 .claude 兼容
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1   # 只禁 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1   # 只禁 .claude/skills
```

## 5. Instructions 适合复用已有规范

如果项目已经有 `CONTRIBUTING.md`、`docs/development.md`、`.cursor/rules/*.mdc`，不要复制一份到 `AGENTS.md`。OpenCode 支持在 config 里用 `instructions` 引用这些文件：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development-standards.md",
    ".cursor/rules/*.mdc",
    // 也支持 https URL，5 秒超时拉取
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}
```

这样做的好处是减少重复维护，跨项目共享规则也容易（团队公共规则放一个 git 仓库，多项目通过 raw URL 引用）。但引用要克制：不要一次性塞 20 个规则文件。规则越多，模型越容易抓不住真正关键的约束。**远程 URL 引用还要承担拉取失败和被改动的风险**——OpenCode 给的超时是 5 秒，如果远程不可达，那次会话就会少这条规则。

## 6. Commands 把重复流程做成入口

当一个提示词反复用三次以上，就可以考虑做成 command。

官方 Commands 文档支持两种方式：

- 在 `opencode.json` 里写 `command` 配置。
- 创建 markdown command 文件，例如 `.opencode/commands/review-diff.md`。

项目里更推荐 markdown 文件，因为更易读、易 review、易版本化。

```md
---
description: Review current git diff for bugs and regressions
agent: build
---

请审查当前 git diff：

1. 先读取当前 diff，不要修改文件。
2. 优先找 bug、行为回归、安全风险和缺失测试。
3. 输出按严重程度排序。
4. 如果没有问题，明确说没有发现阻断问题。
```

文件名就是命令名：

```text
/review-diff
```

frontmatter 里的 `agent` 字段指向 OpenCode 内置或你自己定义的 agent（如默认 `build` / `plan`，或自定义的 `review` / `security-audit`）。如果不写 `agent` 就沿用当前会话的 agent。详见 05 篇。

Command 的价值不是少打几个字，而是把任务边界、检查顺序和输出格式固定下来。

## 7. Command 参数、文件和 shell 输出

OpenCode command 支持 `$ARGUMENTS`、`$1`、`$2` 这类参数，也支持在 prompt 中引用文件和注入 shell 输出。

例子：

```md
---
description: Explain one module with risks
---

请解释 $ARGUMENTS 这个模块：

1. 先阅读相关入口文件。
2. 说明它解决什么问题。
3. 画出调用链。
4. 列出最可能出错的 3 个点。
```

运行：

```text
/explain-module src/auth
```

再比如把 git diff 注入 command：

```md
---
description: Review current diff
---

当前改动如下：

!`git diff --stat`
!`git diff`

请只做审查，不要修改文件。
```

> [!WARNING]
> **不要在 command 里塞危险 shell**：`!` 会执行命令并把输出注入 prompt。只读命令适合，删除、发布、数据库写操作不适合。

frontmatter 还有两个有用但容易被忽略的选项：

| 选项 | 作用 | 何时用 |
| --- | --- | --- |
| `model` | 单独覆盖默认模型，只对这条 command 生效 | 这条任务需要更强或更便宜的模型，不想动全局默认 |
| `subtask: true` | 强制走 subagent，主对话上下文不被这条 command 的中间过程污染 | command 会读大量文件、跑长流程，不希望污染你正在主线推进的会话 |

例如让一条体量大的代码审查走 subagent + 更强模型：

```md
---
description: Deep audit of recent changes
agent: build
model: anthropic/claude-opus-4-5
subtask: true
---

请深度审查最近 50 个 commit：
...
```

## 8. 推荐沉淀顺序

不要第一天就配置满。更稳的顺序是：

```text
普通提示词
  ↓  同一提醒出现 3 次
AGENTS.md / instructions
  ↓  同一流程出现 3 次
.opencode/commands/*.md
  ↓  需要不同角色和权限
agents
  ↓  跨项目复用能力
skills
  ↓  需要运行时扩展
plugins / custom tools
```

每往下一层，维护成本都更高。OpenCode 的开放配置不是为了堆满所有目录，而是让真实经验逐步沉淀。

## 9. 新手常见坑

| 坑 | 后果 | 更稳做法 |
| --- | --- | --- |
| 把 API key 写进配置 | 泄露凭据 | 用 `/connect`、auth、环境变量或 secret manager |
| `AGENTS.md` 写成百科 | 模型抓不住重点 | 只写稳定约束、命令和边界 |
| command 写成万能 prompt | 每次执行仍然发散 | 一个 command 只做一类任务 |
| 一次性任务写进 rules | 后续任务被污染 | 临时目标留在对话里 |
| 只写 rules，不配 permissions | 误以为安全边界已生效 | 规则和权限分别治理 |
| 项目配置没人 review | 团队行为不一致 | 配置文件按代码一样 review |

## 10. 怎么验收

你可以用 5 个问题检查这一层是否过关：

- 每一条 `AGENTS.md` 规则是否未来多次任务都需要？
- 项目配置里是否没有真实密钥？
- 能否用一个 command 稳定完成重复任务？
- 规则、配置、命令是否各司其职，没有互相污染？
- 删除某条 rule 或 command 时，是否知道会影响哪些流程？

> [!TIP]
> **过关标准**：你能解释清楚每条配置、每条 rule、每个 command 为什么存在，以及它们分别影响 OpenCode 的哪一层行为。

## 接下来去哪

<Cards>
  <Card title="配置 OpenCode" description="把模型、permission、formatter、server、share 等运行策略放到正确配置层。" href="/docs/opencode/official/01-customization/config" />
  <Card title="编写 Rules" description="把未来多次任务都要遵守的项目约束写进 `AGENTS.md`。" href="/docs/opencode/official/02-agents-skills/rules" />
  <Card title="创建自定义命令" description="把重复流程沉淀成 `/xxx` 入口，固定任务边界和输出结构。" href="/docs/opencode/official/01-customization/commands" />
  <Card title="Agents、Skills 与 Plugins" description="当 rules 和 commands 不够时，再进入角色、流程包和运行时扩展。" href="/docs/opencode/understanding/05-agents-skills-plugins" />
</Cards>

## 官方资料

- Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- Rules：[https://opencode.ai/docs/rules](https://opencode.ai/docs/rules)
- Commands：[https://opencode.ai/docs/commands](https://opencode.ai/docs/commands)
- Permissions：[https://opencode.ai/docs/permissions](https://opencode.ai/docs/permissions)
