它到底是什么

--agents 是 Claude Code CLI 的启动 flag，用于在启动时以 JSON 形式动态定义自定义 subagent。这些定义只在当次会话中生效，不会写入磁盘，适合快速测试或脚本化自动化场景。

接受两种输入：

• 一个内联 JSON 字符串（交互模式和非交互模式均可）
• 一个 JSON 文件路径（仅限配合 --print/-p 非交互模式，需要 v2.1.281 及以上版本）

JSON 中每个顶层 key 是一个 agent 的名字，value 是该 agent 的定义对象。定义对象里的字段与文件形式 subagent（.claude/agents/*.md）的 frontmatter 字段基本一致，用 prompt 字段代替 Markdown 正文来充当系统提示词。

用法

# macOS / Linux / WSL,内联 JSON
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

# Windows PowerShell,需用 here-string
claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}
'@

# 非交互模式 + JSON 文件路径(v2.1.281+)
claude -p --agents ./agents.json "Review my changes"

支持字段（除 description 外均为可选）：

唯一必需的字段是 description，其余字段均为可选，prompt 可以留空。

与其他 flag 的组合 / 互斥

• 交互模式下 --agents 只接受 JSON 对象，不接受文件路径。
• 只有搭配 --print（或 -p）时，--agents 才可以接受 JSON 文件路径，否则会报 --agents takes a JSON object, or a file path only with --print (-p)。
• 可与其他会话配置 flag 一起使用。

在 settings.json / env 的等价配置

--agents 定义的 subagent 是会话级、不落盘的。若想让 agent 定义持久化、跨会话复用，等价的落盘方式是把同样的字段写成 frontmatter，放到 .claude/agents/<name>.md（项目级）或 ~/.claude/agents/<name>.md（用户级）。

运行约束 / 限制

优先级（与其他 subagent 来源的关系）

当同名 subagent 出现在多个来源时，按以下优先级从高到低取用：

也就是说，--agents 定义的 agent 会覆盖项目级和用户级的同名 subagent，但会被 managed settings 中的同名定义覆盖。

常见坑

• JSON 格式错误会导致直接退出：官方错误参考页列出了三种相关报错——Error: Invalid --agents configuration:、Error: --agents takes a JSON object, or a file path only with --print (-p)、Error: --agents file not found，分别对应 JSON 不合法、非 --print 模式下误传文件路径、传入的文件路径不存在。
• 文件路径形式的适用条件容易搞混：只有配合 --print/-p 时才能传文件路径，交互模式下传路径会直接报错，而不是尝试把路径当文件读取。
• 同名覆盖是静默的：CLI 定义的 subagent 会不声不响地覆盖 .claude/agents/ 和 ~/.claude/agents/ 中的同名 agent，如果没意识到优先级顺序，容易误以为改了项目里的 agent 文件却没生效。

来源

• Create custom subagents - Claude Code Docs
• Claude Code CLI Reference
• Claude Code Docs — Errors reference