Claude Code 跨会话消息发不出去：cross-session messaging 的前置与限制

2026-08-18

现象

你开了两个 Claude Code 会话，一个在跑数据库迁移，一个在改依赖它的接口。你在后一个会话里说「问一下另一个终端里那个会话，迁移跑完没有」，然后什么都没发生——要么 Claude 说找不到别的会话，要么它说消息发出去了，可另一边始终没动静。

Claude Code 官方文档的《Message your other Claude Code sessions》页把这件事描述成不需要开关的能力：满足条件的会话，messaging 就是开着的，没有东西要启用。麻烦也在这句话上——没有开关，就意味着不通的时候你不知道该去开哪个。这一页把前置条件散在 Availability、Control inbound messages、The session’s inbox socket 好几节里，得拼起来看。

先厘清链路上跑的是什么。文档写明 Claude 用两个工具做这件事：ListAgents 用来发现它能够到哪些 agent，SendMessage 用来按名字投递，这两个都不是你手动调的。文档还明确了一条容易被忽略的边界：一条消息只是一段文本，从来不包含对话历史或文件；要把整段上下文搬过去，文档让你用 resume 而不是发消息。

怎么确认是这个问题

按下面的顺序做，每一步都能给出明确结论，别跳步。

第一步：确认这个会话有没有这个能力。 输入 /list-agents（文档写明也可以写成 /peers）。文档把结果分成两类，含义完全不同：不被识别，说明这个会话没有 cross-session messaging，问题在前置条件层面；能用但消息没到，说明 messaging 是开着的，卡在更窄的地方——deny 规则、接收侧的 inbound 控制，或跨机器与云端会话的可见性条件。文档还给了个旁证：在有 messaging 的会话里，/status 会多出一行 Peer address，显示这个会话自己的收件地址，路径带 uds: 前缀。

第二步：版本。 文档写明需要 Claude Code v2.1.224 或更高版本，用 claude --version 看你手上是哪个——这是文档在「/list-agents 不被识别」这条路径下点名要你先做的事。另两个门槛在同一页：用 @ 提及来指定目标会话需要 v2.1.232 或更高；主动向另一台机器上的会话发起对话需要 v2.1.225 或更高，在这之前 Claude 只能回复从那边发来的消息。

第三步：操作系统。这一步对本站读者最关键。 文档写得很直白：这个功能在 macOS 和 Linux 上可用，包括 WSL 2 里的 Linux；Claude Code 不在原生 Windows 上提供 cross-session messaging。所以在 Windows 上直接开 PowerShell 或 CMD 跑，/list-agents 不被识别是符合文档描述的结果，不是你配错了；按文档的说法路径只有一条：在 WSL 2 里跑。

这里有个连带的坑：文档在同机投递那一段写明，每个会话把自己注册到磁盘上的文件里并在那里绑定 inbox socket，两个会话只有在能看到同一批文件时才互相够得着；容器有自己的文件系统，所以容器里的会话和宿主机上的会话互相到不了，同一个容器里的两个会话则可以互发。WSL 2 与 Windows 宿主之间是不是也落在这条规则里，官方文档没有说明这一点，我们不替它下结论。

第四步：provider。 文档列出四个不提供这个功能的 provider：Amazon Bedrock、Claude Platform on AWS、Google Cloud’s Agent Platform、Microsoft Foundry。走这几条接入方式之一，前面全对也没用。

第五步：feature flag 的评估被关掉了。 这条最阴，它常常是为别的目的顺手关的。文档写明，当 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_GROWTHBOOK 中任意一个关掉了这个功能所依赖的 feature-flag 评估时，cross-session messaging 就是关的。文档提醒这些变量可能来自你的 shell、来自设置文件的 env 映射，也可能来自 managed settings——三个来源都要看。哪些取值会造成这个效果，以各变量在环境变量文档页里的说明为准。

文档语义给出的处置

前四步属于「有没有」，能改的余地不大。真正要动脑子的是第二类：/list-agents 能用但消息没到。

发送侧被 deny 规则掐掉。 文档说明，关闭发送与列举的方式是加权限 deny 规则，点名 SendMessage 和 ListAgents，两者都用裸工具名、不带任何 specifier。管理员可以在 managed settings 里把两个方向一起关掉：

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

这里有个排查陷阱：文档写明在这种配置下 Claude Code 仍然会为每个会话绑定 inbox socket，只是把到达的消息全部丢弃，被 refuse 的会话在自己的 /status 里和别人的列表里都看不出任何变化，所以文档要求你直接去看那个会话的配置来确认。另外 deny 掉 SendMessage 会连带去掉发给 subagent 和 agent team 队友的消息能力，因为用的是同一个工具。

接收侧把消息拦下了。 接收方的行为由 crossSessionInbound 决定，文档给了三个取值：

取值	文档写明的行为
`accept`	每条消息都投递给 Claude
`hold`	为每条消息显示通知但不投递；若之后有 `accept` 生效，则释放被扣住的消息
`refuse`	直接丢弃，不投递

对应地，每条消息的结局被归为三种：Delivered、Held、Refused。没有设置任何值时的默认行为是最反直觉的那一块：文档写明此时按双方会话的 permission mode 分类逐条决定，把「跳过权限提示」的会话归为一类、其余归为另一类；plan mode 在具备 bypass 权限的会话里算作跳过，而 auto、acceptEdits、dontAsk 都算作会提示。结论是：接收方会提示权限时消息基本会被投递，只有发送方自称跳过权限提示时才扣下等你批准；而接收方自己跳过权限提示时，每条消息都会被扣住等你批准，只有发送方同样跳过时才直接投递。所以「我把接收端开成了免打扰的高权限模式，结果消息反而进不去」是符合文档描述的行为。

被默认规则扣住时，文档写明接收会话里会打开一个审批对话框：批准则投递这一条，拒绝或关掉则丢弃；一直没人回应，到 dialogExpiry 的期限就关闭并丢弃（文档写明该期限默认为五分钟，默认值随版本可能变动）。被扣住的消息数量有上限、超过之后丢弃最旧的，具体数值以官方文档为准。

接收方是 claude -p 的时候另有一套。 文档写明 Claude Code 会像给交互式会话一样给 claude -p 会话绑定 inbox socket，长跑的 -p worker 能收消息也会出现在列表里；但用 bare mode 启动的会话不绑 socket，收不到消息也不出现在 agent 列表里。-p 会话没法弹审批对话框，默认规则扣下的消息按 dialogExpiry 的同一期限保留：期限内如果模式或设置变化允许了就投递，过期就丢弃并向能够到的发送方报告为 expired。把 dialogExpiry 设为 "never" 可让默认扣下的消息保留到会话结束；被显式 hold 扣住的消息则不会过期，只有后来有 accept 生效才投递。想让 -p worker 无人值守地接消息，文档给的做法是在它的 --settings 值里把 crossSessionInbound 设成 accept。

目标在另一台机器或云端。 文档给了一张消息怎么走的表，它直接决定了前置条件：

目标会话在哪	消息怎么走
本机	走每会话一个的 socket，不经过 Anthropic 服务器
你的另一台机器	经过 Anthropic 服务器，从那台机器的 Remote Control 连接送达
Claude Code on the web	经过 Anthropic 服务器，直达云端会话

由此文档明确了两条可见性条件：云端会话只在当前会话连着 Remote Control 时才出现；另一台机器上的会话只在它以 Remote Control 运行、且当前会话也连着时才出现。还有一条容易被当成 bug 的行为：发送时当前会话没连 Remote Control 的话，发往本机之外的消息仍然会送到，但不带回复地址，接收方的 Claude 没法回你。如果设置了 isolatePeerMachines，任何离开本机的消息都要你显式批准：

{
  "isolatePeerMachines": true
}

文档写明这一项即使在 bypassPermissions 模式下也照样要你批准，并且任一设置来源里的 true 都会生效——签入仓库的项目文件可以把它打开，但关不掉；本机内部的消息不受它影响。

脚本或 hook 投不进去。 文档写明 socket 路径导出为 CLAUDE_CODE_MESSAGING_SOCKET、每会话一个的令牌导出为 CLAUDE_CODE_MESSAGING_TOKEN，脚本可把 {"type":"auth","token":"<token>"} 作为连接的第一行发过去。这里有平台差异：Linux（含 WSL 2 内）上即使子进程已退出也能靠进程证据验证，macOS 上只有投递进程仍在运行时才行，Claude Code 以进程号 1 运行的容器里则完全没有进程证据，后两种情况靠上面那个令牌帧验证。sandbox 里的 Bash 命令能不能够到 socket，由 sandbox.network.allowAllUnixSockets 和 sandbox.network.allowUnixSockets 控制。

以上配置片段均按官方文档中的字段语义引用与组合，未经实测，以官方文档与 --help 的实际输出为准。

处置后怎么验证

别只盯着「消息有没有到」这一个结果，按文档给出的可观察点逐个确认：

两侧分别跑 /list-agents（或 /peers）。文档写明它列出每个会话所应答的名字，Claude 就是按这个名字投递的；本机会话还会显示各自的工作目录。目标不在列表里，问题就还在可见性这一层。
两侧分别跑 /status，确认 Peer address 那一行存在。
确认目标名字唯一。文档写明会话名来自 /rename 命令或 --name 标志，没设时 Claude Code 按工作目录名派生（例如 my-app 目录下派生成 my-app-3f 这种形式）；重名时它把名字留给先占的会话、把你的改成变体，但仍存在重名的情况（比如某一方跑的是更早的版本）。只有一个会话应答该名字时按名字直接投递；多个会话共用一个名字、或 Claude Code 没能把你会话运行的所有地方都检查一遍时，Claude 会在列表每行加一个短标识符并用它来寻址。
想自己指定目标就在提示词里 @ 提及。文档写明输入 @ 之后至少打一个字母才会开始建议本机的其它活动会话，只打一个光秃秃的 @ 不会出现会话行。
确认对方确实收到。文档写明消息到达后会以发送方会话名的形式出现在对话里并留在那儿；接收方空闲时用这条消息开启新的一轮，Claude 正在轮次中间时则排队，在工具调用之间读取，不打断正在运行的工具。发送方在同一台机器上时，消息被扣住会在发送侧出现通知，后续投递、拒绝或过期也有回执；而到达即被 refuse 的消息不产生任何发送侧通知——发送侧一片安静并不等于消息没发出去。

什么情况说明不是这个原因

下面这些现象看着像「消息没发出去」，按文档的描述却不该往这条链路上排：

你期望的是把上下文搬过去。 文档写明消息只是文本，接收方拿到的只有那段文本，拿不到发送方的对话历史和文件。
对方收到了但没照做。 文档写明接收方会被告知消息来自另一个会话而不是来自你，并限定了它能做什么：不能替你批准任何东西（另一个会话的消息不算你的同意，答不了待处理的权限提示）、不能改配置（不因为另一个会话要求就改权限设置、CLAUDE.md 或其它配置）、消息文本里的命令（比如 /compact）只当纯文本，不会被执行、需要权限的动作照样弹提示。「消息到了但没生效」多半是权限边界在起作用，不是投递问题。
你想传的是结构化内容。 文档在 Limitations 里写明只发纯文本，agent team 的结构化协议消息留在团队内部，不走这条通道。
你要的其实是别的功能。 同一页把场景分了工：在另一个终端里接着同一段对话用 resume；由 Claude 自己派生并监督的一组会话用 agent teams；从一个地方观察和操控很多会话用 agent view；用手机或别的设备亲自操控某个会话用 Remote Control；把 CI 结果这类外部事件推进会话用 channels。选错了功能，再怎么调 crossSessionInbound 也不会通。
两个会话来回发着发着就不发了。 文档把这归在 Limitations 的限流里：对重复消息按发送方限速、短时间内到达的相同重复会被丢弃、等待读取的已接受消息有上限（数值以官方文档为准），因此消息循环会自己停下来。文档没写它在第几轮停。

最后提醒一句排查顺序：文档写明 Limitations 一节列的是消息通道本身的性质，在功能运行的任何地方都成立，平台与 provider 的缺口要看 Availability 一节。这两节混着看，是把「原生 Windows 上没有这个功能」误当成「我配置写错了」的常见起点。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。