Session 工具总览

概述

OpenClaw 为 Agent 提供一组 session 工具，用于跨会话状态查询、历史回溯、消息发送和 sub-agent 编排。

工具一览

工具	功能
`sessions_list`	列出会话，支持按 kind/label/agent/recency/preview 过滤
`sessions_history`	读取指定会话的对话 transcript
`sessions_send`	向另一个会话发消息，可选等待回复
`sessions_spawn`	派生隔离的 sub-agent 会话执行后台任务
`sessions_yield`	结束当前 turn，等待 sub-agent 完成事件
`subagents`	列出/引导/终止当前会话派生的 sub-agent
`session_status`	显示 `/status` 风格的状态卡，可设置 per-session 模型覆盖

Profile 与可用性

Profile	包含的 session 工具
`minimal`	仅 `session_status`
`messaging`	`sessions_list`、`sessions_history`、`sessions_send`、`session_status`
`coding`	全部（含 `sessions_spawn`、`sessions_yield`、`subagents`）
`full`	全部

messaging profile 下启用 sub-agent 派生：

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

group、provider、sandbox、per-agent 策略可在 profile 阶段之后再移除工具。用 /tools 确认当前有效工具列表。

sessions_list

列出会话，返回 key、agentId、kind、channel、model、token 数、时间戳。

过滤条件：

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

支持邮箱式 triage 模式：可请求可见性范围内的派生标题、最后消息预览片段、每行有界的最近消息。

sessions_history

读取指定会话的对话 transcript。默认不含工具结果，传 includeTools: true 可查看。

安全过滤（返回前自动处理）：

剥离 thinking 标签
剥离 <relevant-memories> 脚手架块
剥离纯文本工具调用 XML（<tool_call>、<function_call> 等，含截断的未闭合块）
剥离降级工具调用脚手架（[Tool Call: ...]、[Tool Result ...]、[Historical context ...]）
剥离泄漏的模型控制 token（<|assistant|> 等 ASCII/全角变体）
剥离畸形 MiniMax 工具调用 XML
脱敏凭证/token 类文本
截断过长文本块
超大历史可能丢弃旧行或替换为 [sessions_history omitted: message too large]

报告标志：truncated、droppedMessages、contentTruncated、contentRedacted、bytes

两个工具均接受 session key（如 "main"）或 session ID。需要原始字节级 transcript 时，直接检查磁盘上的 transcript 文件。

sessions_send

向另一个会话发消息，可选等待回复。

Fire-and-forget：timeoutSeconds: 0，入队后立即返回
等待回复：设置超时，内联获取响应

注意：

线程作用域的聊天会话（如 Slack/Discord key 以 :thread:<id> 结尾）不是有效目标，用父 channel 会话 key 进行 Agent 间协调
消息在接收方提示中标记为 [Inter-session message ... isUser=false]，接收方应视为工具路由数据，不是用户指令
目标响应后，OpenClaw 可运行回复循环（agents 交替消息，上限 session.agentToAgent.maxPingPongTurns，范围 0-20，默认 5）
目标 Agent 可回复 REPLY_SKIP 提前终止

session_status

当前或另一个可见会话的轻量 /status 等效工具。报告用量、时间、model/runtime 状态、关联后台任务上下文。

model=default 清除 per-session 覆盖
sessionKey="current" 指向调用方当前会话
可见客户端标签（如 openclaw-tui）不是 session key

sessions_yield

结束当前 model turn，等待运行时事件（主要是 sub-agent 完成事件）作为下一条消息到达。

这是等待 sub-agent 完成的唯一正确方式
禁止用轮询（subagents、sessions_list、sessions_history、sleep）替代
某些精简 profile 可能有 sessions_spawn 但没有 sessions_yield，此时不要发明轮询循环

subagents

已派生 sub-agent 的控制平面工具，作用域限于当前请求方会话。

支持操作：

action: "list" — 查看活跃/最近的运行
action: "steer" — 向运行中的子 Agent 发送引导消息
action: "kill" — 停止指定子 Agent 或全部（all）

可见性配置

{
  tools: {
    sessions: {
      visibility: "tree",  // self | tree（默认）| agent | all
    },
  },
}

级别	范围
`self`	仅当前会话
`tree`	当前会话 + 派生的 sub-agent（默认）
`agent`	该 agent 的所有会话
`all`	所有会话（跨 agent 还需 `tools.agentToAgent`）

沙箱会话强制锁定为 tree。

Wiki AI

目录