VoltAgent Codex Subagent Directory: Installing Specialist Agents via TOML in ~/.codex/agents

## What This Is / What Problem It Solves Codex (OpenAI's coding agent) also supports 'subagents' — specialist roles split into independent, reusable config files that run in an isolated context window. But it differs from Claude Code's subagents in a few key ways that will waste your time if you mix them up: Codex uses `.toml` (not Markdown + YAML), files live in `~/.codex/agents/`, and Codex will not auto-delegate to a subagent — you must explicitly name the one you want to use. VoltAgent/awesome-codex-subagents is the Codex-equivalent curated directory, containing 166+ ready-made agents you can pick and customize directly, saving you the time of figuring out the format and categories yourself. ## Why This Source Is Worth Using It's MIT-licensed (commercial use allowed), aligned with Codex's official documentation, and organized into 13 major categories (3 more than the Claude Code version): (1) Core Development (12) (2) Language Specialists (32) (3) Infrastructure (16) (4) Quality & Security (19) (5) Data & AI (13) (6) Developer Experience (14) (7) Specialized Domains (13) (8) Business & Product (16) (9) Meta & Orchestration (12) (10) Research & Analysis (9) (11) AI Governance & Safety (4) (12) Platform Engineering & IDP (4) (13) LLMOps, Evals & Observability (4). The three extra categories — AI governance, platform engineering, and LLMOps — fill exactly the roles modern AI projects are shortest-staffed on. Every entry is standard TOML, making it nearly plug-and-play. ## How Codex Subagents Differ from Claude Code's (Must Know) - Format: Codex uses `.toml`; Claude Code uses Markdown + YAML frontmatter. - Triggering: Codex never auto-delegates — you must explicitly invoke it; Claude Code auto-routes based on the description. - Extra controls: Codex's TOML adds `sandbox_mode` (read-only / workspace-write) and `model_reasoning_effort`, letting you precisely control permissions and reasoning depth — lock to read-only for pure audits, and only open workspace-write when actually modifying code. ## How to Use It (Steps) 1. Locate the agent you need from the 13 categories (security audit -> Quality & Security or AI Governance & Safety). 2. Copy its `.toml` to `~/.codex/agents/<name>.toml` (global) or into the project's `.codex/agents/<name>.toml` (higher priority). 3. Adjust three controls: `model` (choose gpt-5.4 for deep reasoning), `model_reasoning_effort`, and `sandbox_mode`. 4. Invoke it by explicitly naming it in your Codex conversation, e.g., 'use the security-auditor subagent to audit the auth module.' You can chain them into a workflow: have a reviewer agent find issues, a docs agent look up framework APIs, then a developer agent propose a fix once it understands the root cause. ## When to Use It When your team works in Codex and wants to turn recurring tasks (audits, evaluations, documentation, platform ops) into reusable agents; or when you're already used to subagents in Claude Code and want to port the same approach to Codex. The full_prompt above is a fill-in-the-blank standard TOML template. 📎 Source: VoltAgent/awesome-codex-subagents (by VoltAgent, MIT license) — this article is a Traditional Chinese adaptation; the TOML template is a fill-in-the-blank version rewritten to match Codex's format, not a verbatim copy of repository entries. See the link above for the original list.

填下面的欄位，上方 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}}
"""