它到底是什么

/list-agents（别名 /peers）列出当前 Claude Code 会话可以用 SendMessage 发消息的所有 agent，并给出每个 agent 对应的可用名称，包括子代理（subagents）、当前 agent team 的队友，以及其他 Claude Code 会话（本机会话、云端会话、其他机器上通过 Remote Control 连接的会话）。

版本要求（官方文档原文）：

• 需要 Claude Code v2.1.224 及以上版本，否则报 Unknown command: /list-agents
• 输出中的 teammate 行，以及第一行"本会话自己的名字"，需要 v2.1.239 及以上版本
• 仅在 cross-session messaging 已启用的会话中可用

怎么触发 / 怎么使用

/list-agents

等价写法：

/peers

命令本身不接受参数，执行后直接输出当前可达 agent 的列表，不进入任何交互面板。

读懂输出

按官方文档说明，输出结构固定为：

• 第一行（存在时）：本会话自己的名字——也就是其他会话要给你发消息时应该用的名字
• 下面的行，按来源分组：
  • 子代理（Subagents）：当前会话内正在运行的 agent
  • 队友（Teammates）：当前会话所属 agent team 的队友
  • 本机其他会话：同一台机器上运行的其他 Claude Code 会话，包括后台会话，前提是该会话绑定了 inbox socket
  • 云端会话：仅当本会话已连接 Remote Control 时显示，标记为 cloud
  • 其他机器上的 Remote Control 会话：同样需要本会话已连接 Remote Control，标记为 Remote Control；若目标机器的连接已断开，显示为 offline

当本会话连接着 Remote Control 时，输出会隐去本机其他会话的部分细节：工作目录不显示；无法归属到具体用户的会话名会显示为 (unnamed session)；第一行（本会话自己的名字）也会被省略，除非你在本次启动/恢复会话后手动用 --name 或 /rename 设置过名字。有信息被隐去时，输出末尾会给出提示。

保存 / 配置 / 集成

• 相关设置项 crossSessionInbound：控制本会话如何处理其他会话发来的消息（accept / hold / refuse），可在 /config 的 "Messages from your other sessions" 一行中设置（需要 v2.1.232+）
• isolatePeerMachines：设为 true 时，任何发往本机以外会话的消息都需要你的显式批准
• 若要彻底关闭"发送与列出"能力，可在 permission 设置中添加 deny 规则（裸工具名、不带 specifier）：

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

  复制
  管理员可在 managed settings 中为整个组织同时关闭发送和接收
• /status 会显示本会话的 Peer address 行（inbox socket 地址），前缀为 uds:
• Claude Code 会向 hook 和 Bash 命令导出 CLAUDE_CODE_MESSAGING_SOCKET 和 CLAUDE_CODE_MESSAGING_TOKEN 两个环境变量，用于脚本向本会话的 socket 投递消息

运行约束 / 限制

跟同类原语对比

经典使用场景

• 在让 Claude 给某个会话发消息前，先确认该会话是否真的在可达列表里，以及应该用哪个名字寻址
• 排查"消息没送到"问题时区分两种情况：命令本身不识别（说明本会话不支持该功能，需检查版本）与命令能跑但发送未达（说明是 deny 规则、接收方 inbound 控制、Remote Control 未连接等更具体的原因）
• 查看本会话自己对外暴露的名字，以便告诉其他会话该用什么名字给自己发消息
• 确认 Remote Control 连接状态下列表里哪些本机细节被隐藏，从而判断是否需要用 /rename 显式命名会话

常见坑

1. /list-agents 报 Unknown command，说明该会话不满足 cross-session messaging 的版本要求，而不是"当前没有其他会话可连接"——应先用 claude --version 核实版本。
2. 命令能正常输出列表，但发出的消息对方没收到：官方文档明确这属于"更窄的限制"生效，可能是 permission deny 规则去掉了 SendMessage，也可能是接收方 crossSessionInbound 设为 hold/refuse，还可能是目标是云端/跨机会话但本会话未连接 Remote Control。
3. 连接 Remote Control 时，输出会隐去本机会话的工作目录和名字（显示为 (unnamed session)），这是有意为之的信息脱敏，不代表这些会话不存在或消息发不出去。
4. v2.1.239 之前的版本里，agent team 队友不会出现在 /list-agents 列表中，但 Claude 实际上已经可以按名字给他们发消息——列表不全不等于功能不可用。

来源

• Claude Code Commands 官方文档 — /list-agents 命令表条目及版本要求
• Message your other Claude Code sessions（cross-session-messaging 官方文档） — /list-agents//peers 的详细行为、输出结构、配置项与限制