---
title: "配置 Agents"
description: "理解 OpenCode 裡的 Build、Plan、Explore、General，以及什麼時候建立自己的 Agent。"
verifiedAt: "2026-05-09"
---

Agent 不是“給模型換幾個角色名”。它真正解決的是邊界：什麼時候可以改檔案，什麼時候只能分析，什麼時候可以把一個獨立問題丟給子任務。

> [!NOTE]
> **這一篇用 8 分鐘換什麼**：看完以後，你應該能判斷該用 `Build`、`Plan`、`Explore` 還是 `General`，並能寫出一個不會亂改檔案的自定義 Agent。

## 先給結論：先用內建 Agent，再自定義

新手最常見的錯誤，是還沒用熟 OpenCode 自帶的 Agent，就先建立一堆“架構師”“審查員”“文件專家”。這通常不會讓工作更清楚，反而會把邊界搞亂。

先記住這個判斷：

| 場景 | 優先用誰 | 原因 |
| --- | --- | --- |
| 實現功能、修 bug、改檔案 | `Build` | 預設動手型主代理 |
| 先看程式碼、評估方案、做 review | `Plan` | 更適合規劃和分析 |
| 查某段邏輯在哪裡 | `Explore` | 只讀探索，適合隔離上下文 |
| 獨立研究、多步驟旁路任務 | `General` | 通用子代理，不干擾主線 |

> [!IMPORTANT]
> Agent 的質量不看名字多專業，而看職責、許可權和輸出是否穩定。一個只讀審查 Agent 預設能改檔案，就是邊界失敗。

## OpenCode 的 Agent 分工模型

OpenCode 裡同時有主代理和子代理。主代理是你正在直接對話的工作模式；子代理是為某個專項任務臨時啟動的隔離上下文。

```mermaid
flowchart LR
  User[你的任務] --> Need{這一步要什麼}
  Need -->|要改程式碼| Build[Build 主代理]
  Need -->|要先想清楚| Plan[Plan 主代理]
  Need -->|只讀找線索| Explore[Explore 子代理]
  Need -->|獨立旁路任務| General[General 子代理]
  Plan --> Build
  Explore --> Build
  General --> Build
```

一個穩妥流程是：先用 `Plan` 理清方案，再切到 `Build` 執行；程式碼庫很大時，用 `Explore` 查結構，把結果帶回主線。

## 主代理和子代理怎麼選

主代理適合承接當前會話的長期工作。OpenCode 裡可以透過 **Tab** 在主代理之間切換。子代理更像臨時請來的專項助手，可以由主代理自動呼叫，也可以用 `@` 指定。

```txt
@explore find where authentication is handled
```

| 型別 | 適合做 | 不適合做 |
| --- | --- | --- |
| 主代理 | 持續規劃、執行、改檔案、承接上下文 | 同時塞進多個互不相關的調查任務 |
| 子代理 | 只讀搜尋、專項 review、獨立研究 | 替代主會話長期推進複雜改動 |

不要把子代理當成“更強模型”。它的價值是隔離任務：讓探索、審查、資料查詢不汙染主會話。

## 什麼時候建立自定義 Agent

只有當某類任務反覆出現，並且需要穩定邊界時，才值得建立自定義 Agent。

| 適合建立 | 暫時別建立 |
| --- | --- |
| 只讀程式碼審查 | 一次性問題 |
| 安全檢查 | 只是想換一個角色名 |
| 文件維護 | 輸出標準還沒想清楚 |
| 資料庫遷移規劃 | 每次都要臨場補很多要求 |
| 固定釋出前檢查 | 和現有內建 Agent 重疊太多 |

如果你每次都要補充“不要改檔案”“只看安全風險”“先列計劃”，這些規則就應該進入 Agent 定義。

## 用 Markdown 定義一個只讀審查 Agent

新手優先用 Markdown 檔案定義 Agent，比把大段 JSON 塞進 `opencode.json` 更清楚。檔名就是 Agent 名，`.opencode/agents/review.md` 對應 `@review`。

```md
---
description: Review code without editing files
mode: subagent
permission:
  edit: deny
  bash: ask
---

Review the current change.
Focus on bugs, security, regressions, and missing tests.
Do not edit files.
```

這個例子裡，真正起邊界作用的是 `permission.edit: deny`。最後一行 `Do not edit files.` 只是意圖說明，不應該承擔安全邊界。

## 配置欄位怎麼判斷

先記住這些欄位就夠了：

| 欄位 | 作用 | 新手判斷 |
| --- | --- | --- |
| `description` | 讓模型判斷什麼時候呼叫它 | 寫具體場景，不寫空泛人格 |
| `mode` | 決定是主代理還是子代理 | 長期工作用 `primary`，專項隔離用 `subagent` |
| `permission` | 限制檔案、命令、網路等能力 | 涉及安全邊界時必須寫 |
| `model` | 指定模型 | 只有任務確實需要不同模型時再指定 |
| `temperature` | 控制隨機性 | 審查、遷移、排障偏低；腦暴可以稍高 |
| `steps` | 限制最多迭代步數 | 用來控制成本和跑偏 |
| `disable` | 停用某個 Agent | 臨時停用比刪除更穩 |
| `prompt` | 指向外部提示詞檔案 | 長提示詞複用時再用 |

> [!WARNING]
> 舊資料裡可能出現 `maxSteps`。現在優先用 `steps` 表達最大迭代步數，避免新舊欄位混用。

## 許可權比提示詞可靠

不要只在提示詞裡寫“不要改檔案”。如果你真的不希望它改檔案，就用許可權限制：

```yaml
permission:
  edit: deny
  bash: ask
```

提示詞是意圖，許可權是邊界。尤其是程式碼審查、安全檢查、釋出前檢查這類任務，許可權要和職責一致。

## 怎麼判斷 Agent 寫對了

一個好 Agent 應該有穩定行為：

- 看到 `description` 就知道什麼時候該用。
- 任務範圍窄，不是什麼都想做。
- 許可權和職責一致：審查 Agent 不應預設能改檔案。
- 輸出結構穩定，例如總是先列風險，再列建議測試。
- 不需要你每次額外解釋一大段背景。

把它跑 2-3 次，如果每次都要臨場補同一句限制，就把限制寫回 Agent。Agent 不是一次性 prompt，而是可複用的工作邊界。

## 新手常見坑

- 建立太多 Agent。數量多不等於效率高，先把常用的 3-5 個打磨穩定。
- `description` 寫得太抽象。模型會根據它判斷是否呼叫，不能只寫 “helpful assistant”。
- 把主代理和子代理混用。長期對話用主代理，專項隔離用子代理。
- 只寫提示詞，不配許可權。涉及檔案修改、命令執行時，許可權才是底線。
- 自定義 Agent 和內建 Agent 重疊。能用 `Plan`、`Build`、`Explore` 解決的，不必先造一個新名字。

## 接下來去哪

<Cards>
  <Card title="配置 Skills" href="/zh-Hant/docs/opencode/official/02-agents-skills/skills">
    學會把可複用能力沉澱成 Skill，而不是每次靠臨時提示詞。
  </Card>
  <Card title="配置 Plugins" href="/zh-Hant/docs/opencode/official/02-agents-skills/plugins">
    理解什麼時候需要外掛，什麼時候內建 Agent 和 Skill 已經夠用。
  </Card>
  <Card title="配置 Rules" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules">
    把專案約束寫成長期規則，讓 Agent 預設按同一套邊界工作。
  </Card>
  <Card title="Agents、Skills、Plugins 怎麼分" href="/zh-Hant/docs/opencode/understanding/05-agents-skills-plugins">
    用更完整的視角理解三者分工，避免把所有問題都塞進 Agent。
  </Card>
</Cards>

## 官方資料

- [OpenCode agents](https://opencode.ai/docs/agents/)
- [OpenCode configuration](https://opencode.ai/docs/config/)
