它到底是什么

--agent <name> 用于指定当前会话使用哪个 agent（subagent 定义），效果是把整个主线程变身为该 agent 的角色，而不是像 Task 委派那样另外派生一个并行的子 agent。

指定后会同时替换三样东西：

• System 提示词——用该 agent 的自定义指令整体替换 Claude Code 默认系统提示词（官方文档说明这在效果上等价于使用 --system-prompt）
• 工具限制——会话中只能使用该 agent 定义允许的工具
• 模型——整个会话使用该 agent frontmatter 里指定的 model（sonnet / opus / haiku / fable 等）

接受值是一个 agent 名字字符串，对应 .claude/agents/（项目级）、~/.claude/agents/（个人级）下某个 markdown 文件 frontmatter 里的 name 字段，或通过 --agents CLI flag 以 JSON 内联定义的 agent。未指定 --agent 时，若 .claude/settings.json 配置了 "agent" 键，会话默认使用该 agent；两者都没有则使用 Claude Code 默认系统提示词。

一个例外：即便 agent 定义中设置了 omitClaudeMd: true，CLAUDE.md 文件仍会通过消息流正常加载。

用法

claude --agent my-custom-agent

对应的 agent 定义文件（项目级示例）：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
permissionMode: default
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

也可以不落文件，直接用 --agents 以 JSON 一次性定义并配合 --agent 选用：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}' --agent code-reviewer

未见到与之对应的环境变量。

与其他 flag 的组合 / 互斥

• --bg：可组合，让指定 agent 以后台 agent 方式运行某个任务，例如 claude --bg --agent my-custom-agent "task description"。
• --resume：会话被恢复时，之前选定的 agent 会持续生效；若该 agent 已不存在，会话会继续使用默认工具，并显示点名该 agent 的警告，而不是报错终止。
• --agents：常搭配使用——先用 --agents 以 JSON 内联定义一个或多个 agent，再用 --agent <name> 选中其中之一运行。
• --system-prompt：官方文档指出 --agent 对系统提示词的效果"等价于使用 --system-prompt"，即用 agent 定义里的内容整体替换默认系统提示词，二者本质上作用在同一处（都是替换系统提示词）。
• --append-subagent-system-prompt / --append-subagent-system-prompt-file：用于向 subagent 的系统提示词追加内容，与 --agent 属于相关但不同的机制。

在 settings.json / env 的等价配置

CLI flag 优先级更高：若 .claude/settings.json 里设置了 "agent"，命令行传入的 --agent 会覆盖它。

运行约束 / 限制

经典使用场景

• 需要在整个会话期间保持某种专业化、受限的行为模式（如安全审查、只读代码审查）时使用 --agent，而不是每次用 @agent-<name> 这类 @-mention 指定某个 subagent 去处理任务。
• 与 --bg 组合，让指定 agent 以后台方式独立跑一个任务。

常见坑

• --agent 与 @-mention 调用方式的区别容易混淆：@agent-<name>（或在选择器里选中 code-reviewer (agent)）只是指定 Claude 调用哪个 subagent，不会把主线程变成该 agent；而 --agent 是把整个主线程变成该 agent，作用范围是整个会话。
• agent 定义丢失后的静默降级：如果用 --agent 启动的会话被 resume，而对应的 agent 定义文件已被删除或改名，Claude Code 不会报错中止，而是继续使用默认工具并显示警告——容易在没注意到警告的情况下，误以为仍在用原 agent 的受限工具集工作。

来源

• CLI reference（code.claude.com，从 docs.claude.com 重定向而来）
• Create custom subagents（code.claude.com/docs/en/sub-agents）
• What is the --agent Flag in Claude Code（ClaudeLog FAQ，第三方，与官方文档内容相互印证）