Mingyu's Library主页
2026年8月19日

第 13 课:跨会话通信(让你的多个会话互相传话)

日期:2026-08-19 前置:Claude Code v2.1.224+(@ 点名需 v2.1.232+,主动向另一台机器发起对话需 v2.1.225+);仅 macOS / Linux(含 WSL2),原生 Windows 不支持;Bedrock、AWS 上的 Claude Platform、Google Cloud Agent Platform、Microsoft Foundry 不支持。 官方文档:https://code.claude.com/docs/en/cross-session-messaging

这节课解决什么问题

你开三个终端并行干活:一个改 schema、一个写 API、一个跑迁移。以前 A 会话改崩了 B 依赖的东西,你得自己发现、自己去 B 那边复述一遍。现在 Claude 可以自己把这句话递过去。

注意它不是上下文共享:传过去的只有一段纯文本,不含对话历史,也不含文件。要搬整个上下文,那是 --resume(见第 10 课会话管理),不是这个。

技巧一(入门):先确认这台机器上「谁在」,再让 Claude 传话

# 在任意一个会话里,列出 Claude 能够到的所有 agent
/list-agents        # 等价别名:/peers

列表会包含四类:当前会话内的 subagents、本机其它 Claude Code 会话(含后台会话)、你的 Claude Code Web 云端会话(需本会话连着 Remote Control)、你其它机器上的 Remote Control 会话。每行给出「它应答的名字」和本机会话的工作目录(用来区分重名会话)。

传话不需要你手动调工具——Claude 自己用 ListAgents 找目标、用 SendMessage 送达。你只要用自然语言说明意图:

问一下我另一个终端里那个会话,迁移跑完了没有

把我们刚才做的改动讲给正在做 payments API 的那个会话听

第二个例子里你没规定措辞,Claude 自己组织消息内容,每次发出去的文本可能不同。

给会话起个好名字是这一切的前提:启动时 claude --name api-worker,或会话中 /rename api-worker。不起名字时 Claude Code 会用工作目录名生成,比如 my-app 目录下叫 my-app-3f。同名冲突时,先到先得,后来的会被改成变体名。

来源:https://code.claude.com/docs/en/cross-session-messaging

技巧二(常用):用 @ 精确点名,省掉一次 ListAgents

打 @ 再敲至少一个字母,会弹出本机其它活跃会话的候选(光打一个裸 @ 不会出现会话行),选中后 Claude Code 会插入 @api-worker 这样的 mention,并直接告诉 Claude 目标是谁——省掉先列一遍的开销。

告诉 @api-worker schema 迁移已经跑完了

典型的并行 worktree 场景(配合第 11 课的 worktree 用法):

# 终端 1
cd ~/repo-wt/schema && claude --name schema
# 终端 2
cd ~/repo-wt/api && claude --name api
# 终端 3:长任务,让它跑完自己汇报
cd ~/repo-wt/migrate && claude --name migrate

然后在终端 3 里:

迁移跑完后,把新增的列名和「现在 rebase 到 main 是安全的」这两点告诉 @api

对方收到的样子大致是这样一句纯文本,挂在发送方会话名下面:

Schema migration finished: the new column is tenant_id, and rebasing on main is safe now.

送达时机:接收方正在跑工具时不会被打断,消息在两次工具调用之间被读到;接收方空闲时,Claude Code 直接用这条消息开一个新回合。

技巧三(进阶):管住入站——crossSessionInbound 三档

别人的会话能往你这儿塞 prompt,这件事本身需要闸门。设置项 crossSessionInbound 有三个值:

值 行为
accept 每条都投递给 Claude
hold 只显示提示、不投递;之后若有 accept 生效,已扣住的消息会被释放
refuse 直接丢弃,不投递

除了写设置文件,也可以在 /config 里的 Messages from your other sessions 那一行选(需 v2.1.232+),选中的值会写进用户设置。注意:这个 key 不支持 /config crossSessionInbound=value 简写。

// .claude/settings.json —— 让一个无头 worker 无人值守地接收消息
{
  "crossSessionInbound": "accept"
}

# 更干净的做法:只给这一个 -p worker 开,不污染全局用户设置
claude -p "watch the test suite and report" \
  --name test-worker \
  --settings '{"crossSessionInbound":"accept"}'

没显式配置时的默认规则(值得记住,否则会遇到「消息发了没到」):Claude Code 按两边会话的权限模式分成「绕过权限提示」和「会提示权限」两类——

扣住时会弹审批对话框,超过 dialogExpiry(默认 5 分钟)未处理就关闭并丢弃。-p 会话弹不出对话框,同样按这个期限处理,可把 dialogExpiry 设为 "never" 让它保留到会话结束。

安全边界(这几条是设计上的硬保证,不是最佳实践建议): - 别的会话发来的消息 不算你的同意,不能替你回答待批准的权限提示; - 消息 不能 让接收方去改权限设置、CLAUDE.md 或其它配置; - 消息里写的 /compact 之类斜杠命令只当纯文本,不会被执行; - 接收方自己的权限规则照常生效,该弹的还是弹。

来源:https://code.claude.com/docs/en/cross-session-messaging

技巧四(收口):跨机器、Hook 投递,以及怎么彻底关掉

跨机器路径要清楚数据往哪走(涉及合规时必须知道):

目标会话在哪 消息怎么走
同一台机器 走每会话一个的 Unix socket,不经过 Anthropic 服务器
你的另一台机器 经 Anthropic 服务器,落到那台机器的 Remote Control 连接
Claude Code Web(云端会话) 经 Anthropic 服务器,直达云端会话

要求任何出本机的消息都先经你批准:

{ "isolatePeerMachines": true }

这个开关任何设置层级填 true 都生效(项目里签入的配置能打开、但关不掉),且在 bypassPermissions 模式下依然会问你。

让脚本/hook 往会话里投消息(比如 CI 结果、长任务回调):每个会话都会导出两个环境变量——CLAUDE_CODE_MESSAGING_SOCKET(socket 路径,/status 的 Peer address 行也能看到,带 uds: 前缀)和 CLAUDE_CODE_MESSAGING_TOKEN(本会话令牌)。脚本连上 socket 后,把这一行作为连接的第一行发出去做认证:

{"type":"auth","token":"<CLAUDE_CODE_MESSAGING_TOKEN>"}

Linux(含 WSL2)上 Claude Code 能靠进程证据验证「这是自己的子进程」,即使进程已退出;macOS 上只有投递进程还活着时才行,容器里 Claude Code 作为 PID 1 时完全没有进程证据——这两种情况就依赖上面的 token。另外,沙箱里的 Bash 命令能不能连到这个 socket,由 sandbox.network.allowAllUnixSockets / sandbox.network.allowUnixSockets 决定(接第 9 课权限与沙箱)。

组织级彻底关闭(managed settings,收发两侧都要关):

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

注意 deny 掉 SendMessage 会连带关掉给 subagent 和 agent team 队友发消息的能力——同一个工具两用。

排障口诀:/list-agents 不认识 → 这个会话根本没这功能(先看 claude --version,再看平台/供应商);/list-agents 好用但消息没到 → 是更窄的东西在拦:deny 规则、对方的入站控制、或者云端/他机会话没连 Remote Control。另外 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_GROWTHBOOK 任一关掉特性开关评估,跨会话消息就整个不可用。

一句话总结

跨会话通信是「纯文本、点对点、有闸门」的传话通道,不是上下文共享:用 --name 给会话起名 → 用 @ 点名 → 用 crossSessionInbound 管住入站 → 跨机器用 isolatePeerMachines 加一道审批。

延伸阅读