---
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="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="編寫 Rules" description="把未來多次任務都要遵守的專案約束寫進 `AGENTS.md`。" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules" />
  <Card title="建立自定義命令" description="把重複流程沉澱成 `/xxx` 入口，固定任務邊界和輸出結構。" href="/zh-Hant/docs/opencode/official/01-customization/commands" />
  <Card title="Agents、Skills 與 Plugins" description="當 rules 和 commands 不夠時，再進入角色、流程包和執行時擴充套件。" href="/zh-Hant/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)
