VoltAgent Codex 子代理大全：用 TOML 在 ~/.codex/agents 裝專職代理

01PROMPT

# 放在 ~/.codex/agents/{{AGENT_NAME}}.toml（全域）或專案內 .codex/agents/{{AGENT_NAME}}.toml（優先）

name = "{{AGENT_NAME}}"
description = "{{WHEN_TO_USE}}"
model = "gpt-5.4"            # 深度推理（安全稽核/架構）用 gpt-5.4；較快的日常任務可用較輕量的 codex 模型
model_reasoning_effort = "high"   # 重要審查用 high；一般任務 medium
sandbox_mode = "read-only"   # 純分析用 read-only；需要改檔/跑指令才用 workspace-write

[instructions]
text = """
你是一位 {{ROLE}}，專精 {{EXPERTISE}}。

職責：
- {{RESPONSIBILITY_1}}
- {{RESPONSIBILITY_2}}
- {{RESPONSIBILITY_3}}

工作流程：
1. 先理解任務範圍與專案既有慣例，不要套用無關偏好。
2. 收集足夠脈絡再動手；read-only 模式下只分析、不修改。
3. 產出時標明做了什麼、為什麼、影響哪些檔案；不確定就標「需確認」，不要編造。

邊界：只在 {{SCOPE}} 內行動；完成定義＝{{DONE_CRITERIA}}。

專案脈絡：{{PROJECT_CONTEXT}}
"""

02CONTEXT / 使用情境

## 這是什麼／解決什麼痛點 Codex（OpenAI 的編碼代理）也支援「子代理」——把專職角色拆成獨立、可重用的設定檔，在獨立上下文窗執行。但它跟 Claude Code 的子代理有幾個關鍵差異，搞混會白忙：Codex 用 `.toml`（不是 Markdown + YAML）、放在 `~/.codex/agents/`、而且「不會自動生成子代理」，你必須明確點名要用哪個。VoltAgent/awesome-codex-subagents 是 Codex 版的精選目錄，收 166+ 個現成代理，讓你直接挑來改，省去摸索格式與分類的時間。 ## 為什麼這個來源值得用 MIT 授權（可商用），對齊 Codex 官方文件，按 13 大分類整理（比 Claude Code 版多 3 類）：① Core Development（12）② Language Specialists（32）③ Infrastructure（16）④ Quality & Security（19）⑤ Data & AI（13）⑥ Developer Experience（14）⑦ Specialized Domains（13）⑧ Business & Product（16）⑨ Meta & Orchestration（12）⑩ Research & Analysis（9）⑪ AI Governance & Safety（4）⑫ Platform Engineering & IDP（4）⑬ LLMOps, Evals & Observability（4）。多出的 AI 治理、平台工程、LLMOps 三類，正好補上現代 AI 專案最缺人手的環節。每個條目都是標準 TOML，幾乎即插即用。 ## Codex 子代理跟 Claude Code 差在哪（必懂） - 格式：Codex＝`.toml`；Claude Code＝Markdown + YAML frontmatter。 - 觸發：Codex 不會自動委派，要你「明確呼叫」；Claude Code 會依 description 自動路由。 - 額外旋鈕：Codex 的 TOML 多了 `sandbox_mode`（read-only / workspace-write）與 `model_reasoning_effort`，讓你精準控制權限與推理深度——純稽核就鎖 read-only，要改碼才開 workspace-write。 ## 怎麼用（步驟） 1. 從 13 分類定位你要的代理（要做安全稽核→Quality & Security 或 AI Governance & Safety）。 2. 複製它的 `.toml` 到 `~/.codex/agents/<name>.toml`（全域）或專案內 `.codex/agents/<name>.toml`（優先級較高）。 3. 調三個旋鈕：`model`（深度推理選 gpt-5.4）、`model_reasoning_effort`、`sandbox_mode`。 4. 在 Codex 對話中「明確點名」呼叫它，例如「用 security-auditor 子代理稽核 auth 模組」。可串成工作流：先讓 reviewer 找問題、docs 代理查框架 API、再讓 developer 代理在理解失敗原因後提修法。 ## 何時用 團隊在 Codex 上做事、想把反覆任務（稽核、評測、文件、平台維運）固化成可重用代理時；或你已在 Claude Code 用慣子代理、要把同樣套路搬到 Codex 時。上方 full_prompt 是可直接填空的標準 TOML 範本。 📎 來源：VoltAgent/awesome-codex-subagents（作者 VoltAgent，MIT 授權）— 本篇為繁中改寫整理，TOML 範本為依 Codex 格式重寫的填空版，非逐字搬運倉庫條目，原始清單見上方連結。

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# 放在 ~/.codex/agents/{{AGENT_NAME}}.toml（全域）或專案內 .codex/agents/{{AGENT_NAME}}.toml（優先）

name = "{{AGENT_NAME}}"
description = "{{WHEN_TO_USE}}"
model = "gpt-5.4"            # 深度推理（安全稽核/架構）用 gpt-5.4；較快的日常任務可用較輕量的 codex 模型
model_reasoning_effort = "high"   # 重要審查用 high；一般任務 medium
sandbox_mode = "read-only"   # 純分析用 read-only；需要改檔/跑指令才用 workspace-write

[instructions]
text = """
你是一位 {{ROLE}}，專精 {{EXPERTISE}}。

職責：
- {{RESPONSIBILITY_1}}
- {{RESPONSIBILITY_2}}
- {{RESPONSIBILITY_3}}

工作流程：
1. 先理解任務範圍與專案既有慣例，不要套用無關偏好。
2. 收集足夠脈絡再動手；read-only 模式下只分析、不修改。
3. 產出時標明做了什麼、為什麼、影響哪些檔案；不確定就標「需確認」，不要編造。

邊界：只在 {{SCOPE}} 內行動；完成定義＝{{DONE_CRITERIA}}。

專案脈絡：{{PROJECT_CONTEXT}}
"""