！ 本篇文章將會介紹 opencode 的自訂 agents，primary、subagent 到 permissions，組一支各有專長的小隊 :D

TL;DR: https://dev.benben.me/slides/s/ironman-11-custom-agents

本篇目標

讀完這篇你會學到：

• 了解 agent 的定義檔結構（markdown + front-matter）
• 會建立 primary agent（自己切換）與 subagent（被呼叫的專家）
• 會幫 agent 綁 model、用 permissions 限制能力範圍

Agent 是什麼：一份說明書 + 一組能力上限

還記得 Day 05 的 Build 和 Plan 嗎？它們其實就是 opencode 內建的兩個 agent。一個 agent 本質上就是：

一份系統提示（這個角色怎麼想事情）+ 一組能力限制（它能做什麼、不能做什麼）

opencode 內建的有：

另外還有三個隱藏的系統 agent（compaction、title、summary），它們在背景自動做事，不會出現在選單裡。

Primary 與 subagent 的差別：

• Primary agent：你直接對話的主力，用 Tab 鍵循環切換
• Subagent：被 primary 呼叫的專家（自動派遣），你也可以在訊息裡 @general 手動點名

你知道嗎？subagent 沒指定 model 時，會直接沿用「呼叫它的那個 primary agent」的 model。所以幫 subagent 綁便宜 model 是真的省錢，不是都市傳說。

建立自己的 Agent：一個 .md 檔就搞定

存放位置

• 專案層：.opencode/agents/
• 全域層：~/.config/opencode/agents/

檔名就是 agent 名稱：review.md 會建立一個叫 review 的 agent。

實作一：code reviewer subagent

---
description: Reviews code for quality and best practices
mode: subagent
model: opencode-go/glm-5.3-flash
temperature: 0.1
permission:
  edit: deny
  bash:
    '*': ask
    'git diff': allow
    'git log*': allow
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Security considerations

Provide constructive feedback without making direct changes.

四個重點欄位：

• description：必填。告訴 AI「什麼時候該找這個專家」——自動派遣就是靠這句話判斷的
• mode：primary / subagent / all（沒寫預設 all）
• model：綁定特定 model，格式 provider/model-id。這裡用 GLM 5.3 Flash 這種便宜快速的模型，review 這種例行工作綽綽有餘
• permission：能力邊界。edit: deny 讓它只能出一張嘴——正好是 reviewer 該有的教養

bash 可以寫 glob 細部控制：上面的例子是「全部 bash 先問，但 git diff 和 git log 直接放行」。規則由上往下比對，越後面寫的越優先。

實作二：翻譯 primary agent

---
description: 將文件翻譯成流暢的繁體中文
mode: primary
model: opencode-go/glm-5.3-flash
temperature: 0.3
permission:
  bash: deny
---

你是專業技術譯者。翻譯時保留專有名詞與 code block 原文，
語氣自然，不要逐字直譯。

放進全域目錄後，按 Tab 就能切到它。翻譯不需要動檔案，bash: deny 直接關掉，安全又省心。

實作三：直接請 Opencode 幫你產

不想手寫 front-matter？官方也有懶人法：

opencode agent create

它會問你要存全域還是專案、這個 agent 做什麼，然後幫你生成 system prompt，最後讓你勾選 permissions——沒勾到的全部會被 deny，安全預設給好給滿。

進階調校

• steps：限制 agent 最多迭代幾輪（防暴衝、控成本；舊寫法 maxSteps 已 deprecated）
• temperature：0.0–0.2 適合分析與規劃、0.3–0.5 一般開發、0.6 以上適合腦力激盪
• hidden: true：把 subagent 藏起來，只讓其他 agent 程式化呼叫（@ 選單看不到）
• permission.task：限制這個 agent 能派遣哪些 subagent，一樣吃 glob
• color：給 agent 一個主題色，介面上好認

另外提醒：front-matter 裡其他你多寫的欄位會直接透傳給 provider當 model 參數，例如 OpenAI 的 reasoningEffort。等 Day 20 講多模型時會再用到這招。

常見問題

Q：舊文件裡的 tools: { write: false } 還能用嗎？
A：tools 已被官方列為 deprecated，新設定請改用 permission（更細、支援 glob）。看到舊範例直接自動在腦內翻譯就好。

Q：subagent 可以指定只能被某些 agent 呼叫嗎？
A：可以，在 primary agent 身上設 permission.task，例如 "*": "deny、"review-*": "allow"。不過使用者自己 @ 點名永遠可以，這是設計不是 bug。

Q：要怎麼看目前有哪些 agent？
A：opencode agent list，或 TUI 裡 @ 打開自動完成選單看一輪。

小結

• Agent = 系統提示 + 能力上限；description 決定自動派遣時機
• .opencode/agents/*.md，front-matter 設 mode / model / permission
• Primary 用 Tab 切換、subagent 用 @ 點名或讓 AI 自動派遣
• 幫例行工作綁便宜 model，是最直接的省錢手段
• 最後最後再補充一下：其實原廠的 Build / Plan 兩個就很好用了，實在不需要開太多 agent，少而精才是王道。

明日預告

Day 12：Rules 撰寫心法——AGENTS.md 的進階配置，規則要寫多少才剛好？

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/P3C5U6 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D