配置 Agents

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

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

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

先記住這個判斷：

OpenCode 的 Agent 分工模型

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

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 在主代理之間切換。子代理更像臨時請來的專項助手，可以由主代理自動呼叫，也可以用 @ 指定。

@explore find where authentication is handled

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

什麼時候建立自定義 Agent

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

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

用 Markdown 定義一個只讀審查 Agent

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

---
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. 只是意圖說明，不應該承擔安全邊界。

配置欄位怎麼判斷

先記住這些欄位就夠了：

許可權比提示詞可靠

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

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 解決的，不必先造一個新名字。

接下來去哪

官方資料

• OpenCode agents
• OpenCode configuration