文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

使用代理视图管理多个代理

从一个屏幕调度和管理多个 Claude Code 会话。代理视图显示每个会话在做什么以及哪些需要你的输入。

代理视图通过 claude agents 打开，是一个用于管理所有后台会话的单一界面：正在运行的、需要你输入的和已完成的。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在一个会话需要你时才介入。每个后台会话都是一个完整的 Claude Code 对话，无需终端连接即可继续运行，因此你可以随时打开、回复和离开。

当你有几个独立任务 Claude 可以在没有你监督的情况下处理时，使用代理视图。调度一个 bug 修复、一个拉取请求审查和一个不稳定测试调查作为三行，在另一个窗口继续工作，当某行显示需要你或有结果时再查看。

当你想更直接地在任何代理的会话中工作时，附加到该行以进入完整对话。

要将代理视图与子代理、代理团队和工作树进行比较，请参阅并行运行代理。

本页涵盖：

• 快速开始：给 Claude 一个后台任务，检查它，并在需要时介入
• 使用代理视图监控会话，包括状态图标、预览和回复、附加、组织和键盘快捷键
• 调度新代理：从代理视图、会话内部或 shell 调度
• 从 shell 管理会话
• 后台会话如何托管：由监管进程托管

快速开始

本指南涵盖代理视图的核心循环：调度任务，观察 Claude 工作时其行更新，预览检查并回复，以及附加到完整对话。你调度的会话在关闭代理视图后继续运行，因此你可以离开并稍后回来。

1. 打开代理视图

   从你的 shell 运行：

   claude agents
   

   代理视图打开，底部有输入框，随着会话启动表格会填充内容。随时按 Esc 返回 shell。你离开时会话继续运行，下次打开代理视图时会重新出现。

2. 调度会话

   输入描述任务的提示并按 Enter。新的后台会话在该任务上启动，并显示为一行，指示它是在工作中、等待你还是已完成。新会话使用代理视图标题中显示的模型，以及你在该目录中运行 claude 时获得的相同权限模式。

   你在此处输入的每个提示都会启动自己的新会话。输入另一个提示并按 Enter 会在第一个旁边启动第二个会话，而不是向第一个发送后续消息。你可以这样并行运行多个会话。

   每个会话独立使用你的订阅配额，因此在调度多个会话之前请参阅限制。

3. 预览和回复

   使用箭头键选择一行并按 Space 打开预览面板。它显示会话的最新输出或它正在等待的问题，而非完整记录。输入回复并按 Enter 发送，无需离开代理视图。

4. 附加和分离

   在选中的行上按 Enter 或 → 以附加到完整对话。该会话接管终端，就像你运行了 claude 一样。在空提示上按 ← 以分离并返回表格。

5. 将现有会话加入

   要将你已经打开的会话移入代理视图，在其中运行 /bg，或在空提示上按 ← 以将其置于后台并一步打开代理视图。该会话继续运行并显示为你调度的会话旁边的行。

你可以将 claude agents 用作主要入口点代替 claude：从代理视图调度每个任务，当你需要完整对话时附加，按 ← 返回表格。

使用代理视图监控会话

运行 claude agents 打开代理视图。它接管整个终端，列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动以及上次更改的时间。

默认情况下，列表显示你启动的所有后台会话，跨所有项目。在一个仓库中工作的会话和在不同工作树中的另一个会话都出现在这里，无论你从哪个目录打开代理视图。要将列表缩小到一个项目，传递 --cwd（需要 Claude Code v2.1.141 或更高版本）：

claude agents --cwd ~/projects/my-app

这仅显示在该目录下启动的会话。已移入工作树的会话（在 ~/projects/my-app/.claude/worktrees/ 下）仍算作属于 ~/projects/my-app。

你在其他终端中打开的交互式会话在你将它们置于后台之前不会出现。会话生成的子代理和队友不会作为单独的行列出。

已固定
  ✽ clawd walk cycle          Write assets/sprites/clawd-walk.png           3m

待审查
  ∙ jump physics              github.com/example/game/pull/2048          ●  2h

需要输入
  ✻ power-up design           needs input: double jump or wall climb?       1m

工作中
  ✽ collision detection       Edit src/physics/CollisionSystem.ts           2m
  ✢ playtest level 3          run 12 · all checkpoints cleared           in 4m

已完成
  ✻ title screen              result: menu, options, and credits done       9m
  ∙ sound effects             result: 14 SFX exported to assets/audio       4h
  … 还有 6 个

读取会话状态

每行以一个图标开头，其颜色和动画显示会话的状态：

另外，图标的形状显示底层进程是否正在运行：

行右边缘可能出现的 ● 是拉取请求状态指示器，不是状态图标的一部分。它前面的数字是会话已打开的拉取请求数。

代理视图打开时，终端标签页标题显示等待输入的计数：当会话需要输入时显示 2 awaiting input · claude agents，当没有时显示 claude agents。

后台会话不需要打开任何终端即可继续工作。单独的监管进程运行它们，因此你可以关闭代理视图、关闭 shell 或启动新的交互式会话，你调度的工作会继续进行。

会话状态通过自动更新和监管重启在磁盘上持久化。会话在机器休眠时也会保留。它们的进程在唤醒时恢复，监管重新连接到它们而不是将时间间隔视为空闲。关机仍会停止运行的会话；有关如何恢复它们，请参阅关机后会话显示为失败。

行摘要

每行中的单行摘要由 Haiku 级模型生成，因此行可以在不打开记录的情况下告诉你会话在做什么、需要什么或产出了什么。当会话积极工作时，摘要最多每 15 秒刷新一次，加上每次轮次结束时刷新一次。

每次刷新都是通过你的正常提供商的一个简短 Haiku 级请求，按与会话本身相同的数据使用条款计费和处理。

拉取请求状态

当会话打开拉取请求时，行的右边缘会出现状态点，在支持超链接的终端中链接到拉取请求。当会话打开了多个拉取请求时，计数出现在点前面，颜色反映最需要注意的那个。

对于大多数任务，这行是你获取结果的地方：当点变绿时审查并合并拉取请求。

预览和回复

在选中的行上按 Space 打开预览面板。它显示会话需要你做什么、其最新输出以及它打开的任何拉取请求。大多数时候这就够了，你永远不需要打开完整记录。

在预览面板中输入回复并按 Enter 发送到该会话。当会话询问多选问题时，预览面板显示选项，你可以按数字键选择一个。对于其他被阻塞的会话，按 Tab 用建议的回复填充输入，你可以在发送前编辑。用 ! 前缀回复以改为发送 Bash 命令。

使用 ↑ 和 ↓ 预览相邻会话而无需关闭面板，或 → 以附加。

附加到会话

在选中的行上按 Enter 或 → 以附加。代理视图被完整的交互式会话取代，就像你在该目录中运行了 claude 一样。附加时，Claude 会发布你离开期间发生的事情的简短回顾。

附加时，会话的行为与任何其他 Claude Code 会话相同：每个命令、键盘快捷键和功能都有效。

在空提示上按 ← 以分离并返回代理视图。如果对话框有焦点且不响应 ←，按 Ctrl+Z 立即分离。

Ctrl+C 在附加时保持其标准中断行为：它取消正在运行的响应或 ! shell 命令，而不是分离。在空提示上按两次 Ctrl+C 分离，与任何会话相同。

分离从不停止后台会话：←、Ctrl+Z、/exit、双 Ctrl+C 或双 Ctrl+D 都让它继续运行。要从内部结束会话，运行 /stop。

在你调度或将会话置于后台后，在空提示上按 ← 在任何 Claude Code 会话中都有效，不仅限于你从代理视图附加的会话。它将当前会话置于后台并打开代理视图，选中该行，这样你可以在不离开终端的情况下切换会话。即使是没有对话历史的全新会话也会创建该行，因此 → 可以返回到它。当该行是唯一一行时，代理视图在其下方显示入门提示。你可以在 /config 中关闭此快捷键（leftArrowOpensAgents 设置）。

组织列表

代理视图将会话分组，使需要输入的在顶部，待审查 和 需要输入 在 工作中 和 已完成 之上。这些组名称与上面的状态不是一一对应的：当会话有打开的拉取请求时移动到 待审查，已完成 将已完成、失败和停止的会话收集在一起。按 Ctrl+S 改为按目录分组。你的选择在运行之间持久化。

在组内：

• 按 Ctrl+T 将会话固定到顶部，并在空闲时保持其进程运行
• 按 Shift+↑ 或 Shift+↓ 重新排序会话
• 按 Ctrl+R 重命名会话
• 在组标题上按 Enter 折叠它

要从列表中移除会话，按 Ctrl+X 停止它，两秒内再按 Ctrl+X 删除它。在组标题上按 Ctrl+X 确认后删除该组中的每个会话。

删除会从代理视图中移除会话。如果 Claude 为会话创建了工作树，删除也会移除该工作树，包括其中的任何未提交更改，因此先推送或提交你想保留的工作。你自己创建并在其中启动会话的工作树会保留。对话记录保留在你的本地机器上，可通过 claude --resume 访问。

较旧的已完成会话折叠为 … N more 行以保持列表简短。失败和有打开拉取请求的会话始终保持可见。

过滤会话

在调度输入中输入以过滤而非调度：

键盘快捷键

在代理视图中按 ? 查看上下文中的每个快捷键。下表总结了它们。

调度新代理

你可以从代理视图调度新的后台会话，将现有的交互式会话发送到后台，或直接从 shell 启动。

从代理视图

在代理视图底部的输入中输入提示并按 Enter 启动新的后台会话。会话从提示自动命名；稍后使用 Ctrl+R 重命名。

将图像粘贴到提示中以在任务中包含截图或图表。

前缀或提及提示的某些部分以控制会话如何启动：

将重复任务打包为技能让你可以从代理视图反复启动相同的工作流，无需重新输入提示。

当同一个 @name 同时匹配子代理和同级仓库时，子代理优先。裸第一个词匹配也适用，因此恰好以你的子代理名称之一开头的提示会调度该子代理而不是将该词视为纯文本。当你想要明确时使用 @ 形式，或用不同的词开始提示以避免匹配。

调度到特定目录

新会话在你打开代理视图的目录中运行。要定向到不同的目录：

• 在该目录中打开 claude agents
• 在包含多个仓库的父目录中打开 claude agents，并在提示中用 @<repo> 提及一个以在那里运行会话
• 从 shell 中 cd 到该目录并运行 claude --bg "<prompt>"

当代理视图按目录分组时，高亮行的目录成为调度目标，这样你可以滚动到一个组并调度到其中，无需重新输入路径。

从会话内部

运行 /background 或其别名 /bg 将当前对话移入后台会话。传递提示如 /bg run the test suite and fix any failures 以先给出更多指令。

从交互式会话置于后台会启动一个新进程，从保存的对话恢复，因此运行中的子代理、监视器和后台命令不会转移到它。当有任何正在运行时，Claude 会在置于后台前要求你确认。进入后台后，会话可以启动新的子代理、监视器和后台命令，这些在后续分离和重新附加时继续运行。

原始启动的配置标志传递到置于后台的会话，因此其 MCP 服务器、设置和回退模型保持有效：

• --mcp-config 和 --strict-mcp-config
• --settings
• --add-dir
• --plugin-dir
• --fallback-model
• --allow-dangerously-skip-permissions

你在会话期间使用 /add-dir 添加的目录也会传递。

传递 --allow-dangerously-skip-permissions 使 bypassPermissions 在置于后台的会话中可达，但不会授予任何新权限。该模式仍然需要权限模式、模型和努力程度中描述的相同的一次性交互接受，任何会话才能使用它。

从你的 shell

传递 --bg 以启动直接进入后台的会话：

claude --bg "investigate the flaky SettingsChangeDetector test"

要运行特定子代理作为会话的主代理，将 --bg 与 --agent 结合：

claude --agent code-reviewer --bg "address review comments on PR 1234"

传递 --name 以设置会话在代理视图中的显示名称，而非自动生成的名称：

claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

置于后台后，Claude 打印会话的短 ID 和管理命令。当你传递 --name 时，名称出现在短 ID 之后：

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

文件编辑如何隔离

每个后台会话，无论是从代理视图、/bg 还是 claude --bg 启动的，都在你的工作目录中开始。在编辑文件之前，Claude 将会话移入 .claude/worktrees/ 下的隔离 git 工作树，这样并行会话可以读取相同的检出但每个写入自己的。

Claude 跳过工作树的情况：

• 会话已在链接的 git 工作树内，无论是 Claude 在 .claude/worktrees/ 下创建的还是你在其他地方用 git worktree add 创建的
• 工作目录不是 git 仓库且未配置 WorktreeCreate 钩子
• 写入在工作目录之外

要关闭 git 工作树不实用的仓库的工作树隔离，将 worktree.bgIsolation 设置为 "none"。后台会话然后直接编辑你的工作副本，无需先移入工作树。将设置添加到项目的 .claude/settings.json：

{
  "worktree": {
    "bgIsolation": "none"
  }
}

在 git 仓库之外，会话直接写入工作目录且彼此不隔离，因此避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置 WorktreeCreate 钩子，Claude 会以与 git 相同的方式隔离编辑。

在代理视图中删除会话（Ctrl+X 两次）会移除 Claude 为其创建的工作树，包括其中的任何未提交更改，因此先合并或推送你想保留的更改。使用 claude rm 从 shell 删除会保留有未提交更改的工作树并打印其路径，以便你自己清理。你自己创建并在其中启动会话的工作树在两种情况下都会保留。

要找到会话的工作树路径，预览会话或附加并检查其工作目录。

要让子代理无论如何启动都在自己的工作树中运行，在其前置数据中设置 isolation: worktree。

设置模型

代理视图标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，来自你用户设置中的 model 设置。在 /model 选择器中按 d 设置，或直接编辑设置。要为整个代理视图会话覆盖它，在打开代理视图时传递 --model。参见权限模式、模型和努力程度。

每个后台会话可以运行不同的模型。要为一个会话覆盖它：

• 从 shell，传递 --model 和 claude --bg
• 附加到运行中的会话并在那里运行 /model。如果会话重新生成，更改会持续
• 调度设置了 model 字段的子代理

权限模式、模型和努力程度

后台会话从其运行的目录读取设置，就像你在该目录启动 claude 一样。

权限模式取决于你如何启动会话。使用 /bg 或 ← 将现有会话置于后台会保持当前权限模式，因此你切换到 acceptEdits 或 auto 的会话在分离后保持该模式。从代理视图输入调度或从 shell 运行 claude --bg 使用该目录设置中的 defaultMode，或调度的子代理前置数据中的 permissionMode。

你启动后台会话的权限模式在监管稍后停止并重启会话进程时持续。你使用 claude --bg --dangerously-skip-permissions 或 claude --bg --permission-mode bypassPermissions 启动的会话在重启后保持 bypassPermissions，而不是回退到目录的 defaultMode。

要为从代理视图调度的每个会话设置默认值，在打开时传递 --permission-mode、--model 或 --effort 中的任何一个：

claude agents --permission-mode plan --model opus --effort high

claude agents 也接受 --dangerously-skip-permissions 作为 --permission-mode bypassPermissions 的简写，以及 --allow-dangerously-skip-permissions 使 bypassPermissions 在每个调度会话的 Shift+Tab 循环中可用而不在该模式下启动。两者都匹配顶级 CLI 标志。

活动默认值出现在调度输入下方的页脚中。

没有这些标志时，会话使用该目录设置中的 defaultMode 或调度的子代理前置数据中的 permissionMode，以及代理视图标题中显示的模型。

使用 bypassPermissions 或 auto 会被拒绝，直到你通过交互式运行 claude 一次接受了该模式，因为这些模式允许你未在监视的会话在没有审批的情况下行动。无论你是将模式传递给 claude agents 还是 claude --bg --permission-mode，都适用相同规则。

设置、插件和 MCP 服务器

代理视图接受与 claude 相同的配置标志，用于加载设置、插件、MCP 服务器和额外目录。这些标志需要 Claude Code v2.1.142 或更高版本。每个标志适用于代理视图本身，并传递到你从中调度的每个会话，因此你以此方式加载的插件或 MCP 服务器在这些会话中也可用。

每个值重复 --add-dir、--plugin-dir 或 --mcp-config 一次。空格分隔的形式如 --add-dir a b c 不支持 claude agents。

以下示例使用设置覆盖和一个额外目录打开代理视图：

claude agents --settings ./ci-settings.json --add-dir ../shared-lib

从 shell 管理会话

每个后台会话都有一个你可以从 shell 使用的短 ID。当你使用 claude --bg 启动会话时打印 ID，每个会话的 ID 是 ~/.claude/jobs/ 下的目录名。这些命令对于脚本编写或当你不想打开代理视图时很有用。

后台会话如何托管

代理视图中列出的每个会话都被视为后台会话，无论你当前是否附加到它。相比之下，直接运行 claude 启动的会话绑定到该终端并在关闭时结束，除非你将其发送到后台。

监管进程

后台会话由每用户监管进程托管，独立于你的终端和代理视图。监管在你第一次将会话置于后台或打开代理视图时自动启动，你不直接管理它。

监管及其会话使用与你的交互式会话相同的凭据认证，除了模型 API 之外不进行额外的网络连接。

每个后台会话都是自己的 Claude Code 进程，由监管管理而非绑定到你的终端。正在积极工作、等待你输入或有终端附加的会话保持其进程运行。正在运行的后台 shell 命令、子代理、工作流或监视器算作活跃工作，因此长时间运行的进程如开发服务器保持会话存活。

一旦会话完成并无附加放置约一小时，监管停止其进程以释放资源。你使用 Ctrl+T 固定的会话免除并在空闲时保持其进程运行。记录和状态无论如何都保留在磁盘上，下次你附加、预览或回复停止的会话时，监管从上次停止的地方启动新进程。当每个会话都已完成且没有终端连接时，监管本身退出并在你下次需要时重新启动。

当主机内存不足时，监管先停止空闲非固定会话，仅在释放了什么都没有时才停止空闲固定会话。

监管监视磁盘上安装的 Claude Code 二进制文件，在常规自动更新器替换后重启到新版本。这是本地文件监视，不是网络检查。后台会话是分离进程，因此它们在重启期间继续运行，新的监管重新连接到它们。空闲固定会话也原地重启到新版本，以便无需你重新附加即可获取更新。

状态存储位置

会话状态存储在你的 Claude Code 配置目录下。如果你设置了 CLAUDE_CONFIG_DIR，监管使用该目录代替 ~/.claude，并作为独立实例运行，有自己的会话。

要在不直接读取文件的情况下检查此状态，运行 claude daemon status。它报告监管是否可达、其进程 ID 和版本、套接字目录以及有多少后台会话处于活跃状态。/doctor 包含相同检查的摘要。在 Windows 上，claude daemon status 在守护进程的管道密钥文件被锁定或不可读时显示底层文件错误，而非报告通用连接失败。

关闭代理视图

要完全关闭后台代理和代理视图，将 disableAgentView 设置设置为 true 或设置 CLAUDE_CODE_DISABLE_AGENT_VIEW 环境变量。管理员可以通过托管设置强制执行此操作。

故障排除

claude agents 列出子代理而非打开代理视图

如果 claude agents 打印计数后跟你的配置子代理然后退出，代理视图在你的环境中不可用。更早的版本并非在每个环境中都打开代理视图，包括通过 Bedrock、Vertex AI 或 Foundry 连接时。运行 claude update 安装最新版本。

如果更新后代理视图仍未打开，检查它是否被设置或环境变量关闭。

代理视图打开但没有会话

在你调度第一个会话之前，代理视图显示一个简短的入门提示，带有示例提示代替会话列表。在底部的输入中输入提示并按 Enter 调度你的第一个会话。

无法打开代理因为后台任务正在运行

如果按 ← 将当前会话置于后台显示 Cannot open agents — N background task(s) running，该会话有进行中的工作如子代理、工作流或后台 shell 命令，快捷键不会静默放弃它。运行 /tasks 查看正在运行的内容，然后 /bg 确认放弃它们。参见从会话内部了解置于后台时什么会转移、什么不会。

提示被拒绝为太短

调度输入期望任务描述，而非对话开场白。少于四个字符的提示被拒绝并显示 Too short 提示，这样意外按键不会启动会话。描述你想让会话做什么，如 investigate the flaky checkout test。

关机后会话显示为失败

关闭或重启机器会停止运行中的后台会话，因此下次打开代理视图时它们显示为失败。附加、预览或回复其中任何一个，会话从上次停止的地方重新启动。

仅休眠不会导致此情况。会话在休眠期间保留，监管在唤醒时重新连接到它们。

附加后会话响应缓慢

一旦会话完成并无附加放置约一小时，监管停止其进程以释放资源。附加会从上次停止的地方启动新进程，这需要一点时间。正在工作、等待你或固定的会话不会被这样停止，因此用 Ctrl+T 固定会话以保持其响应性。

.claude/worktrees/ 正在填满

在代理视图中删除会话会移除 Claude 为其创建的工作树。claude rm 保留有未提交更改的工作树并打印其路径。在项目目录中使用 git worktree list 列出残留条目，用 git worktree remove <path> 移除每个。参见清理工作树。

限制

代理视图处于研究预览阶段，有以下限制：

• 速率限制适用：后台会话与交互式会话一样消耗你的订阅使用量，因此并行运行十个代理大约比运行一个快十倍消耗配额
• 会话是本地的：后台会话在你的机器上运行。它们在休眠期间保留，但在机器关闭时停止
• Claude 创建的工作树在代理视图中随会话删除：在删除编辑了自己工作树中文件的会话之前合并或推送更改。claude rm 保留有未提交更改的工作树；你自己创建的工作树保留

相关资源

有关并行运行 Claude 的其他方式，请参阅：

• 并行运行代理：将代理视图与子代理、代理团队和工作树进行比较
• 代理团队：协调多个相互通信的会话
• Web 版 Claude Code：在托管云环境中而非本地运行会话