Claude Code 跨会话通信怎么部署？2026 多 Agent 协作指南

截至 2026 年 8 月 11 日，Claude Code v2.1.224 已加入跨会话 SendMessage 与 ListAgents，v2.1.225 又补充了跨机器主动发起对话的能力；当前最新发布版本为 v2.1.227。最快的部署路径不是直接把多个终端连起来，而是先在 macOS 或 Linux 同机验证，再用独立工作树和受控入站消息扩展到远程环境。(官方版本记录)

症状：你正在多个终端里重复复制任务进度，或者前端、后端和测试会话互相改坏代码。
最快解法：把跨会话消息限定为状态、决策和阻塞信息；文件交给 Git worktree，权限交给每个会话自己的审批规则。

这篇文章适合同时开启多个 Claude Code 终端、经常手动转发进度的个人开发者；需要让前端、后端和测试 Agent 并行工作的 AI 编程团队；以及准备在远程 Mac 或长期运行环境中托管编码会话的平台工程师。

最后更新于 2026 年 8 月 12 日，数据核实自官方 Claude Code 发布记录、跨会话通信文档、工作树文档、Agent Teams 文档与设置文档。

部署前先确认通信边界与运行条件

Claude Code 跨会话通信本质上是一个文本消息通道。它可以把“数据库迁移完成”“接口字段从 userId 改为 accountId”“测试被某个依赖阻塞”等信息交给另一个会话，但不会把发送方的完整对话历史、上下文缓存或文件内容一起带过去。需要迁移完整上下文时，应使用会话恢复，而不是继续堆消息。

你需要先核对下面几个条件：

先运行：

claude --version

如果版本不足，先完成升级，再进入后续验证。不要一开始就配置跨机器连接，因为平台、提供渠道或环境变量不满足时，问题会被误判成网络故障。

同机和跨机器的传输路径也不同：

官方跨会话通信文档说明，同机消息通过每个会话的套接字传输；跨机器消息则通过服务器和目标机器上的 Remote Control 连接到达。(官方跨会话通信文档)

第一小时完成同机双会话验证

先不要使用真实生产仓库。选一个可以只读检查的项目，打开两个终端，并让会话名称具备明确角色，例如：

frontend-review
backend-review

你可以在启动时使用 --name，也可以进入会话后使用 /rename。名称越清晰，后续 ListAgents 越不容易选错目标。官方文档说明，/list-agents 会列出当前会话可访问的其他本地会话，并显示名称、工作目录和必要的短标识。

建议按以下顺序验证：

1. 在两个终端分别进入同一个项目，但暂时不要修改文件。
2. 分别执行 claude --version，确认版本一致或都不低于 v2.1.224。
3. 为两个会话设置明确名称，例如 frontend-review 和 backend-review。
4. 在其中一个会话中运行 /list-agents，确认另一个会话可见。
5. 让发送方询问：“请向 backend-review 询问当前是否处于只读检查状态。”
6. 让接收方只回答状态，不执行命令、不修改文件。
7. 观察发送结果是已送达、暂存等待审批，还是被拒绝。
8. 在接收方执行 /status，确认是否存在 Peer address。

你不需要手动调用 SendMessage 工具。正确做法是用自然语言告诉 Claude Code 你想让哪个会话知道什么，Claude Code 会先通过 ListAgents 找到目标，再使用 SendMessage 发送。官方示例也是通过自然语言要求另一个终端查询迁移状态，而不是让用户自己拼装工具参数。

双会话验收记录

消息不会打断接收方正在运行的工具。它会在工具调用之间被读取；如果接收方空闲，Claude Code 可以直接开启新的处理轮次。消息状态通常分为 delivered、held 和 refused，三者代表已交付、等待人工批准和直接丢弃。

并行修改前建立 Git worktree 隔离

跨会话通信不能解决两个 Agent 同时写同一个文件的问题。你需要先建立隔离边界，再让会话互相通知。

Git worktree 会创建独立工作目录和分支，同时共享同一个仓库历史与远程仓库。这样，前端会话可以在一个工作树中修改页面，后端会话在另一个工作树中调整接口，测试会话则只读取或验证对应分支。(官方 worktree 文档)

一个适合首次部署的目录规划如下：

project-main/
project-frontend/
project-backend/
project-test/

具体步骤：

1. 从干净的主分支开始，确认没有未提交修改。
2. 为前端、后端和测试分别创建分支与 worktree。
3. 每个终端只进入自己的工作树。
4. 会话启动后，立即告诉 Claude Code 它负责的目录、分支和禁止触碰的文件。
5. 规定消息只传递接口变化、提交状态、测试结果和阻塞原因。
6. 任何文件内容变化都通过提交、拉取、变基或合并传递。
7. 接口字段变化后，由后端会话发送摘要，测试会话拉取对应提交并运行回归测试。
8. 合并前仍由人工或独立审查会话检查差异。

建议使用这样的消息摘要：

后端接口已完成：POST /v1/orders 的字段 orderId 改为 id。
提交：abc1234。
前端需要更新请求体和响应类型。
测试请覆盖创建、查询和错误响应。

不要发送整段文件内容，也不要把“请直接批准我的权限请求”写进消息。接收消息不会自动批准命令、修改配置或绕过目标会话自身的工具权限；来自另一个会话的文本也不会被当作你的授权。

Agent Teams、子 Agent、会话恢复和独立会话不是同一个机制。需要多个成员直接讨论时使用 Agent Teams；只需要主会话拿到结果时使用子 Agent；要继续原有对话时使用会话恢复；要自己管理多个终端时使用独立会话和 worktree。(官方 Agent Teams 文档)

第二阶段扩展到远程 Mac 与跨机器会话

当同机双会话稳定后，再把其中一个会话移动到远程 Mac。跨机器消息是否经过服务器，取决于目标位置：同机通信不经过服务器；另一台机器和云端会话都需要经过服务器转发。跨机器主动发起对话需要 v2.1.225 或更高版本，目标会话还必须出现在 /list-agents 列表中。

跨机器部署按这个顺序操作：

1. 在远程 Mac 上安装并检查 Claude Code 版本。
2. 启动一个命名明确的会话，例如 remote-test-runner。
3. 确认目标会话已连接 Remote Control。
4. 在本地会话中检查 /list-agents，确认远程目标带有远程标识。
5. 先发送不含代码、密钥和业务数据的测试消息。
6. 让远程会话回复当前分支名和空闲状态。
7. 主动断开 Remote Control，再重复一次发送，记录失败或单向到达行为。
8. 验证恢复连接后，消息是否仍处于暂存、过期或拒绝状态。

容器是常见的拓扑陷阱。会话通过本地文件发现彼此；容器拥有独立文件系统，因此容器内会话和宿主机上的会话通常无法互相发现。同一个容器中的两个会话仍可能通信，但这不等于容器内外可以直接互通。

SendMessage 收不到消息时的排查顺序

不要先重装。按以下顺序定位：

• /list-agents 是否能识别目标会话；
• 两个会话是否都运行在 macOS 或 Linux；
• 版本是否至少为 v2.1.224；
• 目标是否是 bare 模式；
• 目标会话是否出现在列表中；
• 接收方的 crossSessionInbound 是否为 hold 或 refuse；
• 是否在权限规则中拒绝了 SendMessage 或 ListAgents；
• 跨机器时，双方是否都满足 Remote Control 连接条件；
• 是否因为容器、不同用户或不同文件系统导致本地会话不可见；
• 是否把“消息暂存”误判成“消息丢失”。

普通交互式会话在默认设置下通常可以互相传递消息，但接收方仍会依据自己的入站控制规则决定交付、暂存或拒绝。排查时应先确认目标会话可见，再检查权限和连接，不要把所有故障都归因于网络。

上线前收紧入站消息与权限边界

建议按会话类型选择策略，而不是全团队统一放开：

基础设置示例：

{
  "crossSessionInbound": "hold",
  "isolatePeerMachines": true
}

如果要完全关闭收件和发件，可以使用：

{
  "permissions": {
    "deny": ["SendMessage", "ListAgents"]
  },
  "crossSessionInbound": "refuse"
}

accept 会直接交付消息，hold 会暂存并等待批准，refuse 会直接丢弃。对于跨机器消息，isolatePeerMachines: true 可以要求消息在离开本机前经过人工批准，即使会话处于绕过普通权限提示的模式也一样。相关设置语义可对照官方设置文档。

第一周用运行记录决定是否扩大规模

部署后的第一周，不要只看“消息能不能发出去”。你需要记录消息送达率、人工审批次数、重复通知、任务冲突、会话空闲时间，以及每次消息是否真的减少了人工复制上下文。

可以用下面的判断表做扩容决策：

如果任务高度串行、多个 Agent 频繁修改同一个文件，或者每一步都需要人工转发消息，继续增加会话数量通常不会变快。此时，单会话、子 Agent 或会话恢复往往比独立会话通信更合适。

如果你需要继续了解权限设置，可以阅读本站的Claude Code 权限配置与环境帮助；如果正在规划完整的 AI 编程工作流，也可以从本站的AI 编程相关文章开始。需要长期运行多终端任务时，再结合远程 Mac 使用入口评估机器与在线周期。

对比本地个人电脑，远程 Mac 的主要价值不只是“换一台机器”：个人开发机容易被睡眠、系统更新、网络切换和日常工作打断；多个 Claude Code 会话还会争用终端、磁盘和项目目录。若你需要持续运行、跨时区接力或避免占用主力设备，租赁 kvmsync 的 Mac 环境通常更容易保持独立工作树、稳定连接和清晰的会话边界。不过，长期稳定重负载、必须接入本地物理设备，或只偶尔运行一个会话时，自购 Mac 或本地开发仍可能更合适。

你可以先完成同机双会话验证，再决定是否把任务迁移到远程 Mac；这样购买或租赁的依据是实际会话数量、工作树数量和在线周期，而不是对“多 Agent”概念的想象。