使用 agent view 管理多个代理

​

快速开始

claude agents

​

默认打开 agent view

/config defaultToAgentsView=true

claude

​

使用 agent view 监控会话

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

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          all checkpoints cleared ×12                in 4m

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

​

读取会话状态

​

行摘要

​

拉取请求状态

• Claude Code 对拉取请求将标签写为 #1234，对 GitLab 合并请求写为 !1234。
• 即使无法检测到超链接支持（例如通过 SSH 或 tmux），Claude Code 也会输出链接。设置 FORCE_HYPERLINK=0 可将标签呈现为纯文本。
• 在您向会话发送后续消息后，Claude Code 会保留该标签，同时行恢复显示实时进度。

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

​

窥视和回复

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

• 正在工作的会话：/model、/effort、/rename 和 /usage 会立即运行。其他回复会加入会话的消息队列而不是打断回复，并在排队输入生效时生效。其他命令会等待当前轮次结束，即使是在会话自身的提示符处输入后会立即运行的命令
• 恰好为 /stop 的回复：立即停止会话，而不是发送给会话，无论会话正在工作还是在等待您
• shell 作业：回复（包括 /stop）会作为键入的输入发送到该命令的终端

• 带有预定义选项的问题：面板按编号列出选项。在回复输入框为空时，按某个选项的编号将其填入，然后按 Enter 发送，或者改为输入您自己的答案
• 没有预定义选项的问题：输入您的答案。当空输入框显示建议的回复时，按 Tab 将其填入，并可在发送前编辑
• 权限提示或其他对话框，例如沙箱提示或 MCP 服务器的输入请求：回复并不会回答它。您的回复会在队列中等待。要回答该对话框，请用 → 附加

​

附加到会话

​

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

• 按 Enter 重新打开对话。
• 按 Esc 撤销切换并返回对话。如果 Esc 显示 Still starting — try again in a moment，说明后台会话尚未就绪，请稍后再按一次 Esc。
• 按两次 Ctrl+C 退出到 shell。

• 前台子代理仍在运行：Claude Code 会继续等待，以便 Claude 启动的前台子代理的工作能够转移，并显示 Still backgrounding after the current tool。再按一次 ← 可不等待直接转入后台，这会从头重新启动这些子代理。
• 有权限提示或问题在等待您的回答：当权限提示或 Claude 提出的问题处于等待状态时，Claude Code 会继续等待并显示 Still backgrounding after the current tool — a question is waiting for your answer. 如果您的回答让当前轮次得以继续，例如在权限提示上选择 Yes，Claude Code 会在当前工具完成时将会话转入后台。
• 您在提示输入框中输入内容：Claude Code 会取消切换，因为未发送的文本会留在终端的输入框中，不会移到后台会话。它会显示 Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.
• 您停止了当前轮次：Claude Code 会取消切换并显示 Backgrounding cancelled — the turn was stopped. 例如，当您用 Esc 中断 Claude，在主对话的权限提示上不添加评论而选择 No，或在主对话中 Claude 提出的问题上按 Esc 时，当前轮次会停止。再按一次 ← 即可将会话转入后台。
• 排队的消息无法移动：您在 Claude 工作时排队的消息会随对话移到后台会话。当其中某条消息无法移动时，会话会留在前台，Claude Code 会显示类似 Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it. 的通知。

​

组织列表

• 按 Ctrl+T 将会话固定到顶部，并在空闲时保持其进程运行
• 按 Shift+↑ 或 Shift+↓ 重新排序会话
• 按 Ctrl+R 重命名会话
• 在组标题上按 Enter 将其折叠，但过滤器处于活动状态时除外，此时所有组都保持展开

• /resume 指定了 id 或搜索词
• 视图通过 --cwd 限定了范围
• 视图以 --safe-mode 启动
• 视图以 --permission-mode 或 --settings 等标志打开

​

过滤会话

​

快捷键

​

分派新的 Agent

​

从 Agent 视图分派 Agent

• /exit 和 /quit 关闭 Agent 视图
• /logout 将您注销
• /model 设置 分派模型
• /login 打开登录对话框，以便您无需附加到会话即可重新登录
• 不带参数的 /resume 或其别名 /continue 会打开该仓库过去会话的选择器，以将其中一个作为后台会话 恢复。需要 Claude Code v2.1.212 或更高版本

​

分派到特定目录

• 在该目录中打开 claude agents。
• 在父目录中打开 claude agents，并在提示词中使用 @<repo> 提及子仓库。输入 @ 会列出这些目标：
  • 启动目录下一级的 Git 仓库
  • 您启动时所在仓库已注册的、位于其目录树内的 git worktree，例如 Claude 在 .claude/worktrees/ 下创建的 worktree，并标注其检出的分支。在仓库外添加的 worktree（例如使用 git worktree add ../feature 添加的）不会列出
  • 列表中已有会话的任何目录
  名称包含空格的目录不会列出。
• 从 shell 中 cd 进入该目录并运行 claude --bg "<prompt>"。

​

将会话发送或复制到后台

​

将会话发送到后台

​

使用 /fork 复制会话

• 与任何分派的会话一样，副本会 在编辑文件前移入自己的 worktree。这种情况下，确认信息不会提及副本运行的位置。
• 当您的会话在启动后移入其链接的 worktree 时，副本会回到会话移动前的位置启动，并且除非它 就地编辑，否则会在那里自己的 worktree 中进行代码更改。当您的 worktree 检出在某个分支上时，该指令还会告诉任务建立在您工作之上的副本将其新分支基于您的分支，因为您的分支仍检出在您的 worktree 中。确认信息以 runs in the origin tree 结尾。
• 当您在拥有主工作树的仓库的链接 worktree 内启动会话时，副本会在该主工作树中启动，同样遵循使用自己 worktree 的规则，但没有分支指令。此时确认信息同样以 runs in the origin tree 结尾。
• 在裸仓库布局的 worktree 内启动的会话没有可返回的主工作树，因此副本留在原处，确认信息以 edits this checkout 结尾。当在不位于链接 worktree 内的会话中 关闭了 worktree 隔离时，也会出现相同的说明，因为此时副本会编辑您打开的文件。

​

后台处理时的继承内容

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

​

从您的 shell 分派 Agent

claude --bg "investigate the flaky SettingsChangeDetector test"

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

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

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

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 命令

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

​

文件编辑如何隔离

• 您使用 ← 或 /background 将已打开的会话移到后台。该会话会继续在其原本工作的位置编辑文件
• 会话已位于链接的 git worktree 内，无论该 worktree 是 Claude 在 .claude/worktrees/ 下创建的，还是您使用 git worktree add 在其他位置创建的
• Claude 正在编辑的文件位于链接的 git worktree 内，例如会话或其子代理使用 git worktree add 创建的 worktree
• 工作目录不是 git 仓库，且没有配置 WorktreeCreate hook
• 写入位置在工作目录之外

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

• 提交并推送：Claude 无需询问即可提交，并在仓库有远程时推送分支。
• 草稿 Pull Request：Claude 会在任务需要时打开一个，该行上会显示 #N 标签。
• 绝不：推送到 main 或 master、强制推送以及合并。
• 您的 git 指令优先：如果任务、CLAUDE.md 或 记忆 表明由您自己处理提交或推送，Claude 会将 git 操作留给您。

​

删除会话会移除什么

• Agent 视图会移除它，包括未提交的更改，因此请先提交您想保留的内容。
• 当它有未提交的更改时，claude rm 会保留它以及会话行。
• Agent 视图和 claude rm 都不会移除另一个正在运行的会话正在使用或已锁定的 worktree，再次删除也不会改变这一点。Claude Code 会保留 worktree 和会话，并指明保留的目录及原因；在 Agent 视图中，该会话的行会显示 not deleted。请关闭另一个会话，然后再次删除。
• 当您删除的会话的 worktree 中有 Claude Code 无法确认已保存到其他位置的提交时，Claude Code 会保留 worktree 和会话，消息会指明 worktree 的分支以及有多少未推送的提交。消息还提供两种后续做法：推送这些提交，或再次删除以丢弃它们。 远程上的提交不会阻止删除。您的 origin 远程默认分支的本地副本上的提交也不会阻止删除，前提是该分支检出在您的主检出中（即仓库目录本身，而不是 worktree）。 在该拒绝之后，您可以选择：
  • 要保留这些提交，请推送它们，或将它们合并到该默认分支，然后再次删除会话。
  • 要丢弃它们，请不推送而直接再次删除会话：在 Agent 视图中该会话的行上按两次 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 视图中该会话的行上按两次 Ctrl+X，或运行 claude rm 拒绝消息中打印的 claude rm <id> --force-remove-worktree <worktree-id> 命令。worktree 的分支会保留在仓库中。 只有当 Claude Code 能确认以下所有条件时才会提供此选项：
    • 该目录是仓库在 .claude/worktrees/ 下的链接 worktree 之一
    • worktree 及其已检出的子模块都没有对已跟踪文件的未提交更改
    • 没有其他会话的记录指向它
    当 Claude Code 无法验证子模块检出的状态时（例如该子模块被一个单独的 git 仓库替换），也不会提供此选项。
  • 解决阻碍因素，例如提交或储藏未提交的更改、将单独的 git 仓库移出 worktree、关闭正在使用该目录的程序或修复 hook，然后再次删除会话。
  • 自行移除该目录，然后再次删除会话。

• Agent 视图在丢弃这些文件前会要求同样按两次 Ctrl+X。对于由 hook 创建的目录，它会改为运行您的 WorktreeRemove hook；如果没有该 hook，它会拒绝删除并保留会话。
• claude rm 会保留会话和 worktree，并指明原因。

​

设置模型

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

• 从 shell 中使用 claude --bg 时传递 --model。
• 附加到正在运行的会话并运行 /model 进行切换：在选择器中选择，或输入 /model <name>，都会保存为新会话的默认值，除非您在选择器中按 s 进行仅限当前会话的切换。仅限当前会话的切换在会话重新生成后依然有效。
• 分派一个在 frontmatter 中设置了 model 字段的 子代理。

​

权限模式、模型和 effort

​

设置和提供商

​

LLM 网关

• 您使用 ← 或 /background 将自己的会话转入后台
• 您将会话分派到您当前所在的目录
• 您通过附加或回复来唤醒当前所在目录中已停止的会话

​

权限模式

• 使用 /bg 或 ← 转入后台：Claude Code 保留会话原有的权限模式，因此您已切换到 acceptEdits 或 auto 的会话在分离后仍保持该模式
• 从使用 ← 打开的 Agent 视图分派：目标自身的配置优先；当没有其他设置指定权限模式时，采用您来源会话的权限模式
• 从在 shell 中启动的 claude agents 分派，或使用 claude --bg 分派：新会话的启动方式与在该目录中启动新的 claude 会话相同，除非您是从使用 分派默认值 打开的 Agent 视图分派的。会话以哪种权限模式启动 列出了优先顺序

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

​

分派默认值

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

​

重新启动后保留的内容

​

设置、插件和 MCP 服务器

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

​

从 shell 管理会话

​

将会话列为 JSON

​

从脚本读取会话状态

​

后台会话如何被托管

​

监督进程

• 工作中、暂停在权限提示或其他对话框上，或已连接：进程继续运行。运行中的子代理、工作流或监视器计为工作中，待执行的会话范围定时任务（例如 /loop 唤醒）也同样计为工作中。
• 已完成或等待您的下一条消息，且未连接约一小时：监督进程停止该进程以释放资源。以向您提问结束其轮次的会话计为等待您的下一条消息。对话保存在磁盘上，下次您连接或回复时，会话从中断处恢复。使用 Ctrl+T 固定会话以保持其进程运行。
• 在监督进程运行时意外退出：监督进程重新启动该进程。如果通过 kill 等方式结束您自己使用 ← 或 /background 后台化的会话，该会话会被标记为已停止，而不是重新启动。对于以关闭结束的会话，请参阅会话在关闭后显示为失败或已停止。
• 自动更新后：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待您或已连接的会话不会被中断。
• 监督进程本身停止，例如因为其进程被 Claude Code 外部结束：在 macOS 和 Linux 上，每个会话的进程会等待约一分钟，等待新的监督进程重新连接到它，如果没有重新连接则停止。在这一分钟内于 shell 中运行 claude agents，即可启动新的监督进程并保持会话运行。如果这一分钟先过去，会话会停止，但其保存的对话仍保留在磁盘上：连接或回复某个会话，它就会从保存的对话重新启动，如会话在关闭后显示为失败或已停止中所述。

​

状态存储位置

​

关闭 agent view

​

故障排除

​

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

​

Agent 视图打开时没有会话

​

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

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

​

提示词被拒绝为过短

​

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

• 在 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 --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 attach 打印 This session has no saved transcript。
• Agent 视图在列表下方显示 Press enter again to restart this session fresh。

​

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

​

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

​

Agent 视图说后台服务没有响应

claude daemon stop --any --keep-workers

​

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

claude daemon stop --any --keep-workers

​

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

​

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

​

附加后会话响应缓慢

​

.claude/worktrees/ 正在填满

​

限制

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

​

相关资源

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

​

版本历史