使用 agent view 管理多个代理

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

Agent view 通过 claude agents 打开，是所有后台会话的一个屏幕：什么正在运行、什么需要你的输入、什么已完成。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在需要时才介入。每个后台会话都是一个完整的 Claude Code 对话，在没有终端连接的情况下继续运行，所以你可以随时打开它、回复并离开。

当你有多个独立任务 Claude 可以在不需要你观看每一步的情况下处理时，使用 agent view。调度一个 bug 修复、一个拉取请求审查和一个不稳定测试调查作为三行，在另一个窗口中继续工作，当一行显示它需要你或有结果时检查回来。

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

要比较 agent view 与 subagents、agent teams 和 worktrees，请参阅 并行运行代理。Agent view 在你的机器上运行会话，你调度每一个；要让 Claude 从一个对话中在云端启动和跟踪并行会话，请参阅 Projects。

快速开始

本演练涵盖核心 agent view 循环：调度一个任务，观看其行在 Claude 工作时更新，窥视以检查它并回复，以及附加到完整对话。你调度的会话在关闭 agent view 后继续运行，所以你可以离开并稍后回到它。

claude agents

你可以使用 claude agents 作为你的主要入口点而不是 claude：从 agent view 调度每个任务，当你想要完整对话时附加，按 ← 返回表格。

在常规 claude 会话内，提示页脚的 ← 提示计算正在等待你的后台 agent 数量，例如 ← 2 agents，当没有 agent 需要输入时返回 ← for agents。超过 99 的计数显示为 99+。当终端获得焦点时，计数大约每十秒刷新一次，当焦点返回时立即刷新。当计数移动和 agent 完成时，它会短暂改变颜色，当后台会话完成而没有 agent 需要你的输入时，它会短暂显示完成的数量，例如 ← 2 done。当启用了prefersReducedMotion 设置时，两个闪烁都关闭，并且在屏幕阅读器模式中隐藏提示。

使用 agent view 监控会话

运行 claude agents 打开 agent view。它接管整个终端并列出按状态分组的每个会话，固定的会话和需要你的会话在顶部。每行显示会话的名称、当前活动和其年龄，从会话创建时开始计算；已完成的会话的年龄冻结在运行花费的时间。

名称用该会话中由 /color 设置的颜色着色。包括当你用 ← 或 /background 后台会话时。

默认情况下，列表显示你启动的每个后台会话，跨越所有项目。在一个存储库中工作的会话和在不同 worktree 中工作的另一个会话都会出现在这里，无论你从哪个目录打开 agent view。要将列表限制到一个项目，请传递 --cwd：

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

这只显示在该目录下启动的会话。它仍然列出已移入 worktree 到 ~/projects/my-app/.claude/worktrees/ 下的会话。

你在其他终端中打开的交互式会话不会出现，直到你后台它们。Subagents 和 teammates 会话生成的不会列为单独的行。

Pinned
  ✽ clawd walk cycle          Drawing the walk-cycle sprite frames          3m

Ready for review
  ∙ jump physics              Opened PR with collision fix                 #2048  2h

Needs input
  ✻ power-up design           double jump or wall climb?                    1m

Working
  ✽ collision detection       Adding swept-AABB checks to CollisionSystem   2m
  ✢ playtest level 3          run 12 · all checkpoints cleared           in 4m

Completed
  ✻ title screen              result: menu, options, and credits done       9m
  ∙ sound effects             result: 14 SFX exported to assets/audio       4h
  … 6 more

读取会话状态

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

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

行右边缘可能出现的 #N 或 !N 标签是会话的拉取请求或合并请求的链接，不是状态图标的一部分。

终端标签标题在 agent view 打开时显示等待输入的计数：当会话需要输入时显示 2 awaiting input · claude agents，或当没有会话需要输入时显示 claude agents。

要从脚本或另一个程序读取会话状态，请使用 claude agents --json 而不是 ~/.claude/jobs/ 下的文件。

当 agent view 打开时，Claude Code 还会通过你配置的终端通知频道发送通知，当本地后台会话开始需要你的输入、完成或失败时。在计划上运行的会话，例如 /loop 会话，仅在需要你的输入时通知。通知使用与 Claude Code 其余部分相同的 preferredNotifChannel 设置，并使用 agent_needs_input 或 agent_completed 类型触发 Notification hook。

后台会话不需要任何打开的终端来继续工作。一个单独的监督进程运行它们，所以你可以关闭 agent view、关闭你的 shell 或启动一个新的交互式会话，你的调度工作继续进行。

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

当机器在会话中途响应时休眠时，会话可能会陷入无响应状态。当你打开一个已停止响应的会话时，监督进程重启其进程，会话从中断处继续中断的响应。

行摘要

每行中的单行摘要由 Haiku-class 模型生成，所以该行可以告诉你会话正在做什么、需要什么或生成了什么，无需打开记录。当会话正在积极工作时，摘要最多每 15 秒从会话自己的最近输出刷新一次，无需发送模型请求，每个回合结束时模型写入新摘要。

工作中的行显示会话说它正在做什么，被阻止的行显示它提出的问题。在长回合期间，模型也大约每分钟重写一次摘要，所以繁忙的行不会继续显示过时的摘要。摘要文本填充行的剩余宽度；打开窥视面板读取终端边缘裁剪的句子。

当列表按目录分组时，摘要以会话的状态作为彩色单词开头，例如 Needs input · double jump or wall climb?。在默认状态分组中，组标题已经命名了状态，所以行只显示摘要。

结束回合摘要和每次中途重写是通过你的正常提供商的一个短 Haiku-class 请求，按与会话本身相同的数据使用条款计费和处理。15 秒的模型重写之间的更新重用会话自己的输出，不发送请求。在没有配置 Haiku-class 模型的第三方提供商或网关上，请求使用会话的主模型；设置 ANTHROPIC_DEFAULT_HAIKU_MODEL 以选择一个。

拉取请求状态

当会话打开拉取请求时，Claude Code 在行的右边缘添加一个标签，链接到拉取请求：

• Claude Code 将标签写为 #1234 用于拉取请求，!1234 用于 GitLab 合并请求。
• Claude Code 即使无法检测到超链接支持（例如通过 SSH 或 tmux）也会发出链接。设置 FORCE_HYPERLINK=0 将标签呈现为纯文本。
• 在你向会话发送后续内容后，Claude Code 保持标签，同时行返回到实时进度。

处理现有拉取请求的会话以相同方式链接到它。Claude Code 根据 Claude 运行的命令以不同方式查找拉取请求：

• 当 Claude 用 gh 编辑、评论、关闭或标记拉取请求为就绪时，Claude Code 链接命令自己的输出命名的拉取请求。捕获的输出不命名拉取请求的 gh 命令不创建链接；gh pr merge 是常见情况，因为它仅将其结果打印到交互式终端。
• 当 Claude 用 gh pr checkout 检出拉取请求或推送到分支时，Claude Code 用 gh pr view 查找分支并链接其打开的拉取请求。
• 当 Claude 推送时拉取请求不需要已存在：Claude Code 在同一目录中最多五个后续 git、gh、glab 或 curl 命令运行后重试分支查找，所以在推送后创建的拉取请求，包括 Claude 通过 GitHub REST API 创建的，在重试找到它时链接。

当会话链接到多个拉取请求时，标签显示计数，例如 3 PRs，按最需要关注的打开拉取请求着色。打开窥视面板查看它们全部。

拉取请求编号由其状态着色：

对于以拉取请求结束的任务，检查此标签以获取结果：当其编号变绿时审查和合并拉取请求。

窥视和回复

在选定的行上按 Space 打开窥视面板。它打开时显示行截断的句子，该句子是什么取决于会话的状态：

• 等待你的会话：它提出的确切问题，在回复输入上方
• 已完成的会话：其结果
• 工作中的会话：其完整状态句子

任何链接到会话的拉取请求都列在下面。对于等待你的会话，下面的一行，例如 waiting 3m 显示它已经等待多长时间，这是面板中唯一显示的时间。行右边缘的年龄是一个不同的数字：它从会话启动时开始计算。

大多数时候窥视面板就足够了，你不需要打开完整的记录。

在窥视面板中输入回复并按 Enter 将其发送到该会话。当会话提出带有预定义选择的问题时，窥视面板将它们显示为编号列表，你可以按数字键选择一个。权限提示显示为描述会话想要运行的内容的文本，没有编号选项。输入回复以回答它，或附加以用标准提示回答。对于其他被阻止的会话，按 Tab 用建议的回复填充输入，你可以在发送前编辑。用 ! 前缀回复以发送 Bash 命令。

当 PermissionRequest 或 PreToolUse hook 返回 Claude Code 无法为会话询问的调用验证的输出时，行显示 hook 事件和 hook output invalid: 以及验证错误，然后是待处理请求的文本。对于以其他方式失败的 hook，行说 hook 失败。会话仍然等待相同的请求。

无法传递的回复，因为后台服务无法访问或发送失败，会被保存并在其进程再次启动时作为其下一个提示发送到会话，错误消息说回复已保存。前缀为 ! 的回复不会被保存，因为保存的文本会作为纯提示而不是 Bash 命令到达会话。

启用语音听写后，在回复输入获得焦点时按住或点击你的推送通话键以听写回复而不是输入。同样的功能在 agent view 底部的调度输入中也有效。

使用 ↑ 和 ↓ 窥视相邻会话而不关闭面板，或 → 附加。

附加到会话

在选定的行上按 Enter 或 → 附加。Agent view 被完整的交互式会话替换。当你附加时，Claude 发布一个关于你离开时发生的事情的简短回顾。

附加时，会话的行为像任何其他 Claude Code 会话：命令、快捷键和功能都有效，除了下面的例外。

当你附加时，/install-github-app 和 /mcp 设置列表正常工作，因为终端上有人可以完成它们的对话。当没有人附加时，这些命令无法打开它们的对话，所以会话在 agent view 中显示在 Needs input 下，行如 open this session to manage MCP servers，记录回复说相同的内容。附加并再次运行命令以继续；当你附加时需要输入的行清除。/mcp reconnect <server>、/mcp enable 和 /mcp disable 无论哪种方式都无需附加即可工作。

附加的会话始终以全屏模式呈现，无论你的 tui 设置如何，因为后台会话没有终端滚动历史可追加。使用 PgUp、PgDn 或鼠标滚轮滚动，按 Ctrl+O 进入记录模式。你的终端的原生滚动和 tmux 复制模式仅显示当前视口，与运行任何全屏应用程序时相同。

在空提示上按 ← 或运行 /exit 分离并返回 agent view，无论你从 agent view 打开会话还是从 shell 用 claude attach <id> 运行。

当 /btw overlay 打开时，← 也分离。需要 Claude Code v2.1.257 或更高版本。仍在回答的侧问题在你离开时继续运行。下次你附加时，overlay 会重新打开它，或带有它的答案。

在 Windows 上，如果你在附加后约半秒内按 ←，Claude Code 显示 Ambiguous ←, press again to detach，因为在该窗口中终端可以重新传递附加前的按压。再按一次 ← 以分离。

Ctrl+Z 也分离但返回到你开始的地方：如果你从那里附加则返回 agent view，或如果你运行了 claude attach 则返回你的 shell。当对话有焦点且不响应 ← 时使用 Ctrl+Z。

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

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

在不离开终端的情况下切换会话

在前台运行的会话中，一个你在终端中启动的而不是从 agent view 附加的，在空提示上按 ← 会后台它并打开 agent view，该行被选中，所以你可以在不离开终端的情况下切换会话。同样的单次按压分离附加的会话。

如果你在删除提示的最后文本或通过提示历史移动后立即按 ←，Claude Code 会要求你确认：第一次按压显示 Press ← again to open agents，或在附加的会话中显示 Press ← again to go back to agents，第二次按压切换。

当 ← 后台前台会话时，agent view 显示 Your conversation moved to the background 在列表上方，该会话的行已被选中。从那里：

• 按 Enter 重新打开对话。
• 按 Esc 撤销切换并返回对话。如果 Esc 显示 Still starting — try again in a moment，后台会话还没有准备好，所以稍后再按一次 Esc。
• 按 Ctrl+C 两次以退出到你的 shell。

当 Claude Code 无法重新打开对话时，它退出并打印一个 claude --resume 命令来恢复它。

Claude 的任务列表随对话移动到后台会话，所以当你返回该行时清单是完整的。

你按 ← 的行也在你用箭头键或鼠标移动选择后保持粗体、未暗淡的名称，所以你可以告诉你来自哪个会话。

如果在你按 ← 时工具正在运行，Claude Code 会等待大约十秒钟让它完成后台，响应在后台会话中继续。再按一次 ← 以立即后台而不是等待。当进行中的工作无法转移到后台会话时，Claude Code 首先显示 Background this session? 对话，与 /background 相同。

十秒限制在前台 subagents Claude 在对话中启动的仍在运行时不适用。Claude Code 继续等待以便它们的工作转移，并在等待时显示 Still backgrounding after the current tool 通知。再按一次 ← 以立即后台而不等待，这会从头重新启动这些 subagents。Claude Code 不等待动态工作流正在运行的 subagents。当工作流有 subagents 运行时，Claude Code 显示 Background this session? 对话。

Claude Code 不会在你的提示输入中有未发送的文本时后台会话，因为文本会留在你的终端输入框中，不会移动到后台会话。如果你在 Claude Code 等待后台会话时输入到输入中，它会用 Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again. 取消切换。

按 ← 创建会话的行，即使对话还没有消息，所以 → 仍然返回到它。

你可以在 /config 中用 leftArrowOpensAgents 设置关闭此快捷键。

组织列表

Agent view 按状态分组会话，需要输入的会话在顶部，Ready for review 和 Needs input 在 Working 和 Completed 上方。这些组名不与上面的状态一一对应：当会话有打开的拉取请求时，它移动到 Ready for review，Completed 收集已完成、失败和已停止的会话。

按 Ctrl+S 改为按目录分组。你的选择在运行中保存。

在一个组内：

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

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

第二次按压删除会话，即使停止尝试失败，例如因为后台服务没有响应：确认保持活跃另外两秒，删除结束会话的进程本身。按 Esc 关闭确认而不删除。

除了删除会话删除什么中涵盖的保留情况外，删除会从列表中删除会话，Claude 为其创建的 worktree 会被删除、保留或留在原地，取决于你如何删除以及 worktree 保留什么。对话记录始终保留在你的本地机器上，可通过 claude --resume 访问。

要在 Claude Code v2.1.212 或更高版本上恢复会话，在调度输入中输入 /resume。一个选择器打开，显示你打开 agent view 的存储库的过去会话，最新的在前，包括你从列表中删除的会话；已有行的会话不会列出。↑/↓ 移动选择，Enter 恢复选定的会话作为后台会话，所以它重新加入列表作为行，Esc 关闭选择器。

选择器仅对裸 /resume 打开。有针对性的、作用域的或受限的恢复无法由选择器提供，所以当以下情况时 agent view 显示 attach to a session to run it 提示：

• /resume 命名一个 id 或搜索项
• 视图用 --cwd 作用域
• 视图用 --safe-mode 启动
• 视图用 --permission-mode 或 --settings 等标志打开

不适合屏幕的已完成会话折叠成 … N more 行。失败和有打开拉取请求的会话始终保持可见。Completed 组填充活跃组之后剩余的垂直空间，在短终端上标题压缩为单个摘要行，以便正在工作或需要输入的会话保持可见。

过滤会话

在调度输入中输入以过滤而不是调度：

快捷键

在 agent view 中按 ? 查看每个快捷键的上下文。下表总结了它们。

Ctrl+S、Ctrl+T 和 Ctrl+G 遵循你的 keybindings.json。在 Agents 上下文中用 agents:switchView 和 agents:togglePin 操作重新绑定或取消绑定 Ctrl+S 和 Ctrl+T，以及通过 Chat 上下文的 chat:externalEditor 绑定的 Ctrl+G。表中的其他快捷键无法重新绑定。

调度新代理

你可以从 agent view 调度新的后台会话、将现有的交互式会话发送到后台，或直接从 shell 启动一个。

从 agent view

在 agent view 底部的输入框中输入提示并按 Enter 启动新的后台会话。会话从提示自动命名；稍后可以用 Ctrl+R 重命名它。

自动名称是由 Haiku-class model 编写的简短标签。会话稍后获得的名称也会出现在其行上，包括当你在该会话中 接受计划 时会话获得的 生成的标题。

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

粘贴的文本长度超过 800 个字符或超过三行会折叠为 [Pasted text #N] 占位符，以便输入保持在一行；完整文本在你调度时发送。要在调度前查看或编辑折叠的文本，再次粘贴相同的文本，占位符会展开回输入。

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

一小组命令在 agent view 本身中运行而不是调度：

• /exit 和 /quit 关闭 agent view
• /logout 将你登出
• /model 设置 调度模型
• /login 打开登录对话框，以便你可以在不附加到会话的情况下再次登录
• 裸 /resume 或其 /continue 别名打开存储库过去会话的选择器，以 恢复一个 作为后台会话。需要 Claude Code v2.1.212 或更高版本

Skills、你自己的命令和提示扩展内置命令如 /init 作为其第一个提示发送到新的后台会话。其他内置命令显示 attach to a session to run it 提示。你输入的所有内容都保留在提示旁边的输入中，以便你可以编辑它。

将重复任务打包为 skill 让你从 agent view 多次启动相同的工作流而无需重新输入提示。

当相同的 @name 同时匹配 subagent 和同级存储库时，subagent 优先。不带 @ 的首字形式也适用，所以以匹配你的某个 subagent 名称的单词开头的提示会调度该 subagent 而不是将该单词视为纯文本。当你想要明确指定时，使用 @ 形式，或以不同的单词开头提示以避免匹配。

调度到特定目录

新会话在你打开 agent view 的目录中运行。要针对不同的目录，使用以下任何一种：

• 在该目录中打开 claude agents。

• 在父目录中打开 claude agents 并在提示中用 @<repo> 提及一个子存储库。输入 @ 会列出这些目标：

  • 启动目录下一级的 Git 存储库
  • 你启动的存储库的已注册 git worktrees，这些 worktrees 位于其目录树内，例如 Claude 在 .claude/worktrees/ 下创建的那些，标记有其检出的分支。在存储库外添加的 worktrees，例如用 git worktree add ../feature 添加的，不会被列出
  • 任何已在列表中有会话的目录

  名称包含空格的目录不会被列出。

• 从 shell，cd 进入目录并运行 claude --bg "<prompt>"。

当 agent view 按目录分组时，调度会将提示发送到选定行的目录，所以你可以选择一个组并在不重新输入路径的情况下调度到它。

从会话内部

两个命令将工作从你所在的会话移动到后台：/background 将当前对话发送到那里并释放你的终端，/fork 在你继续工作的地方发送一个副本。

将会话发送到后台

运行 /background 或其别名 /bg 将当前对话移动到后台会话。传递提示如 /bg run the test suite and fix any failures 以在后台化前先给出一个更多指令。如果 Claude 在你运行 /bg 时正在响应，响应会在后台会话中继续。

退出仍有后台工作运行的会话，例如 subagents、后台 shell 命令、工作流或 monitors，会显示 Background work is running 对话而不是立即退出。选择 Move to background and exit 以与 /background 相同的方式将会话移动到后台并返回你的 shell。当 agent view 被 关闭 时，不显示该选项。

如果后台会话列表上已有一个会话具有对话的名称，Claude Code 会对新行的名称进行编号，例如 my-session (2)，并保持现有行的名称不变。要重命名新行，在 agent view 中选择它并按 Ctrl+R。

使用 /fork 复制会话

运行 /fork 将当前对话复制到新的后台会话中，同时原始会话继续运行。副本从对话中到该点的所有内容开始；参见下面的项目符号了解副本运行的位置。它还会继承模型、权限模式、工作量以及你在会话期间添加的任何目录或"不再询问"权限授予。副本在 agent view 中显示为其自己的行。

在 fork 之后，两个对话是独立的：副本所做的任何事情都不会自动进入原始对话，尽管在启用了 cross-session messaging 的会话中，任一会话的 Claude 都可以显式地向另一个会话发送消息。

复制会话需要 Claude Code v2.1.212 或更高版本；在 v2.1.161 到 v2.1.211 上，/fork 启动一个 forked subagent，现在是 /subtask。当 agent view 被关闭 时，/fork 保持 forked-subagent 行为，/subtask 不可用。

传递提示如 /fork open a draft pull request with the work so far，副本立即开始处理它。没有提示的情况下，副本等待其第一个指令：在 claude agents 中选择其行并按 Space 发送一个，或运行 claude attach <id>。选定的行在等待时显示 space to send it a prompt。

/fork 确认是一行，显示副本的状态，例如 session running、其 agent-view 行的名称和其会话 ID 用于 claude attach。点击名称以切换到副本：此会话移动到后台，与按 ← 相同，agent view 打开副本的会话。

除了副本 就地编辑 的情况外，Claude Code 指示它在进行代码更改前创建自己的 worktree。在 git 存储库外，只有从 hook 创建的 worktree 移出的副本才会获得该指令；没有 WorktreeCreate hook，副本就地编辑。从你的 worktree 移出的副本也被告知永远不要编辑、在其中运行命令或进入该 worktree，无论隔离设置如何。

副本开始的位置取决于当前会话运行的位置：

• 像任何调度的会话一样，副本 在编辑文件前移动到其自己的 worktree。在这种情况下，确认不会提及副本运行的位置。
• 当你的会话在启动后移动到其链接的 worktree 时，副本从会话移动前的位置开始，除非它 就地编辑，在那里的自己的 worktree 中进行代码更改。当你的 worktree 在分支上检出时，该指令也告诉一个副本，其任务建立在你的工作基础上，以你的分支为基础创建其新分支，因为你的分支在你的 worktree 中保持检出。确认以 runs in the origin tree 结尾。
• 当你在具有主工作树的存储库的链接 worktree 内启动会话时，副本在该主工作树中启动，具有相同的 worktree-of-its-own 规则但没有分支指令。确认也以 runs in the origin tree 结尾。
• 在裸存储库布局的 worktree 内启动的会话没有主工作树可返回，所以副本保持在原地，确认以 edits this checkout 结尾。当 worktree 隔离在不在链接 worktree 内的会话中被 关闭 时，也会出现相同的注释，因为副本随后编辑你打开的文件。

使用启动标志启动的会话，副本不会继承，例如替换的系统提示或 --tools 允许列表，无法被 fork；Claude Code 会说明这一点而不是进行部分副本。从 agent view 调度的会话正常 fork：副本使用与其来自的会话相同的 agent definition 和附加指令启动。

后台化时会继承什么

后台化启动一个新进程，从保存的对话恢复，进行中的工作会转移到它：运行后台 shell 命令、后台 subagents、动态工作流、你用 /loop 创建的计划任务，以及 Claude 对 artifact comments 的自动回复 都会继承并在那里继续运行。一个 subagent 与它启动的所有内容一起移动，所以它仅在所有工作都能转移时才转移。要停止进行中的工作而不是转移它，设置 CLAUDE_DISABLE_ADOPT=1 环境变量；Claude Code 随后会要求你在后台化前确认。

当 dynamic workflow 仍有 subagents 运行时，Claude Code 在后台化前用 Background this session? 对话询问，该对话说明有多少 subagents 会重新启动。选择 Stay 让它们先完成。如果你确认，Claude Code 在后台会话中重放运行：仍在运行的 subagents 从头开始，所以它们迄今为止使用的令牌会再次花费。参见 Resume after a pause 了解哪些已完成的 subagents 返回其保存的结果，哪些再次运行。

Claude Code 停止无法转移的工作，例如运行中的 monitor，并停止拥有监视器的后台 subagent 以及它。当任何此类工作正在运行时，Claude Code 显示 Background this session? 对话，以便你可以在它停止工作前确认。

一旦在后台，会话可以启动新的 subagents、monitors 和后台命令，这些会在后续的分离和重新附加中保持运行。

来自原始启动的配置标志会传递到后台化的会话，所以其 MCP servers、settings 和备用模型保持有效：

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

你在会话期间用 /add-dir 添加的目录也会传递。传递 --allow-dangerously-skip-permissions 会在后台化的会话中保持 bypassPermissions 可访问，但它不会授予任何新权限：该模式仍然需要 Permission mode, model, and effort 中描述的一次性交互式接受。

从你的 shell

传递 --bg 或其长形式 --background 启动直接进入后台的会话：

claude --bg "investigate the flaky SettingsChangeDetector test"

提示是位置参数，不是 -p 值。Claude Code 拒绝 --bg 与 -p 或 --print 结合在任何会话创建前，因为 --print 永远不会启动 claude agents 附加到的交互式会话。

要运行特定的 subagent（你已定义的，例如 code-reviewer）作为会话的主代理，结合 --bg 和 --agent：

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

如果名称不匹配你的任何 subagents，启动失败：Claude Code 打印 no agent named 警告，仍然报告会话为后台化，但会话立即以 --agent '<name>' not found 错误退出。

当后台化的会话稍后恢复或重新启动时，Claude Code 恢复代理及其工具限制；对于其系统提示，参见 System prompt flags in resumed conversations。它首先在会话自己的目录中搜索代理，前提是你已 信任该工作区，所以项目范围的代理在会话从另一个目录恢复时仍然加载。如果代理不再存在，会话继续使用默认工具，其记录以 warning naming the agent 打开。

要在后台继续现有对话，用 --resume 传递其完整会话 ID：

claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

在 Claude Code v2.1.257 或更高版本上，Claude Code 要么在相同 ID 下继续该会话，要么在新 ID 下启动副本并打印 note: 行解释为什么它无法就地继续。当会话就地继续时，claude agents 为其显示一行。

当你将 --bg 与 --continue、裸 --resume 或 --resume 与名称或文件路径结合时，Claude Code 总是启动这样的副本。添加 --fork-session 以有意启动副本，不带注释。

传递 --name 以在 agent view 中设置会话的显示名称而不是自动生成的名称：

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

后台化后，Claude 打印会话的短 ID 和管理它的命令。当托管后台会话的服务尚未运行时，--bg 可能首先在此输出上方打印 Starting background service…。当你传递 --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

运行 shell 命令

要运行 shell 命令作为后台作业而不是 Claude 会话，传递 --exec。以下示例将 pytest -x 作为后台作业运行：

claude --bg --exec 'pytest -x'

从 agent view，通过在调度输入的第一个字符处输入 ! 调度相同类型的作业：! 显示为前缀，其后的所有内容都是命令，Enter 启动作业。

该命令作为 PTY 支持的作业运行，并在 agent view 中显示为一行，最近的输出行作为其状态。shell 作业运行命令代替 Claude，所以不调用任何模型，输出也不发送到任何会话。

要查看输出，附加到该行，按 Space 以在不附加的情况下查看，或从你的 shell 运行 claude logs <id>。捕获的输出保留在内存中，不写入磁盘。该行及其输出在命令退出后约五分钟自动清理，所以如果你需要结果，请在那之前读取它。

文件编辑如何隔离

每个后台会话，无论是从 agent view、/bg 还是 claude --bg 启动，都在你的工作目录中启动。在编辑文件前，Claude 将会话移动到 .claude/worktrees/ 下的隔离 git worktree 中，所以并行会话可以读取相同的检出但每个都写入自己的。一旦会话在其 worktree 中，Claude Code enforces worktree isolation 对会话和它生成的任何 subagents。

Claude 在以下情况下跳过 worktree：

• 会话已经在链接的 git worktree 内，无论 Claude 是在 .claude/worktrees/ 下创建的还是你用 git worktree add 在其他地方创建的
• Claude 正在编辑的文件在链接的 git worktree 内，例如会话或其 subagent 用 git worktree add 创建的
• 工作目录不是 git 存储库且没有配置 WorktreeCreate hook
• 写入在工作目录外

要为 git worktrees 不实用的存储库关闭 worktree 隔离，将 worktree.bgIsolation 设置为 "none"。后台会话随后直接编辑你的工作副本而不先移动到 worktree。将设置添加到项目的 .claude/settings.json：

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

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

当 hook 在不是 git 存储库的目录中失败时，Claude 跳过该目录的隔离并就地编辑工作目录。在 git 存储库内，Claude Code 阻止对共享检出的写入，直到 Claude 将会话移动到 worktree。

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

subagent 后台会话生成的继承会话的工作目录，所以其文件编辑落在会话的 worktree 中而不是你的工作副本。要给 subagent 其自己的单独 worktree，在其 frontmatter 中设置 isolation: worktree 或在生成它时传递 isolation: "worktree"。

当后台会话在 Claude 进入的 worktree 中进行了代码更改时，Claude Code 指示 Claude 在完成前保留工作，所以如果你删除会话及其 worktree，它会存活：

• 提交并推送：Claude 无需询问即可提交，当存储库有远程时推送分支。
• 草稿拉取请求：当任务要求时 Claude 打开一个，#N label 出现在行上。
• 永不：推送到 main 或 master、强制推送和合并。
• 你的 git 指令优先：如果任务、CLAUDE.md 或 memory 说你自己处理提交或推送，Claude 将 git 留给你。

编辑未自行隔离的检出的会话仍然会在提交或切换分支前询问。这适用于隔离设置为 "none" 时、worktree 移动失败时，或会话在已存在的 worktree 内启动时。

无论任务如何，Claude 以报告结束作业，说明它做了什么以及工作在哪里：路径、分支、拉取请求或答案本身。

删除会话会移除什么

在 agent view 中用 Ctrl+X 两次或用 claude rm 删除会话。除了下面保留的情况外，会话离开列表。其记录通过 claude --resume 保留在你的机器上，移除在监督者重新启动后存活。

Claude 为会话创建的 worktree 会发生什么：

• Agent view 删除它，包括未提交的更改，所以先提交你想保留的内容。

• claude rm 当它有未提交的更改时保留它，以及会话行。

• 当另一个运行中的会话正在使用或已锁定 worktree 时，agent view 和 claude rm 都不会删除它，再次删除不会改变这一点。Claude Code 保留 worktree 和会话，并命名保留的目录和原因；在 agent view 中，会话的行显示 not deleted。关闭另一个会话，然后再次删除。

• 当你删除一个 worktree 有 Claude Code 无法确认保存在其他地方的提交的会话时，Claude Code 保留 worktree 和会话，消息命名 worktree 的分支和有多少未推送的提交。消息还提供两种前进方式：推送提交，或再次删除以丢弃它们。

  远程上的提交不会阻止删除。本地副本上的提交也不会，只要该分支在你的主检出（存储库目录本身而不是 worktree）中检出。

  在该拒绝后，你选择：

  • 要保留提交，推送它们或将它们合并到该默认分支，然后再次删除会话。
  • 要丢弃它们，再次删除会话而不推送：在 agent view 中的其行上按 Ctrl+X 两次，或运行拒绝打印的 claude rm <id> --discard-unpushed 命令。这会删除会话和 worktree 以及其分支，丢弃未推送的提交和任何未提交的更改。

  当你再次删除时，Claude Code 仅丢弃拒绝显示的内容：如果 worktree 自那以后获得了提交，Claude Code 再次保留它并显示更新的状态。

  当另一个已完成会话的记录也命名 worktree 时，当你再次删除时它保留；推送提交，然后再次删除。

• git 不再识别的 worktree，例如在 git worktree prune 后，不会阻止删除。Claude Code 删除会话并在磁盘上留下目录。

• 当 git 或你的 WorktreeRemove hook 无法删除 worktree 时，Claude Code 保留 worktree 和会话，消息命名原因。对于 hook，消息说它如何结束，例如 exited 1，并引用其 stderr 的开始。消息还告诉你接下来要做以下哪一个：

  • 再次删除会话以无论如何删除目录，在 agent view 中的其行上按 Ctrl+X 两次或运行 claude rm 拒绝打印的 claude rm <id> --force-remove-worktree <worktree-id> 命令。Claude Code 仅在它可以确认目录是存储库在 .claude/worktrees/ 下的链接 worktrees 之一，没有对跟踪文件的未提交更改、其内没有嵌套存储库，没有其他会话的记录命名它时才提供此选项。worktree 的分支保留在存储库中。
  • 修复阻碍的东西，例如提交或隐藏未提交的更改、关闭使用目录的任何东西或修复 hook，然后再次删除会话。
  • 自己删除目录，然后再次删除会话。

你自己创建的 worktree 并在其中启动会话的，无论哪种方式都会保留在原地。

一个 worktree 目录不属于任何 git 存储库的会话，因为存储库被删除或 WorktreeCreate hook 在其他地方创建了目录，仍然可以被删除。当文件保留在目录中时：

• Agent view 在丢弃它们前要求相同的 Ctrl+X 双按。对于 hook 创建的目录，它运行你的 WorktreeRemove hook，没有一个它拒绝删除并保留会话。
• claude rm 保留会话和 worktree，并命名原因。

任一路径都保留另一个已完成会话的记录命名的目录。

设置模型

agent view 标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，这来自你的用户设置中的 model 设置。通过在 /model 选择器 中选择模型来设置它，或直接编辑设置。

要为整个 agent view 会话覆盖调度默认值，在打开 agent view 时传递 --model。参见 Permission mode, model, and effort。

要从 agent view 内部更改调度默认值，在调度输入中输入 /model 后跟模型名称并按 Enter。标题更新以显示该模型，带有 (session) 标记，之后调度的会话使用它。输入 /model default 以清除覆盖并返回调度默认值。此覆盖持续当前 claude agents 运行的其余部分，不写入你的设置文件。以下示例在 Opus 上调度一个会话，在 Sonnet 上调度下一个：

/model opus
refactor auth
/model sonnet
run the test suite

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

• 从 shell，用 claude --bg 传递 --model。
• 附加到运行中的会话并运行 /model 以切换：从选择器中选择，或输入 /model <name>，保存为你的新会话默认值，除非你在选择器中按 s 进行仅会话切换。如果会话被重新生成，仅会话切换会持续。
• 调度一个 subagent，其 frontmatter 设置 model 字段。

权限模式、模型和工作量

后台会话从它运行的位置和方式获取其设置、提供商、权限模式、模型和工作量。下面的小节涵盖每个来源，以及当监督者重新启动会话时什么持续。

设置和提供商

后台会话从它运行的目录读取其 settings，就像你在那里启动了 claude 一样。这包括项目设置中的 env 值，所以在那里设置的 ANTHROPIC_MODEL 或提供商变量适用于该目录中的每个后台会话。

后台会话也用你调度它的 shell 的 PATH 运行，所以它运行的命令找到与你的终端相同的工具。它也保留该 shell 的云提供商选择，例如 CLAUDE_CODE_USE_BEDROCK 或 CLAUDE_CODE_USE_VERTEX，以及其 ANTHROPIC_DEFAULT_*_MODEL 别名和任何 CLAUDE_CODE_EXTRA_BODY 覆盖你在那里导出的。

LLM gateway

如果你通过 LLM gateway 路由 Claude Code，将网关变量放在设置文件的 env 块中而不是在你的 shell 中导出它们，后台会话用其余设置读取它们。Set in a settings file 显示块和要使用哪个设置文件用于凭证。

如果你仅在你的 shell 中导出网关 ANTHROPIC_BASE_URL，它到达后台会话，以及 ANTHROPIC_CUSTOM_HEADERS 和你与它导出的凭证，仅当 supervisor 本身从导出相同网关的 shell 启动时，仅在这些情况下：

• 你用 ← 或 /background 后台化你自己的会话
• 你调度一个会话到你所在的目录
• 你通过附加或回复它唤醒你所在目录中的停止会话

Claude Code 在云提供商前转发网关。如果你调度的 shell 选择提供商并用其 auth-bypass 标志导出其网关端点，Claude Code 在适用于 ANTHROPIC_BASE_URL 的条件下将端点和标志对转发到会话，以及 ANTHROPIC_CUSTOM_HEADERS。例如，导出 CLAUDE_CODE_USE_VERTEX=1 与 ANTHROPIC_VERTEX_BASE_URL 和 CLAUDE_CODE_SKIP_VERTEX_AUTH=1，Claude Code 转发该端点和标志。

Claude Code 仅将转发的网关应用于该会话的运行进程，永远不会将其写入磁盘。

权限模式

permission mode 取决于你如何启动会话：

• 用 /bg 或 ← 后台化：Claude Code 保留会话所在的权限模式，所以你切换到 acceptEdits 或 auto 的会话在分离后仍保持该模式
• 从你用 ← 打开的 agent view 调度：目标自己的配置优先，你来自的会话的权限模式在没有其他设置一个时适用
• 从 shell 中启动的 claude agents 或用 claude --bg 调度：新会话以新 claude 会话在该目录中的方式启动，除非你从用 dispatch defaults 打开的 agent view 调度它。Which permission mode a session starts in 列出顺序

对于你从用 ← 打开的 agent view 调度的会话，Claude Code 从适用的第一个中获取权限模式：

1. 目标目录的 permissions.defaultMode。两个来源规则适用：
   • auto 和 bypassPermissions 仅从托管设置、--settings 文件或 ~/.claude/settings.json 生效。
   • Claude Code 拒绝来自项目的 .claude/settings.json 或 .claude/settings.local.json 的 defaultMode，该模式选择比你来自的会话所在的更宽松的模式。
2. 你来自的会话的权限模式

当 Claude Code 拒绝来源的模式太宽松时，列表中的下一个来源决定。例如，如果你从 plan-mode 会话调度到一个检入的设置要求 acceptEdits 的目录，新会话在 plan mode 中启动。如果你将该 defaultMode 移动到 ~/.claude/settings.json，它无论你来自的会话的权限模式如何都适用。

宽松性运行 plan，然后 Manual 和 dontAsk，然后 acceptEdits 和 auto，它们彼此计为更宽松，然后 bypassPermissions。

调度默认值

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

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

--effort 这里接受与 top-level --effort flag 相同的值，包括 ultracode。

--agent 设置当调度提示未命名一个时使用的 subagent，无论是用 @name 还是作为第一个单词。如果设置了一个，它默认为 agent 设置，否则为内置的全能 claude 代理。在调度输入中命名 subagent 会覆盖两者。

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

传递 --restricted 以在 restricted mode 中启动你从视图调度的每个会话，就像每个都用顶级 --restricted 标志启动一样。需要 Claude Code v2.1.248 或更高版本。

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

Claude Code 拒绝 claude --bg --permission-mode bypassPermissions 直到你通过交互式运行 claude --dangerously-skip-permissions 一次接受了绕过免责声明，因为该模式让你没有看到的会话无需批准就能行动。传递 --dangerously-skip-permissions 或 --permission-mode bypassPermissions 到 claude agents 在你之前没有接受它时显示相同的免责声明，接受会将 bypassPermissions 应用到你从视图启动的会话。传递 --allow-dangerously-skip-permissions 也显示相同的免责声明，接受会在这些会话的 Shift+Tab 循环中使 bypassPermissions 可用而不在其中启动它们。

重新启动时持续什么

你为后台会话选择的权限模式、模型和工作量，以及 configuration flags it carries，在监督者稍后 stops and restarts 其进程时都会持续。你用 claude --bg --dangerously-skip-permissions 或 claude --bg --permission-mode bypassPermissions 启动的会话在该重新启动后仍保持 bypassPermissions。你在会话中期用 /model 或 /effort 更改的模型或工作量也被保留。

如果会话从你的设置而不是从 --effort 或 /effort 获取工作量，Claude Code 每次为会话启动进程时都会再次读取你的设置。所以当你在 settings.json 中编辑保存的工作量时，更改到达你用 ← 或 /bg 后台化的会话及其后续重新启动。保存的工作量是 effortLevel 键或 modelSettings 条目。

Claude Code 也保留你用 /rename 或 Ctrl+R 设置的名称在该重新启动中，所以你仍然可以运行 claude --resume <name> 以到达会话。

你在附加时用 Ctrl+S 隐藏的提示也与会话一起保留。在其进程被停止或重新启动后重新打开会话，Ctrl+S 恢复隐藏的文本。隐藏中的粘贴内容不会在重新启动中存活。

Settings、plugins 和 MCP servers

Agent view 接受与 claude 相同的配置标志以加载 settings、plugins、MCP servers 和额外目录。Agent view 将 --settings 和 --plugin-dir 应用于自己，并将每个配置标志传递给你从它调度的会话，所以以这种方式加载的 plugin 或 MCP server 在这些会话中也可用。

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

你可以将 --settings 和 --plugin-dir 放在 agents 之前或之后。将 --add-dir 和 --mcp-config 放在 agents 之后：如果你将其中任何一个放在 agents 之前，claude agents --json 失败并显示 unknown option 错误。

以下示例使用 settings 覆盖和一个额外目录打开 agent view：

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

--settings 接受文件路径或内联 JSON 字符串。文件路径必须指向现有文件；如果不存在，Claude Code 以 Settings file not found 错误退出。

从 shell 管理会话

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

将会话列为 JSON

claude agents --json 将活跃会话打印为 JSON 数组并退出：每个活跃会话，加上仍在工作或被阻止的后台会话，即使其进程已退出。添加 --all 以也包括已完成的后台会话，添加 --cwd <path> 以将列表限制为在该目录下启动的会话。

每个条目描述一个会话：

从脚本读取会话状态

claude agents --json 是从 Claude Code 外部读取会话状态的受支持方式，例如从状态栏、调度程序或监督后台工作的另一个 Claude 会话。轮询 claude agents --json --all，它会继续列出进程已退出的会话，并读取每个条目的 state、status 和 waitingFor。

完成其回合并等待你的下一条指令的会话读取 done，而不是 blocked。blocked 总是意味着会话在继续之前需要你提供的东西。

~/.claude/jobs/<id>/ 下的文件不是稳定的接口。会话或其他程序写入 state、detail、tempo 或 needs 的值会在下一次更新时被替换。

如果你想让会话用自己的话报告进度，让它写一个自己的文件，例如在 $CLAUDE_JOB_DIR/tmp 下，而不是编辑 state.json。

后台会话如何被托管

Claude Code 将 agent view 中列出的每个会话都视为后台会话，无论你当前是否连接到它。相比之下，通过直接运行 claude 启动的会话与该终端绑定，并在终端关闭时结束，除非你将其发送到后台。

要检查你所在的会话类型，请运行 /status。在后台会话中，Session kind 行显示 background job · attached 或 background job · unattended，具体取决于是否连接了终端，在任何其他会话中显示 interactive。

监督进程

监督进程是一个后台服务，运行你的后台会话，使其在你关闭 agent view 或终端后继续工作。Claude Code 在你第一次后台化会话或打开 agent view 时启动它，你不需要自己管理它。

每个会话都是监督进程下的自己的 Claude Code 进程，该进程发生的情况取决于会话的状态：

• 工作中、暂停在权限提示或其他对话上，或已连接：进程继续运行。运行中的子代理、工作流或监视器计为工作中。
• 已完成或等待你的下一条消息，且未连接约一小时：监督进程停止该进程以释放资源。以向你提问结束其轮次的会话计为等待你的下一条消息。对话保存在磁盘上，下次你连接或回复时，会话从中断处恢复。使用 Ctrl+T 固定会话以保持其进程运行。
• 在监督进程运行时意外退出：监督进程重新启动该进程。使用 ← 或 /background 后台化的会话（例如使用 kill）标记为已停止而不是重新启动。对于以关闭结束的会话，请参阅会话在关闭后显示为失败或已停止。
• 自动更新后：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待你或已连接的会话不会被中断。

当会话的进程停止或重新启动时，Claude 在其中启动的后台 shell 命令、动态工作流和后台子代理会转移到其下一个进程；运行中的监视器和子代理启动的 shell 命令会随进程停止。删除会话会停止它转移的所有内容。要改为让所有内容随进程停止而不是转移，请将 CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF 设置为 1。

监督进程及其会话使用与你的交互式会话相同的存储凭证进行身份验证。关于哪些设置和 shell 变量到达会话（包括 PATH），请参阅设置和提供商。关于网关端点，请参阅 LLM 网关。

状态存储位置

会话状态存储在你的 Claude Code 配置目录下。如果你设置了 CLAUDE_CONFIG_DIR，监督进程使用该目录而不是 ~/.claude，并作为单独的实例运行，具有其自己的会话。

每个后台会话都设置了 CLAUDE_JOB_DIR 环境变量指向其 ~/.claude/jobs/<id> 目录，因此会话运行的 shell 命令可以将临时文件写入 $CLAUDE_JOB_DIR/tmp 而不会与并行会话冲突。

要在不直接读取文件的情况下检查此状态，请运行 claude daemon status。它报告监督进程是否可达、其进程 ID 和版本、套接字目录以及有多少后台会话处于活跃状态。

该命令还会在运行的监督进程版本与你调用的 claude 版本不同时发出警告，这发生在监督进程尚未重新启动到新版本的更新之后。警告显示两个版本，并告诉你运行 claude daemon stop --any 以获取新版本。当 Claude Code 作为操作系统服务安装时，建议的命令是 claude daemon stop 不带该标志。

会话完整地保留该版本不匹配：更新会话 state.json 的较旧 Claude Code 版本会保留它不识别的字段并保持会话列出。roster.json 中的会话列表遵循相同的规则，因此由较新版本启动的会话保持可达并在监督进程重新启动后继续接受输入。

关闭 agent view

要完全关闭后台代理和 agent view，将 disableAgentView 设置设为 true 或设置 CLAUDE_CODE_DISABLE_AGENT_VIEW 环境变量。管理员可以通过托管设置强制执行这个。

Troubleshooting

`claude agents` 列出子代理而不是打开代理视图

如果 claude agents 打印一个计数，然后是您配置的子代理，然后退出，说明代理视图在您的环境中不可用。运行 claude update 来安装最新版本。

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

代理视图打开时没有会话

在您分派第一个会话之前，代理视图显示空的部分标题，每个标题下有一个描述，以及在输入上方有一行说明，代替会话列表。在底部的输入中输入提示，然后按 Enter 来分派您的第一个会话。

后台处理显示 `Background this session?` 对话框

如果您按 ← 来后台处理当前会话，而 Claude Code 显示 Background this session? 对话框，说明该会话有正在进行的工作，后台处理会停止、重新启动或让其无人值守地运行，Claude Code 在执行这些操作之前会询问：

• 无法移动的工作：该会话有无法移动到后台会话的工作，例如正在运行的监视器。对话框命名 Claude Code 会停止的工作，并分别计算转移的任务数。
• 具有运行子代理的工作流：动态工作流仍然有子代理在运行。工作流本身会转移，但其运行的子代理从头开始重新启动，对话框会说明有多少个。
• 自动工件回复：Claude 自动回复工件上的评论。这些回复在后台会话中继续，对话框会说明这一点。

运行 /tasks 来查看正在运行的所有内容，然后确认后台处理或选择 Stay 来让工作先完成。请参阅后台处理时转移的内容，了解哪些类型的工作会转移，哪些 Claude Code 会停止。

提示被拒绝为过短

分派输入期望一个任务描述，而不是对话开场白。短于四个字符的提示会被拒绝，并显示 Too short 提示，以防止误触发启动会话。描述您希望会话执行的操作，例如 investigate the flaky checkout test。

会话在关闭后显示为失败或已停止

关闭或重新启动您的机器会停止运行的后台会话。等待您输入的会话在您返回时仍会显示在 Needs input 下。对于任何其他运行的会话，代理视图显示的内容取决于它上次取得进展的时间：

• 在 48 小时内，会话显示为失败。附加或回复它，它会从中断的地方重新启动。
• 超过 48 小时，例如机器关闭数天后，会话显示为已停止，并显示 ended while the background service was off。在该行上按 Enter，页脚会显示 Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it. 在同一行上再次按 Enter 来恢复其保存的对话。回复或 claude attach <id> 会在没有该页脚提示的情况下恢复它。

当转录清理删除了已停止会话的保存对话时，Claude Code 拒绝打开该行：消息说没有可恢复的内容。claude rm <id> 删除该行，除了保留的情况中描述的情况，claude respawn <id> 再次运行其原始提示。请参阅此会话的保存对话不再在磁盘上。

仅睡眠不会停止会话。会话在睡眠中被保留，主管在唤醒时重新连接到它们。

打开会话说对话已经打开

两个进程不能写入同一个转录。当已停止会话的保存对话已在另一个活跃的 Claude Code 进程中打开时，Claude Code 拒绝启动该会话自己的进程。您看到的内容取决于什么持有对话：

• 您恢复对话的终端，例如使用 claude --resume 或 /resume：该行显示 Open in a terminal，并提示在那里继续，打开该行显示 Can't open — this session is running in another terminal。在该终端中继续，或退出它并再次打开该行。
• 另一个非交互式 Claude Code 进程，例如同一对话的后台会话进程，尚未退出：打开该行显示 This conversation is already open in another running Claude session。使用该进程，或等待它退出并再次打开该行。

Claude Code 保存您在拒绝的尝试中输入的回复，并在会话下次启动时发送它。

打开会话说它没有保存的转录

已停止的会话从另一个对话后台处理并在其第一个响应完成之前停止，没有任何可恢复的内容：在该第一个响应完成之前，对话仍然只存在于它被后台处理的会话中。claude attach 拒绝打开它，显示 This session has no saved transcript。

在代理视图中，打开该行在列表下显示 Press enter again to restart this session fresh。在同一行上再次按 Enter 来使用空对话重新启动会话，或从 shell 运行 claude respawn <id>。

原始对话完整无损；使用 claude --resume 恢复它或继续在其中工作。有关详细信息，请参阅错误参考。

终端主机已死亡或会话停止响应

主管在其自己的主机进程中运行每个后台会话的终端。当该进程死亡或停止响应时，Claude Code 显示原因并提供重新启动；在两种情况下，对话都被保存，重新启动会恢复它。错误参考引用完整消息。

Claude Code 永远不会重新启动运行shell 命令的行，无论是从 Enter 还是从 claude attach，因为那样会再次运行该命令；该行的消息和 claude attach 都说该命令不会再次运行。

终端主机已死亡

在 Linux 和 WSL 上，主管每隔几秒检查一次每个主机进程，无论您是否打开会话，当进程已退出但其与主管的连接从未关闭时，将会话标记为失败。

• 在代理视图中，该行显示 terminal host process died — press Enter to restart。在它上面按 Enter，Claude Code 在新的主机进程上重新启动会话。
• 从 shell，claude attach <id> 重新启动已标记为失败的会话。否则它报告原因并退出，告诉您运行 claude attach <id>。

会话没有响应

当主管接受打开但约十秒内没有输出到达时，Claude Code 结束尝试并提供重新启动。仅仅停滞的会话，例如跨机器睡眠，不会达到此提议：主管在打开时自己重新启动它。

• 在代理视图中，页脚显示 Press enter again to restart this session — it isn't responding (its conversation is saved and resumes). 在同一行上再次按 Enter，Claude Code 停止无响应的进程并重新启动会话；没有第二次按下，它不会停止任何内容。
• 从 shell，claude attach <id> 报告原因并退出，告诉您运行 claude stop <id>，然后 claude attach <id>。

会话在启动前失败，并显示 `possibly low memory` 注释

当后台会话的进程在完成启动之前退出，且主机内存不足时，该行的状态命名退出并添加 possibly low memory — free some up and retry。

该注释是一个假设，而不是确认的原因。Claude Code 仅在进程无声退出时添加它，没有写入错误，也没有被信号停止，且主机在那一刻报告内存不足。当进程在退出前确实写入了错误时，该行显示该错误。

释放机器上的内存，然后附加或回复该行，主管为会话启动新进程。当内存保持不足时，主管也会停止空闲会话来自行释放资源，如果停止其他会话没有释放任何内容，也会停止空闲的固定会话。

代理视图说后台服务没有响应

如果附加、查看或 claude logs 报告后台服务没有响应，主管进程可能已停滞。停止它并让下一个 claude agents 启动新的。要在重新启动期间保持后台会话运行，请传递 --keep-workers：

claude daemon stop --any --keep-workers

新的主管重新连接到运行的会话。没有 --keep-workers，该命令也会结束后台会话。--any 标志确认您想停止按需启动的主管，而不是作为已安装的服务，这是默认值。

启动但无法接受连接的主管会自行退出并释放其锁，所以下一个 claude agents 会启动新的，无需此手动停止。上述步骤适用于运行的主管停滞的情况。

如果该命令改为退出，说记录的进程无法验证为主管，请检查报告的进程 ID：如果它是您拥有的主管，自己停止它，然后删除 ~/.claude/daemon.lock，以便下一个 claude agents 启动新的。

在 Windows 上，如果主管不响应停止请求，该命令会打印其进程 ID。使用 taskkill /PID <pid> 结束该进程以完成恢复。当您传递 --keep-workers 时，后台会话仍然被保留。

分派失败，显示 `Could not resolve authentication method`

如果后台分派失败，显示 Could not resolve authentication method，而交互式会话正常进行身份验证，接收分派的工作人员没有获取凭据。后台会话从主管获取其凭据，所以此错误意味着主管进程本身没有可用的存储凭据。确认您已运行 /login 或配置了 API 密钥，然后停止主管：

claude daemon stop --any --keep-workers

下一个 claude agents 或 claude --bg 启动读取您存储凭据的新主管。如果您使用环境变量（如 ANTHROPIC_API_KEY）而不是 /login 进行身份验证，请从设置了该变量的 shell 运行该下一个命令。

有关原因和修复的完整列表，请参阅错误参考。

后台会话无法在 macOS 上读取 Desktop、Documents 或 Downloads

在 macOS 上，后台会话主机作为其自己的进程运行，并与您的终端分别请求对受保护文件夹的访问。如果后台会话在读取 ~/Desktop、~/Documents、~/Downloads 或其他受保护位置时报告 Operation not permitted，请在系统设置中的隐私和安全 > 文件和文件夹下授予访问权限，或为该条目启用完全磁盘访问。

使用本机安装程序，该条目显示为 Claude Code，授予在更新中持续。使用其他安装方法（如 Homebrew 或 npm），该条目显示二进制路径，更新后可能需要再次授予。

后台会话无法在 macOS 上访问本地网络主机

在 macOS 15 及更高版本上，系统会阻止进程访问本地网络上的设备，直到您授予本地网络权限，因此针对 LAN 地址的命令可能在后台会话中失败，显示 connect: no route to host，即使它在前台终端中有效。后台会话中连接到本地网络地址的第一个命令会触发 Claude Code 的 macOS 本地网络权限提示。授予一次，这些命令就能像在前台终端中一样访问 LAN 主机。

附加后会话响应缓慢

当已完成或等待您下一条消息的会话保持未附加约一小时时，主管停止其进程以释放资源。附加从中断的地方启动新进程，并在进程重新启动时立即切换到会话。正在工作、暂停在权限提示或其他对话上的会话，或固定的会话不会以这种方式停止，所以使用 Ctrl+T 固定会话以保持其响应性。

进程启动时，Claude Code 显示会话转录的尾部，格式化为实时会话呈现的方式，带有 markdown、突出显示的代码块和工具调用作为暗淡的行，上方是带有 Session is starting 注释的暗淡提示区域。实时会话在准备好后立即替换它。

`.claude/worktrees/` 正在填满

在代理视图中删除会话会删除 Claude 为其创建的 worktree，但某些删除会保留 worktree 或在磁盘上留下其目录，所以剩余目录可能会累积。Git 不再识别的目录不会出现在 git worktree list 中，所以手动删除这些目录。

在项目目录中使用 git worktree list 列出剩余条目，并使用 git worktree remove <path> 删除每一个。请参阅清理 worktrees。

限制

Agent view 处于研究预览阶段，存在以下限制：

• 速率限制适用：后台会话消耗你的订阅使用量，与交互式会话相同，因此并行运行十个代理的配额消耗速度大约是运行一个代理的十倍。
• 会话是本地的：后台会话在你的机器上运行。它们在机器睡眠时保留，但在机器关闭时停止。
• Claude 创建的 worktrees 在 agent view 中随会话删除：在删除在其自己的 worktree 中编辑文件的会话之前，请提交更改。某些删除会保留 worktree。

相关资源

有关以并行方式运行 Claude 的其他方法，以及在运行的会话之间传递发现的方法，请参阅：

• 并行运行代理：比较 agent view 与 subagents、agent teams 和 worktrees
• 跨会话消息传递：让您的会话相互传递发现
• Agent teams：协调相互发送消息的多个会话
• 在云端使用 Claude Code：在托管的云环境中运行会话而不是本地
• Projects：让 Claude 从一个对话中协调并行云会话，并告诉您哪些需要您

版本历史

Agent view 在研究预览期间发展迅速。如果你使用较旧的 Claude Code 版本，本页上的某些行为可能会有所不同；特别是，claude agents 拒绝它尚不支持的标志，出现 unknown option 错误。下表列出了何时添加每个标志和行为。