用 Agent View 管理多个代理¶

一句话概括： 在一个界面上派发和管理多个 Claude Code 会话。Agent View 展示每个会话正在做什么，以及哪些需要你介入。

Agent View 是后台会话的统一控制台。 通过 claude agents 打开，你可以看到所有后台会话的实时状态：正在运行的、需要你输入的、已完成的。你可以派发新会话、一目了然地掌握进度，只在需要时才介入。每个后台会话都是一个完整的 Claude Code 对话，不依赖终端持续运行——随时打开、回复、离开。

适用场景：多个独立任务并行推进。 比如同时派发一个 Bug 修复、一个 PR Review、一个 Flaky Test 排查，各自独立运行，你只需在某行显示"需要输入"或已有结果时回来查看。

当你想深入某个会话的完整对话时，可以 attach 到对应的行。

如需比较 Agent View 与子代理、代理团队、Worktree 的区别，参见 并行运行代理。

注意： Agent View 处于研究预览阶段，需要 Claude Code v2.1.139 或更高版本。用 claude --version 查看版本。界面和快捷键可能随版本演进而变化。

本文涵盖：

• 快速上手：给 Claude 一个后台任务，监控进度，需要时介入
• 用 Agent View 监控会话：状态图标、Peek 与回复、Attach、组织列表、快捷键
• 派发新代理：从 Agent View、从会话内部、从 Shell 启动
• 从 Shell 管理会话
• 后台会话的托管机制：Supervisor 进程

快速上手¶

核心循环：派发 -> 观察 -> Peek/回复 -> Attach。 下面演示完整流程。派发的会话在你关闭 Agent View 后继续运行，随时可以回来查看。

第一步：打开 Agent View¶

在终端运行：

claude agents

Agent View 打开后，底部有输入框，表格随着会话启动逐步填充。按 Esc 随时退出回到 Shell；如果你是通过 ← 将会话放入后台而打开的 Agent View，Esc 会返回到那个对话而非退出。会话在你离开期间持续运行，下次打开时重新出现。

第二步：派发一个会话¶

输入任务描述并按 Enter。一个新的后台会话启动并显示为一行，标记其当前状态（工作中/等待输入/已完成）。新会话使用 Agent View 顶栏显示的模型，以及你在该目录下运行 claude 时相同的权限模式。

每次输入都会启动一个全新会话。再输入一个 prompt 按 Enter 会启动第二个并行会话，而不是给第一个发送后续消息。可以这样同时运行多个。

每个会话独立消耗你的订阅配额，派发大量会话前请参阅 限制。

第三步：Peek 与回复¶

用方向键选中一行，按 Space 打开 Peek 面板。它显示会话最近的输出或正在等待的问题，而非完整对话。输入回复按 Enter 即可发送，无需离开 Agent View。

第四步：Attach 与 Detach¶

在选中行按 Enter 或 → 进行 Attach。终端切换为完整的交互式 Claude Code 会话。在空 prompt 上按 ← 即可 Detach 回到列表。

第五步：把现有会话放入后台¶

在已有会话中运行 /bg，或在空 prompt 上按 ←，会话转入后台并打开 Agent View。会话继续运行，和你派发的会话并列显示。

你可以把 claude agents 作为主入口：所有任务都从 Agent View 派发，需要完整对话时 Attach，按 ← 回到列表。

普通 claude 会话的 Footer 也会显示后台代理计数。 prompt Footer 中的 ← 提示会标注等待你输入的后台代理数，如 ← 2 agents；无需输入时恢复为 ← for agents。超过 99 显示为 99+。计数约每十秒刷新一次，获得焦点时立即刷新。数量变化时短暂变色，代理完成时也会闪动；当后台会话完成且无等待输入时会短暂显示完成数如 ← 2 done。这些闪动在 prefersReducedMotion 设置开启时关闭，屏幕阅读器模式下隐藏整个提示。该计数在所有 Provider 上可用，包括 Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry。

用 Agent View 监控会话¶

Agent View 按状态分组列出所有后台会话。 运行 claude agents 打开，占据整个终端，每行显示会话名称、当前活动和存活时长（从创建时算起；已完成会话的时长冻结为运行耗时）。置顶的和需要你输入的排在最前。

会话名称会以该会话通过 /color 设置的颜色着色，包括通过 ← 或 /background 放入后台的会话。

默认展示所有项目的后台会话。 不论你在哪个目录打开 Agent View，所有后台会话都会出现。要限定范围，使用 --cwd（需 v2.1.141+）：

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

只显示在该目录下启动的会话。已移入 ~/projects/my-app/.claude/worktrees/ 下 Worktree 的会话仍算属于 ~/projects/my-app。

在其他终端打开的交互式会话不会出现，除非你将它们放入后台。子代理和队友不会作为单独行显示。

Pinned
  ✽ clawd walk cycle          Write assets/sprites/clawd-walk.png           3m

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

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

Working
  ✽ collision detection       Edit src/physics/CollisionSystem.ts           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

读取会话状态¶

每行开头的图标通过颜色和动画指示状态：

图标形状表示底层进程是否存活：

行右侧可能出现的 PR #N 标签是会话创建的 PR 状态，不属于状态图标。多个 PR 时显示计数如 3 PRs。

终端标签页标题反映等待输入的数量： 如 2 awaiting input · claude agents，无等待时显示 claude agents。

Agent View 打开时会发送通知。 当本地后台会话开始需要输入、完成或失败时，Claude Code 通过你配置的终端通知渠道发送通知。按计划运行的会话（如 /loop 会话）仅在需要输入时通知。通知使用与 Claude Code 其他部分相同的 preferredNotifChannel 设置，并触发 Notification Hook（类型为 agent_needs_input 或 agent_completed）。

后台会话不依赖任何终端窗口。 独立的 Supervisor 进程 托管它们，你可以关闭 Agent View、关闭 Shell、启动新的交互会话，派发的任务继续运行。

会话状态跨更新和重启持久化。 机器休眠时会话也会保留，唤醒后进程恢复，Supervisor 重新连接。关机则会停止运行中的会话，参见关机后会话显示失败了解恢复方法。

中途响应中遇到休眠导致无响应的会话，在你打开时 Supervisor 会重启其进程，从中断处继续响应。

行摘要¶

一行摘要由 Haiku 级模型生成。 让你无需打开完整对话就知道会话在做什么、需要什么、产出了什么。

工作中的行显示会话声称在做什么，被阻塞的行显示它正在问的问题。会话活跃工作时，行文本最多每 15 秒从会话自身输出刷新一次（不发送模型请求），每个 Turn 结束时模型重新写一次摘要。长 Turn 期间模型也会每几分钟重写一次，避免繁忙行长时间显示过时内容。摘要文本填满行的剩余宽度，被终端右边缘截断的部分可打开 Peek 面板查看。

按目录分组时，摘要前带有状态着色词，如 Needs input · double jump or wall climb?。默认按状态分组时组标题已标明状态，行内只显示摘要。

从 v2.1.161 起，当会话同时运行多个并行工作项（如子代理、后台 Shell 命令、监控器）时，摘要前会显示 done/total 计数如 2/5。

计费方式： 每个 Turn 结束的摘要和每次中途重写都是一次短 Haiku 级请求，通过你的正常 Provider 计费，遵循与会话本身相同的数据使用条款。15 秒间隔的更新复用会话自身输出，不发送请求。在 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 及自定义网关等第三方 Provider 上，如果没有配置 Haiku 模型，请求会回退到会话的主模型。用 ANTHROPIC_DEFAULT_HAIKU_MODEL 设置这些摘要使用的模型。

PR 状态¶

会话创建 PR 后，行右侧出现 #1234 标签。 在支持超链接的终端中可点击。发送后续消息后标签保留，行内容恢复为实时进度。在 Worktree 中隔离变更的后台会话会自行打开 PR；文件编辑的隔离方式涵盖何时发生以及会话不会在未询问的情况下做什么。

在已有 PR 上工作的会话也会链接到它。用 gh 编辑、评论、关闭或标记 PR ready 都会链接命令输出中提到的 PR。gh pr checkout 或 push 到有开放 PR 的分支时通过 gh pr view 查找该分支来链接。gh pr merge 是常见例外——因为它只将结果打印到交互终端。

多个 PR 时显示计数如 3 PRs，颜色取最需关注的开放 PR。打开 Peek 面板可查看全部。

PR 编号颜色对应状态：

对大多数任务来说，这一列就是你收取结果的地方：PR 编号变绿时去 Review 和合并即可。

Peek 与回复¶

按 Space 打开 Peek 面板，快速查看会话需要什么。 面板以行被截断的那句话开头，具体内容取决于会话状态：

• 等待你的会话：显示其具体问题，上方有回复输入框
• 已完成的会话：显示结果
• 工作中的会话：显示完整状态句

之后列出会话关联的所有 PR。等待你输入的会话在 PR 下方显示等待时长如 waiting 3m——这是面板中唯一的时间。行右侧的时间是另一个数字：从会话启动算起。

大多数时候 Peek 面板就够了，不需要打开完整对话。

在面板中回复： 输入回复按 Enter 发送。会话提出多选题时，面板显示编号列表，按数字键选择。权限提示以文本描述会话想运行什么（无编号选项），输入回复作答，或 Attach 后用标准 prompt 回答。对其他阻塞会话，按 Tab 填充建议回复，可编辑后发送。回复前加 ! 可发送一条 Bash 命令。

回复无法送达时会保存。 如果后台服务不可达或发送失败，回复会被保存，在会话进程下次启动时作为其下一个 prompt 发送，错误消息会说明回复已保存。! 前缀的回复不保存，因为保存的文本会作为普通 prompt 而非 Bash 命令到达会话。

启用语音听写后，回复输入框聚焦时按住或点击 Push-to-talk 键可以用语音回复。派发输入框同样支持。

按 ↑ ↓ 在相邻会话间 Peek 而不关闭面板，按 → 进入 Attach。

Attach 到会话¶

按 Enter 或 → 进入完整交互会话。 Agent View 被替换为完整会话。Attach 时 Claude 会简要回顾你不在期间发生的事。

Attach 后，会话和普通 Claude Code 会话完全一样：所有命令、快捷键和功能都可用，有以下例外。

Attach 时，/install-github-app 和 /mcp 设置列表正常工作，因为有人在终端可以完成对话框。无人 Attach 时这些命令无法打开对话框，会话出现在 Agent View 的 Needs input 下，行显示 open this session to manage MCP servers。Attach 后重新运行命令即可；Attach 时 needs-input 行自动清除。/mcp reconnect <server>、/mcp enable、/mcp disable 无论是否 Attach 都可正常工作。

Attach 的会话始终以全屏模式渲染，与 tui 设置无关，因为后台会话没有终端回滚缓冲区。用 PgUp、PgDn 或鼠标滚轮滚动，按 Ctrl+O 进入 Transcript 模式。终端原生滚动和 tmux copy mode 只显示当前视口。

Detach 回到 Agent View： 在空 prompt 上按 ←，或运行 /exit，无论是从 Agent View Attach 的还是从 Shell 用 claude attach <id> 打开的。

Windows 注意： 如果你在 Attach 后约半秒内按 ←，Claude Code 会显示 Ambiguous ←, press again to detach，因为终端可能重发了 Attach 前的按键。再按一次 ← 即可 Detach。

Ctrl+Z 也可 Detach，但回到你的起点——从 Agent View Attach 的回 Agent View，从 Shell claude attach 的回 Shell。对话框获得焦点且 ← 无响应时用 Ctrl+Z。

Ctrl+C 保持标准中断行为：取消正在运行的响应或 ! Shell 命令，而非 Detach。在空 prompt 上连按两次 Ctrl+C 则 Detach，和普通会话一样。

Detach 不会停止后台会话。 ←、Ctrl+Z、/exit、双击 Ctrl+C 或 Ctrl+D 都只是离开会话，会话继续运行。要终止会话，运行 /stop。

从前台会话按 ← 可直接进入 Agent View。 在前台会话（你在终端中直接启动的，而非从 Agent View Attach 的）中，空 prompt 上按 ← 会将会话放入后台并打开 Agent View，选中该行，方便切换会话。如果你是在删除 prompt 末尾文字或浏览 prompt 历史后立即按 ←，Claude Code 会要求确认：第一次按显示 Press ← again to open agents（Attach 状态下为 Press ← again to go back to agents），第二次才切换。

按 ← 将前台会话放入后台时，Agent View 显示 Your conversation moved to the background，该行已选中。此时你可以：

• 按 Enter 重新打开对话
• 按 Esc 撤销切换，返回对话（如果显示 Still starting — try again in a moment，稍后再按）
• 按 Ctrl+C 两次退出到 Shell

如果有工具正在运行时按 ←，Claude Code 会等最多约十秒让其完成再放入后台，响应继续在后台会话中进行。再按一次 ← 立即放入后台。子代理运行期间不受十秒限制——Claude Code 持续等待以便其工作转移，并显示 Still backgrounding after the current tool；再按 ← 可不等待直接放入后台（子代理会从头重启）。

Claude 的任务列表随对话移到后台会话，返回该行时 checklist 完好无损。你按 ← 离开的那一行在你用方向键或鼠标移动选择后仍保持加粗不暗淡的名称，方便辨识来源。

可在 /config 中关闭此快捷键（leftArrowOpensAgents 设置）。

组织列表¶

Agent View 按状态分组，需要输入的排在最上。 Ready for review 和 Needs input 在 Working 和 Completed 之上。这些分组名和状态不完全对应：有未关闭 PR 的会话进入 Ready for review，Completed 收集已完成、失败和已停止的会话。

按 Ctrl+S 切换为按目录分组。选择跨次运行持久化。

组内操作：

• Ctrl+T：置顶会话并保持其进程运行
• Shift+↑ / Shift+↓：调整顺序
• Ctrl+R：重命名会话
• 在组标题上按 Enter：折叠该组

删除会话： 按 Ctrl+X 停止，两秒内再按 Ctrl+X 删除。在组标题上按 Ctrl+X 确认后删除该组所有会话。

删除操作会移除 Agent View 中的会话。如果 Claude 为该会话创建了 Worktree，删除会一并移除 Worktree 及其未提交的更改——请先 push 或 commit 你想保留的工作。你自己创建的 Worktree 不受影响。对话记录保留在本地，可通过 claude --resume 访问。

删除不会移除有未推送 commit 的 Worktree，也不会移除被另一个运行中会话占用或锁定的 Worktree。Claude Code 会保留该 Worktree 和会话行，Footer 显示保留路径和原因。推送 commit 或关闭另一个会话后再次删除。

删除被拒绝时，行显示 not deleted 及原因；无法移除的 Worktree 会报告底层 git 错误。git 不再识别的 Worktree（如被 git worktree prune 移除记录的）不阻止删除：会话被删除，Worktree 目录保留在磁盘上，Footer 显示其路径。

删除也会清除 Supervisor 会话列表中的条目，无论通过 Ctrl+X 还是 Shell 中的 claude rm 删除，移除跨 Supervisor 重启持久化。

恢复已删除的会话（v2.1.212+）： 在派发输入框输入 /resume，打开一个选择器，列出当前 Agent View 所在仓库的历史会话（最新在前），包括已从列表删除的；已有行的会话不列出。↑/↓ 移动选择，Enter 将选中会话恢复为后台会话重新出现为一行，Esc 关闭选择器。

选择器只对裸 /resume 生效。以下情况显示 attach to a session to run it 提示：

• /resume 后跟 ID 或搜索词
• Agent View 用 --cwd 限定范围
• Agent View 用 --safe-mode 启动
• Agent View 用 --permission-mode 或 --settings 等标志启动

较旧的已完成会话会折叠为 … N more 行。失败的和有未关闭 PR 的始终保持可见。Completed 组填满存活组之后剩余的垂直空间，在短终端上标题压缩为单行摘要以确保工作中和需要输入的会话保持可见。

筛选会话¶

在派发输入框输入内容进行筛选：

快捷键¶

在 Agent View 中按 ? 查看所有快捷键。以下是汇总：

派发新代理¶

你可以从 Agent View 派发、从已有会话放入后台、或直接从 Shell 启动。

从 Agent View 派发¶

在底部输入框输入 prompt 按 Enter 启动新后台会话。 会话名由 Haiku 级模型自动生成；之后可用 Ctrl+R 重命名。会话后来获得的名称也会显示在行上，包括你在该会话中接受计划时 Claude 推导出的名称。

可在 prompt 中粘贴图片，将截图或示意图附带到任务中。粘贴超过 800 字符或超过两行的文本会折叠为 [Pasted text #N] 占位符保持输入单行，完整文本在派发时发送。再次粘贴同样文本可展开占位符以便编辑。

通过前缀或引用控制会话启动方式：

少数命令在 Agent View 本身执行而非派发：

• /exit 和 /quit 关闭 Agent View
• /logout 登出
• /model 设置派发模型
• /login 打开登录对话框，无需 Attach 到会话即可重新登录
• 裸 /resume（或别名 /continue）打开仓库历史会话选择器，将其恢复为后台会话。需 v2.1.212+

Skills、自定义命令和展开型内置命令如 /init 作为首个 prompt 发送给新后台会话。其他内置命令显示 attach to a session to run it 提示，你输入的内容保留在输入框中方便编辑。

将重复任务打包为 Skill，就能从 Agent View 反复启动同一工作流而无需重新输入 prompt。

当同一个 @name 同时匹配子代理和兄弟仓库时，子代理优先。首词裸匹配也适用，所以如果 prompt 恰好以某个子代理名称开头，会派发该子代理而非当作普通文本。用 @ 形式来明确指定，或换个词开头避免匹配。

派发到指定目录¶

新会话默认在你打开 Agent View 的目录运行。要指定其他目录：

• 在目标目录下打开 claude agents。
• 在包含多个仓库的父目录下打开 claude agents，prompt 中用 @<repo> 引用目标仓库。输入 @ 会列出以下目标：
• 启动目录下一级的 Git 仓库
• 启动仓库在其目录树内的已注册 Git Worktree，如 Claude 在 .claude/worktrees/ 下创建的，以其 checkout 的分支名标注。用 git worktree add ../feature 添加在仓库外部的 Worktree 不列出
• 任何已有会话在列表中的目录
• 目录名含空格的不列出
• 从 Shell 中 cd 到目标目录，运行 claude --bg "<prompt>"。

按目录分组时，高亮行所在的目录成为派发目标，可以直接滚动到一个分组后派发，无需重新输入路径。

从会话内部派发¶

两个命令可以将工作从当前会话移到后台：/background 发送当前对话到后台释放终端，/fork 发送副本到后台而你继续在原处工作。

将会话发送到后台¶

运行 /background 或其别名 /bg 将当前会话转入后台。 可附带 prompt 如 /bg run the test suite and fix any failures 给出一个最后指令。如果 Claude 正在回复时你运行 /bg，回复会在后台继续。

退出一个仍有后台工作运行的会话（如子代理、后台 Shell 命令、工作流或监控器）时，会显示 Background work is running 对话框而非立即退出。选择 Move to background and exit 以 /background 的方式将会话放入后台并返回 Shell。Agent View 关闭时不显示此选项。

用 /fork 复制会话¶

运行 /fork 将当前对话复制到新后台会话，原对话继续运行。 副本包含截至当前的所有对话内容、工作目录、模型、权限模式、effort 级别，以及会话中添加的目录和"不再询问"权限授予，出现为 Agent View 中独立的一行。此后两个会话独立：副本的操作不影响原对话。需 v2.1.212+；v2.1.161 到 v2.1.211 上 /fork 启动分叉子代理，现已更名为 /subtask。Agent View 关闭时 /fork 保留分叉子代理行为，/subtask 不可用。

可附带 prompt 如 /fork open a draft pull request with the work so far，副本立即开始工作。不带 prompt 时副本等待首个指令：在 claude agents 中选中其行按 Space 发送，或运行 claude attach <id>。等待时行显示 space to send it a prompt。

和其他派发的会话一样，副本在编辑文件前移入自己的 Worktree。当前会话本身运行在一个有 main working tree 可返回的链接 Worktree 中时，副本在 main working tree 中运行，两个会话不编辑同一个 checkout。Bare-repository 布局中没有 main working tree，副本留在原地，/fork 确认信息会说明它编辑同一个 checkout。

使用了副本无法继承的启动标志（如替换的系统 prompt 或 --tools 白名单）的会话无法 fork；Claude Code 会说明原因而非制作不完整的副本。从 Agent View 派发的会话可正常 fork：副本使用与源会话相同的代理定义和追加指令。

放入后台时携带的内容¶

放入后台会启动一个新进程从保存的对话恢复，进行中的工作随之转移： 运行中的后台 Shell 命令、后台化的子代理、动态工作流和用 /loop 创建的定时任务全部转移并继续运行。子代理连同其启动的所有工作一起转移，所以只有其全部工作都能移动时才会转移。要停止进行中的工作而非转移，设置 CLAUDE_DISABLE_ADOPT=1 环境变量；Claude Code 会在放入后台前要求确认。

无法转移的工作（如运行中的监控器）会被停止，拥有监控器的后台化子代理也随之停止。有这类工作运行时 Claude Code 显示 Background this session? 对话框让你确认。

进入后台后，会话可以启动新的子代理、监控器和后台命令，后续的 Detach/Reattach 期间它们继续运行。

原始启动的配置标志会随会话传递到后台：

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

会话中通过 /add-dir 添加的目录同样传递。

--allow-dangerously-skip-permissions 传递后使 bypassPermissions 在后台会话中可用，但不授予额外权限。该模式仍需要首次交互式接受，详见权限模式、模型与 Effort。

从 Shell 派发¶

传 --bg 或 --background 直接启动后台会话：

claude --bg "investigate the flaky SettingsChangeDetector test"

prompt 是位置参数而非 -p 值。Claude Code 拒绝 --bg 与 -p/--print 组合，因为 --print 不启动 claude agents 可 Attach 的交互式会话。

要以特定子代理作为会话主代理，组合 --bg 和 --agent：

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

如果名称不匹配任何子代理，启动失败：Claude Code 打印 no agent named 警告并仍报告会话已放入后台，但会话立即以 --agent '<name>' not found 错误退出。v2.1.191 之前 Claude Code 会用默认代理运行。

传 --name 设置显示名称：

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

启动后 Claude 打印会话短 ID 和管理命令。后台服务未运行时可能先打印 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 会话，派发输入框首字符输入 !。 之后输入的内容就是命令。例如在 Agent View 输入框派发 pytest -x：

! pytest -x

按 Enter 启动。也可从 Shell 用 --exec 启动：

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

命令以 PTY 作业运行，在 Agent View 中显示为一行，最新输出行作为状态。Shell 作业直接运行命令代替 Claude，不调用模型，输出不发送到任何会话。

查看输出：Attach 到该行、按 Space Peek、或运行 claude logs <id>。捕获的输出保存在内存中不写入磁盘。命令退出约 5 分钟后行和输出自动清理，请在此之前读取。

文件编辑的隔离方式¶

每个后台会话在编辑文件前，Claude 会将其移入独立的 Git Worktree。 路径在 .claude/worktrees/ 下，这样并行会话可以读同一个 checkout，但各自写入自己的副本。

以下情况 Claude 跳过 Worktree：

• 会话已经在一个链接的 Git Worktree 中（不论是 Claude 创建的还是你用 git worktree add 创建的）
• 工作目录不是 Git 仓库且没有配置 WorktreeCreate Hook
• 写入操作在工作目录之外

要关闭 Worktree 隔离： 设置 worktree.bgIsolation 为 "none"。后台会话将直接编辑你的工作副本。在项目的 .claude/settings.json 中添加：

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

注意： worktree.bgIsolation 设置需要 Claude Code v2.1.143 或更高版本。

非 Git 仓库中，会话直接写入工作目录，彼此不隔离，避免派发编辑同一文件的并行会话。使用其他版本控制系统时，配置 WorktreeCreate Hook 即可实现相同隔离。Hook 在非 Git 仓库目录中失败时，会话跳过隔离直接就地编辑；在 Git 仓库中写入会保持阻塞直到隔离完成。

删除会话对 Worktree 的处理取决于删除方式和 Worktree 内容：

查看会话 Worktree 路径：Peek 或 Attach 后查看工作目录。

后台会话派生的子代理继承会话的工作目录，其文件编辑落在会话的 Worktree 中。要给子代理单独的 Worktree，在其 frontmatter 中设置 isolation: worktree 或传 isolation: "worktree"。

隔离代码变更的后台会话还会自动 commit、push 分支并开 draft PR，无需停下来询问。 行的 #N 标签在 PR 打开时出现。它不会 push 到 main/master，不会 force-push 或 merge，当你明确说不要开 PR 或仓库无 remote 时跳过。

未自行隔离的会话（isolation 设为 "none"、Worktree 移动失败、或在已存在的 Worktree 中启动的会话）仍会在 commit 或切换分支前询问。

设置模型¶

Agent View 顶栏的模型名是派发默认值。 来自用户设置中的 model 设置。通过 /model 选择器设置，或直接编辑。

要在打开 Agent View 时覆盖，传 --model。参见权限模式、模型与 Effort。

从 Agent View 内部临时修改派发默认值： 在派发输入框输入 /model 加模型名按 Enter。顶栏更新显示该模型并标记 (session)，后续派发使用它。输入 /model default 清除覆盖。此覆盖仅在当前 claude agents 运行期间有效，不写入设置文件（需 v2.1.172+）。例如：

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

每个后台会话可使用不同模型。 单独覆盖方式：

• 从 Shell：claude --bg 时传 --model。
• Attach 后运行 /model 切换：从选择器选或输入 /model <name> 保存为新会话默认值，除非在选择器中按 s 做仅限该会话的切换。仅限会话的切换在 respawn 后保留。
• 派发 frontmatter 中设置了 model 字段的子代理。

权限模式、模型与 Effort¶

后台会话从其运行目录读取设置，和在该目录运行 claude 一样。 包括项目设置中的 env 值，所以项目中设置的 ANTHROPIC_MODEL 或 Provider 变量对后台会话生效。

云 Provider 选择（如 CLAUDE_CODE_USE_BEDROCK 或 CLAUDE_CODE_USE_VERTEX）和 ANTHROPIC_DEFAULT_*_MODEL 别名来自派发会话的 Shell。如果在该 Shell 中导出了 CLAUDE_CODE_EXTRA_BODY 请求体覆盖，也会传递到会话。网关 ANTHROPIC_BASE_URL 也能到达会话，条件参见 Supervisor 进程了解后台会话如何获取 Provider 设置和凭证。

权限模式取决于启动方式。 用 /bg 或 ← 放入后台的会话保持当前权限模式（如 acceptEdits 或 auto）。从 Agent View 输入框或 claude --bg 派发的使用该目录设置中的 defaultMode，或派发的子代理 frontmatter 中的 permissionMode。

权限模式、模型和 Effort 以及携带的配置标志在 Supervisor 停止并重启进程后仍然保留。用 claude --bg --dangerously-skip-permissions 或 claude --bg --permission-mode bypassPermissions 启动的会话在重启后保持 bypassPermissions（而非回退到目录的 defaultMode）；会话中通过 /model 或 /effort 修改的也会保留。

来自 effortLevel 设置而非 --effort 或 /effort 的 effort 级别不固定在派发时：为会话启动的每个进程都重新读取该设置，所以编辑 settings.json 中的 effortLevel 会影响用 ← 或 /bg 放入后台的会话及其后续重启。

用 /rename 或 Ctrl+R 设置的名称也在重启后保留，claude --resume <name> 仍可解析到该会话。

要为从 Agent View 派发的所有会话设置默认值： 打开时传 --permission-mode、--model、--effort 或 --agent：

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

--effort 接受与顶层 --effort 标志相同的值，包括 ultracode。

--agent 设置 prompt 未指定子代理时使用的默认子代理（通过 @name 或首词）。默认为 agent 设置（如已设），否则内置的 claude 代理。prompt 中指定子代理会覆盖两者。

claude agents 也接受 --dangerously-skip-permissions（等同 --permission-mode bypassPermissions）和 --allow-dangerously-skip-permissions（使 bypassPermissions 在每个会话的 Shift+Tab 循环中可用但不以该模式启动）。两者与顶层 CLI 标志一致。

当前生效的默认值显示在派发输入框下方的 Footer 中。

使用 bypassPermissions 前需先交互式接受免责声明。 claude --bg --permission-mode bypassPermissions 在你交互式运行 claude --dangerously-skip-permissions 接受前会被拒绝，因为该模式允许无人监管的会话不经批准执行操作。传 --dangerously-skip-permissions 或 --permission-mode bypassPermissions 给 claude agents 时显示相同免责声明，接受后对从 View 启动的会话应用 bypassPermissions。传 --allow-dangerously-skip-permissions 也显示免责声明，接受后使 bypassPermissions 在这些会话的 Shift+Tab 循环中可用但不以该模式启动。

这些标志跨版本添加。早期版本会报未知选项错误：

v2.1.157 之前，Agent View 忽略 agent 设置，派发内置 claude 代理。

设置、插件与 MCP 服务器¶

Agent View 接受与 claude 相同的配置标志。 Agent View 将 --settings 和 --plugin-dir 应用于自身，并将所有配置标志传递给其派发的会话，使这些会话可以使用你加载的插件或 MCP 服务器。

对 --add-dir、--plugin-dir 或 --mcp-config 每个值重复一次标志。claude agents 不支持空格分隔多值的写法如 --add-dir a b c。

--settings 和 --plugin-dir 可以放在 agents 前面或后面。--add-dir 和 --mcp-config 应放在 agents 后面：放在前面时 claude agents --json 会报 unknown option 错误。v2.1.200 之前，--plugin-dir 应放在 agents 前面：放后面时虽然传递给派发的会话，但不会加载插件的 agents 和 skills 到 Agent View 自身的自动补全中。

示例：

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

--settings 接受文件路径或内联 JSON 字符串。文件路径必须指向存在的文件，否则 Claude Code 以 Settings file not found 错误退出。

从 Shell 管理会话¶

每个后台会话有一个短 ID，可从 Shell 使用。 ID 在 claude --bg 启动时打印，也是 ~/.claude/jobs/ 下的目录名。这些命令适合脚本化使用或不想打开 Agent View 时。

以 JSON 列出会话¶

claude agents --json 打印活跃会话为 JSON 数组并退出： 每个存活会话，加上仍在工作或阻塞的后台会话（即使其进程已退出）。加 --all 包含已完成的后台会话，加 --cwd <path> 限定为该目录下启动的会话。

每个条目描述一个会话：

后台会话的托管机制¶

Agent View 中列出的每个会话都是后台会话，不论你当前是否 Attach。 直接运行 claude 启动的会话绑定在终端上，终端关闭即结束——除非你将其放入后台。

Supervisor 进程¶

后台会话由每用户独立的 Supervisor 进程托管，与你的终端和 Agent View 分离。 首次放入后台或打开 Agent View 时自动启动，无需手动管理。

当更新替换或移除了运行中 Claude Code 进程的二进制时，该进程从另一个已安装副本（如已安装的 claude 启动器或磁盘上最新版本）启动 Supervisor。

Supervisor 维护一个预热 Worker 进程，使得从 Agent View 或 claude --bg 派发时无需冷启动延迟。派发时 Supervisor 将预热 Worker 分配给你的会话，应用该会话的目录、设置和凭证，然后启动一个替代 Worker 准备下次派发。如果没有健康的预热 Worker，Supervisor 启动一个全新进程。

Supervisor 及其会话使用与交互会话相同的存储凭证，不会建立模型 API 之外的网络连接。Provider 选择变量（如 CLAUDE_CODE_USE_BEDROCK）和 ANTHROPIC_DEFAULT_*_MODEL 别名从派发该会话的 Shell 读取并应用到其 Worker。派发 Shell 的 PATH 也同样应用，使得会话运行的 Shell 命令能找到与你终端相同的工具。

后台会话不继承网关端点变量。 如 ANTHROPIC_BASE_URL、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 的基础 URL 变量不从启动 Supervisor 的 Shell 继承。不带网关导出时，会话使用存储的凭证和项目目录设置中的 env 值。要让项目中所有后台会话使用 LLM 网关，在项目的 .claude/settings.json env 块中设置 ANTHROPIC_BASE_URL。

网关转发条件（v2.1.203+）： 如果你在派发的 Shell 中导出了网关 ANTHROPIC_BASE_URL，它能到达该会话的 Worker（连同 ANTHROPIC_CUSTOM_HEADERS 和伴随的凭证），需同时满足：

• Supervisor 从带有相同网关的环境启动。Supervisor 从首次打开 Agent View 或派发后台会话的 Shell 捕获环境，所以从网关 Shell 启动即给予该环境。
• 会话被派发到你正在派发的目录，或是你自己的会话通过 ← 或 /background 放入后台。用 @repo 或 --cwd 派发到其他目录不携带 Shell 的网关；该项目的 settings.json env 块提供端点。

当 Supervisor 环境携带不同网关或无网关时，Worker 保持你的存储凭证指向默认端点，而非混合一个环境的凭证和另一个的端点。转发的端点仅应用于该存活进程，不写入磁盘。

当 Supervisor 停止空闲会话后你通过 Attach、Peek 或回复唤醒它时，在相同条件下再次转发你环境的网关。从无网关的 Shell 唤醒会话则根据设置和存储凭证重启。

v2.1.174 之前后台会话继承 Supervisor 启动 Shell 的这些变量。

每个后台会话是独立的 Claude Code 进程，由 Supervisor 管理而非绑定在你的终端上。活跃工作、等待输入或有终端 Attach 的会话保持进程运行。Supervisor 将运行中的后台 Shell 命令、子代理、动态工作流或监控器视为活跃工作，如 Dev Server 这样的长期运行进程会保持会话存活。

会话完成且 Detach 约一小时后，Supervisor 停止其进程以释放资源。 用 Ctrl+T 置顶的会话豁免，保持进程运行。对话和状态保存在磁盘上，下次 Attach、Peek 或回复时 Supervisor 从中断处启动新进程。所有会话完成且无终端连接时，Supervisor 自身退出，下次需要时重新启动。

Supervisor 还会重启意外退出的会话进程，有三道防护确保重启不会覆盖停止或处理过时输入：

• 磁盘状态显示为 done、failed 或 stopped 的会话不重启，除非有待发送的回复等待投递。
• 通过 ← 或 /background 放入后台的会话，其进程被外部终止（如 kill）时标记为 stopped 而非重启。通过任务派发的会话（Agent View 输入框或 claude --bg）仍会重启以完成派发的工作。
• 重启的会话被告知它是被重启的且你没有发送新消息，可以重新验证时间敏感上下文（如分支状态）后再继续。重启的 ← 或 /background 会话不恢复超过约一小时的中断响应；等待你的下一条消息。

会话进程停止、重启或更新时，其顶层后台工作会交接（包括 Windows 上），下一个为该会话启动的进程接管：

• 期间完成的后台 Shell 命令以完成状态报告并附带输出
• 动态工作流从中断处恢复
• 后台子代理从自身 transcript 恢复

状态仅存在于进程内部的工作（子代理启动的 Shell 命令、运行中的监控器）随进程停止而非交接。恢复的子代理可以重新启动它们。

删除会话会停止其交接的所有工作。要让会话的所有后台工作随进程停止而非交接，设置 CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF 环境变量为 1。

重启的进程能找到移入 Worktree 的会话对话：当 transcript 不在会话启动位置时，Claude Code 还会查看仓库的注册 Worktree。两处都找不到时，Claude Code 扫描你所有保存的会话 transcript 作为最后手段，从匹配的那个恢复。如果重启的会话只显示原始 prompt（Claude Code 误读 transcript 为空），对话 transcript 以 .orphaned- 前缀重命名而非删除，保留在你的机器上。

按 ← 创建但从未给 prompt 的空行，约 5 分钟后自动移除。claude --bg 启动的和等待初始化 prompt（如信任对话框）的会话不会被移除。

内存不足时， Supervisor 优先停止非置顶的空闲会话，只有释放无效时才停止置顶的空闲会话。

Supervisor 监视已安装的 Claude Code 二进制文件。 自动更新器替换后重启到新版本。这是本地文件监视而非网络检查。后台会话是独立进程，在重启期间继续运行，新 Supervisor 重新连接它们。置顶的空闲会话也会就地重启到新版本以获取更新。

新 Supervisor 接管后，还会分批在后台重启剩余空闲会话到新版本，在短暂延迟后（让跨重启 Attach 的终端先重新连接）。正在工作、等待输入或有终端 Attach 的会话不中断；下次进程重启时移到新版本。

这些重启只向更新版本移动。运行旧版本的 Supervisor 不会干扰使用新版本进程的会话；该会话保持新版本直到更新的 Supervisor 接管。

claude attach 在 Supervisor 重启会话期间会等待（无论是更新、卡住还是迁移），状态行如 Agent is updating to the new Claude Code… 显示等待内容和已过秒数，就绪后连接。约 60 秒后停止等待并报错。claude attach 在后台服务启动或重新连接时也会等待，等待期间完成的会话报告为 exited 而非 error。等待期间的终端调整在 Attach 完成后应用。

状态存储位置¶

会话状态存储在 Claude Code 配置目录下。 设置了 CLAUDE_CONFIG_DIR 时，Supervisor 使用该目录而非 ~/.claude，作为独立实例运行。

每个后台会话有 CLAUDE_JOB_DIR 环境变量指向其 ~/.claude/jobs/<id> 目录，Shell 命令可写入 $CLAUDE_JOB_DIR/tmp 而不与并行会话冲突。

运行 claude daemon status 可检查此状态。报告 Supervisor 是否可达、进程 ID 和版本、Socket 目录和后台会话数量。/doctor 也包含相同检查的摘要。

当运行中的 Supervisor 版本与你调用的 claude 版本不同（更新后 Supervisor 尚未重启）时，命令会发出警告并显示两个版本号，提示运行 claude daemon stop --any 切换到新版本。当 Claude Code 作为 OS 服务安装时，建议命令为 claude daemon stop（不带 --any 标志）。

会话跨版本不匹配保持完好：旧版 Claude Code 更新会话的 state.json 时保留其不识别的字段，会话始终保持列出。roster.json 中的会话列表也遵循相同规则，新版本启动的会话在 Supervisor 重启后仍可达且继续接受输入。

Windows 上，当 Daemon 的 pipe-key 文件被锁定或不可读时，claude daemon status 会展示底层文件错误而非通用连接失败。

关闭 Agent View¶

要完全关闭后台代理和 Agent View： 设置 disableAgentView 设置为 true 或设置 CLAUDE_CODE_DISABLE_AGENT_VIEW 环境变量。管理员可通过托管设置强制执行。

故障排除¶

claude agents 列出子代理而非打开 Agent View¶

如果 claude agents 打印计数和子代理列表后退出，说明当前环境不支持 Agent View。 运行 claude update 安装最新版本。

更新后仍无法打开，检查是否被设置或环境变量关闭。

Agent View 打开后无会话¶

派发首个会话前，Agent View 显示空的分区标题和说明文字，加上输入框上方的一行解释。 在底部输入框输入 prompt 按 Enter 派发第一个会话。

放入后台显示 Background this session? 对话框¶

按 ← 放入后台时显示 Background this session? 对话框， 说明会话有无法移到后台的进行中工作（如运行中的监控器），Claude Code 不会静默停止它。对话框列出将被停止的工作和将转移的任务计数。运行 /tasks 查看所有运行内容，然后确认放入后台或选择 Stay 让工作先完成。参见放入后台时携带的内容了解哪些任务类型转移哪些被停止。

Prompt 因过短被拒绝¶

派发输入框期望任务描述而非寒暄。 少于四个字符的 prompt 会被 Too short 提示拒绝，避免误按启动会话。描述你想让会话做什么，如 investigate the flaky checkout test。

关机后会话显示为失败¶

关机或重启会停止运行中的后台会话，下次打开时显示为失败。 Attach、Peek 或回复任何一个，会话从中断处重启。

休眠不会导致此问题。会话跨休眠保留，Supervisor 唤醒后重新连接。

Agent View 报告后台服务无响应¶

如果 Attach、Peek 或 claude logs 报告后台服务无响应，Supervisor 进程可能已卡住。 停止并让下次 claude agents 启动新的。要保留后台会话，传 --keep-workers：

claude daemon stop --any --keep-workers

新 Supervisor 重新连接正在运行的会话。不传 --keep-workers 则同时终止后台会话。--any 确认你要停止按需启动的 Supervisor 而非已安装的服务（后者是默认情况）。

启动后无法接受连接的 Supervisor 会自行退出并释放锁，下次 claude agents 无需手动停止即可启动新的。上述步骤适用于运行中但卡住的 Supervisor。

Windows 上如果 Supervisor 不响应停止请求，命令会打印其进程 ID。用 taskkill /PID <pid> 终止进程完成恢复。传了 --keep-workers 的后台会话仍会保留。

派发失败报 Could not resolve authentication method¶

如果后台派发报 Could not resolve authentication method 而交互会话正常认证， 说明接收派发的 Worker 未获取到凭证。v2.1.174+ 上 Supervisor 在分配预热 Worker 时提供新的凭证快照，此错误意味着 Supervisor 进程本身没有可用的存储凭证。确认你已运行 /login 或配置了 API Key，然后停止 Supervisor：

claude daemon stop --any --keep-workers

下次 claude agents 或 claude --bg 启动新 Supervisor 读取存储的凭证。如果你通过环境变量（如 ANTHROPIC_API_KEY）而非 /login 认证，确保在设置了该变量的 Shell 中运行。

参见错误参考获取完整原因和修复方法。v2.1.174 之前，闲置的预热 Worker 被分配时可能报此错误，即使凭证有效。升级即可恢复。

打开会话提示对话已在其他地方打开¶

打开一个 stopped 行时，如果其对话同时被另一个运行中的非交互式 Claude Code 进程持有（如仍在结束中的后台 Worker），会显示 This conversation is already open in another running Claude session，因为两个进程不能写同一个 transcript。在已持有对话的会话中回复，或退出它后再打开该行。你已输入的回复不会丢失，下次会话启动时发送。

打开会话提示无保存的 transcript¶

一个从其他对话放入后台并在首次响应完成前停止的会话没有可恢复的内容： 直到首次响应完成，对话仍只存在于源会话中。claude attach 拒绝打开并提示 This session has no saved transcript。

在 Agent View 中，打开该行会在列表下方显示 Press enter again to restart this session fresh。在同一行再按 Enter 以空对话重启会话，或从 Shell 运行 claude respawn <id>。

原始对话完好无损；用 claude --resume 恢复或继续在其中工作。详见错误参考。

会话在启动前失败并提示 possibly low memory¶

后台会话进程在完成启动前退出且主机内存不足时， 行状态显示退出信息并附带 possibly low memory — free some up and retry。

该提示是假设而非确认原因。仅在进程静默退出（未写错误、未被信号停止）且主机当时报告低内存时添加。进程写了错误再退出时，行显示该错误。

释放机器内存后，Attach、Peek 或回复该行，Supervisor 为会话启动新进程。内存持续不足时 Supervisor 也会自行停止空闲会话释放资源。

macOS 后台会话无法读取桌面、文稿或下载¶

macOS 上后台会话宿主作为独立进程运行，需单独请求受保护文件夹访问。 如果后台会话报 Operation not permitted 读取 ~/Desktop、~/Documents、~/Downloads 等路径，在系统设置 > 隐私与安全 > 文件和文件夹中授权，或启用完全磁盘访问。

使用原生安装器时，条目显示为 Claude Code，授权跨更新持久化。Homebrew 或 npm 等方式安装时，条目显示二进制路径，更新后可能需重新授权。

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

macOS 15 及更高版本上，系统在你授予 Local Network 权限之前会阻止进程访问本地网络设备。 后台会话中针对 LAN 地址的命令即使在前台终端可用，也可能因 connect: no route to host 失败。后台会话中首次连接本地网络地址的命令会触发 Claude Code 的 macOS Local Network 权限提示。授予一次后这些命令访问 LAN 主机的行为与前台终端一致。

Attach 后会话响应缓慢¶

会话完成且 Detach 约一小时后，Supervisor 停止其进程。 Attach 时从中断处启动新进程，立即切换到会话。正在工作、等待输入或置顶的会话不会被停止，用 Ctrl+T 置顶可保持响应速度。

进程启动期间，Claude Code 显示会话 transcript 的最后一屏（以 markdown、高亮代码块和暗化工具调用行渲染），上方有暗化 prompt 区域和 Session is starting 提示。就绪后实时会话替换它。

.claude/worktrees/ 目录膨胀¶

Agent View 中删除会话会移除 Claude 为其创建的 Worktree， 无法安全移除的 Worktree 连同其会话行保留以免成为孤儿。git 不再识别的 Worktree 目录在会话删除时留在磁盘上，手动移除不需要的残留目录。

claude rm 在有未提交更改时保留 Worktree 和会话行并打印路径。

在项目目录中用 git worktree list 列出残留项，用 git worktree remove <path> 移除。参见清理 Worktree。

限制¶

Agent View 处于研究预览阶段，有以下限制：

• 速率限制适用： 后台会话消耗的订阅用量与交互会话相同，并行 10 个代理大约消耗 10 倍配额。
• 会话是本地的： 后台会话运行在你的机器上。跨休眠保留，但关机会停止。
• Agent View 中删除会话会删除 Claude 创建的 Worktree： 删除前先 commit。有未推送 commit 的 Worktree 连同会话一起保留。claude rm 在有未提交更改时也保留 Worktree 和会话；你自己创建的 Worktree 始终保留。

相关资源¶

其他并行运行 Claude 的方式：

• 并行运行代理：Agent View 与子代理、代理团队、Worktree 的对比
• 代理团队：多个会话相互通信协作
• Web 端 Claude Code：在托管云环境而非本地运行会话

版本历史¶

Agent View 在研究预览期间快速演进。 如果你使用较旧版本，本页某些行为可能不同；特别是 claude agents 会对不支持的标志报 unknown option 错误。下表列出各标志和行为的添加时间。