OpenClaw session tools 让 agent 具备跨会话列表、历史读取、消息发送、子代理派生（sessions_spawn）和编排能力（sessions_yield、subagents）。默认可见性级别为 tree（当前会话+子代理），沙箱会话强制为 tree。安全过滤自动脱敏凭据、剥离 think 标签和 tool-call XML，并支持 includeTools: true 查看工具结果。子代理默认无递归工具，需 maxSpawnDepth >= 2 才开放。

OpenClaw Session Tools 跨会话工具与子代理编排指南

OpenClaw 为 agent 提供了一套完整的会话工具，用于跨会话操作、状态检查和子代理编排。所有工具受当前 tool profile 和 allow/deny 策略控制。

可用工具列表

工具	功能
sessions_list	列出会话，支持按 kind、label、agent、recency、preview 过滤
sessions_history	读取指定会话的对话记录
sessions_send	向另一个会话发送消息，可选择等待回复
sessions_spawn	派生隔离的子 agent 会话用于后台任务
sessions_yield	结束当前 turn，等待子 agent 后续结果
subagents	列出、引导（steer）或终止（kill）已派生的子 agent
session_status	显示 /status 样式的状态卡片，可为当前会话设置模型覆盖

Tool profile 配置

• tools.profile: "coding" 包含完整会话编排工具集（含 sessions_spawn、sessions_yield、subagents）
• tools.profile: "messaging" 仅包含跨会话消息工具（sessions_list、sessions_history、sessions_send、session_status），不含子 agent 派生
• 如需在 messaging profile 下允许子 agent 派生，添加：

{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}

注意：Group、provider、sandbox 以及每个 agent 的策略仍然可以在 profile 阶段之后移除这些工具。使用 /tools 命令查看生效的工具列表。

会话列表与历史读取

sessions_list

返回会话的 key、agentId、kind、channel、model、token 计数和时间戳。支持过滤：

• kind: main、group、cron、hook、node
• label: 精确匹配
• agentId: 精确匹配
• 搜索文本
• activeMinutes: 最近活跃时间

需要像收件箱一样筛选时，可请求生成可见范围的有标题、最后消息预览或最新消息摘要。派生标题和预览仅在可见性策略允许时生成，确保无关会话隐藏。

sessions_history

获取指定会话的对话记录。默认不包含工具结果，传 includeTools: true 查看。返回内容经过安全过滤和边界控制：

• assistant 文本在被返回前进行规范化处理：
  • 剥离 thinking 标签
  • 剥离 <relevant-memories> / <relevant_memories> 脚手架块
  • 剥离纯文本 tool-call XML 负载（如 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls>，包括未完整闭合的截断负载）
  • 剥离降级的 tool-call/result 脚手架（如 [Tool Call: ...]、[Tool Result ...]、[Historical context ...]）
  • 剥离泄露的模型控制令牌（如 <|assistant|>、其他 ASCII <|...|> 令牌、全角 <｜...｜> 变体）
  • 剥离格式异常的 MiniMax tool-call XML（如 <invoke ...> / </minimax:tool_call>）
• 凭据/令牌类文本在返回前脱敏
• 长文本块被截断
• 非常大的历史记录可能丢弃较早的行，或将过大的行替换为 [sessions_history omitted: message too large]
• 返回摘要标志：truncated、droppedMessages、contentTruncated、contentRedacted、bytes

注意：如果需要精确的逐字节记录，请直接读取磁盘上的 transcript 文件，不要把 sessions_history 作为原始转储使用。

两个工具都接受 session key（如 "main"）或 session ID（来自之前的列表调用）。

跨会话消息发送

sessions_send 将消息发送到另一个会话，并可选择等待回复：

• Fire-and-forget：设置 timeoutSeconds: 0，消息入队后立即返回
• 等待回复：设置超时，回复内联返回

线程作用域的聊天会话（如 Slack 或 Discord 以 :thread:<id> 结尾的 key）不能作为 sessions_send 的目标。应使用父频道会话 key 进行 inter-agent 协调，避免工具路由消息出现在活跃的人类交互线程中。

消息和 A2A 后续回复在接收 prompt 中标记为 inter-session 数据（[Inter-session message ... isUser=false]），并在 transcript 中记录来源。接收 agent 应将其视为工具路由数据，而非终端用户的直接指令。

目标 agent 回复后，OpenClaw 可运行回复往返循环，允许两个 agent 交替发送消息（最多 session.agentToAgent.maxPingPongTurns 次，范围 0-20，默认 5）。目标 agent 回复 REPLY_SKIP 可提前终止。

状态与编排辅助工具

session_status

当前或其他可见会话的轻量级 /status 工具。报告用量、时间、模型/运行时状态以及关联的后台任务上下文。可以回填稀疏的 token/cache 计数器（从最新 transcript 使用条目中获取）。设置 model=default 可清除本会话的模型覆盖。

使用 sessionKey="current" 获取调用者当前会话。可见的客户端标签（如 openclaw-tui）不是会话 key。

sessions_yield

主动结束当前 turn，使下一条消息成为等待中的后续事件。通常在派生子 agent 后使用，让完成结果直接作为下一条消息到达，避免构建轮询循环。

subagents

已派生 OpenClaw 子 agent 的控制平面工具，支持：

• action: "list" — 查看活跃/近期运行
• action: "steer" — 向运行中的子 agent 发送后续指导
• action: "kill" — 停止单个子 agent，或 "all" 停止全部

如何派生子 agent

sessions_spawn 创建隔离的后台任务会话。始终非阻塞，立即返回 runId 和 childSessionKey。

原生子 agent 运行在子会话的第一个可见 [Subagent Task] 消息中接收委托任务，系统 prompt 仅携带子 agent 运行时规则和路由上下文。

关键选项：

• runtime: "subagent"（默认）或 "acp"（外部 harness agent）
• model、thinking: 对子会话的模型或思考模式覆盖
• thread: true: 绑定到聊天线程（Discord、Slack 等）
• sandbox: "require": 强制子会话沙箱化
• context: "fork": 原生子 agent 需要当前请求者的 transcript；省略或使用 context: "isolated" 创建干净子会话。线程绑定的原生子 agent 默认 context: "fork"，除非 threadBindings.defaultSpawnContext 另行指定。

工具权限递归规则：

• 默认叶子子 agent 不获得会话工具
• 当 maxSpawnDepth >= 2 时，深度为 1 的编排子 agent 额外获得 sessions_spawn、subagents、sessions_list、sessions_history，以便管理自己的子 agent
• 叶子运行仍然不获得递归编排工具

完成通知： 子 agent 完成后，通过 announce 步骤将结果发送到请求者的频道。完成分发保留绑定的线程/话题路由，如果完成来源仅标识频道，OpenClaw 可重用请求者会话的已存储路由（lastChannel / lastTo）进行直接投递。

对于 ACP 专用行为，参见 ACP Agents。

可见性级别

级别	范围
self	仅当前会话
tree	当前会话 + 派生子 agent（默认）
agent	该 agent 的所有会话
all	所有会话（如配置了跨 agent）

默认值： tree。

沙箱会话被固定为 tree，忽略配置。

常见问题

sessions_history 返回的内容被过滤/截断了怎么办？

如需原始字节记录，直接读取磁盘上的 transcript 文件。sessions_history 始终施加安全过滤（脱敏、剥离内部占位符）和大小限制（长文本截断、过大行替换）。如果使用 sessions_history 作为数据源，注意检查返回的 truncated、droppedMessages 等标志。

子 agent 如何与父 agent 通信？

子 agent 完成时 OpenClaw 自动将结果发送回请求者频道。如果需要子 agent 期间中途通信，在子 agent 内部使用 sessions_send（需确认工具权限允许）。也可在父 agent 中用 sessions_yield 挂起并等待子 agent 完成结果作为下一条消息。

如何限制子 agent 再派生子 agent？

默认禁用（叶子子 agent 无会话工具）。如需允许，设置 maxSpawnDepth >= 2，此时深度 1 的子 agent 获得 sessions_spawn 等工具。叶子子 agent 始终没有递归工具。

延伸阅读

• Session 管理 — 路由、生命周期、维护
• ACP Agents — 外部 harness 派生
• Multi-agent — 多 agent 架构
• Gateway 配置 — 会话工具配置项
• Session 修剪 — 会话清理策略