moltbot/docs/concepts/session-tool.md

summary, read_when, title

summary	read_when	title
Agent tools for cross-session status, recall, messaging, and sub-agent orchestration	You want to understand what session tools the agent has You want to configure cross-session access or sub-agent spawning You want to inspect status or control spawned sub-agents	Session Tools

Session Tools

OpenClaw gives agents tools to work across sessions, inspect status, and orchestrate sub-agents.

Available tools

Tool	What it does
sessions_list	List sessions with optional filters (kind, recency)
sessions_history	Read the transcript of a specific session
sessions_send	Send a message to another session and optionally wait
sessions_spawn	Spawn an isolated sub-agent session for background work
sessions_yield	End the current turn and wait for follow-up sub-agent results
subagents	List, steer, or kill spawned sub-agents for this session
session_status	Show a /status-style card and optionally set a per-session model override

Listing and reading sessions

sessions_list returns sessions with their key, kind, channel, model, token counts, and timestamps. Filter by kind (main, group, cron, hook, node) or recency (activeMinutes).

sessions_history fetches the conversation transcript for a specific session. By default, tool results are excluded -- pass includeTools: true to see them. The returned view is intentionally bounded and safety-filtered:

• assistant text is normalized before recall:
  • thinking tags are stripped
  • <relevant-memories> / <relevant_memories> scaffolding blocks are stripped
  • plain-text tool-call XML payload blocks such as <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, and <function_calls>...</function_calls> are stripped, including truncated payloads that never close cleanly
  • downgraded tool-call/result scaffolding such as [Tool Call: ...], [Tool Result ...], and [Historical context ...] is stripped
  • leaked model control tokens such as <|assistant|>, other ASCII <|...|> tokens, and full-width <｜...｜> variants are stripped
  • malformed MiniMax tool-call XML such as <invoke ...> / </minimax:tool_call> is stripped
• credential/token-like text is redacted before it is returned
• long text blocks are truncated
• very large histories can drop older rows or replace an oversized row with [sessions_history omitted: message too large]
• the tool reports summary flags such as truncated, droppedMessages, contentTruncated, contentRedacted, and bytes

Both tools accept either a session key (like "main") or a session ID from a previous list call.

If you need the exact byte-for-byte transcript, inspect the transcript file on disk instead of treating sessions_history as a raw dump.

Sending cross-session messages

sessions_send delivers a message to another session and optionally waits for the response:

• Fire-and-forget: set timeoutSeconds: 0 to enqueue and return immediately.
• Wait for reply: set a timeout and get the response inline.

After the target responds, OpenClaw can run a reply-back loop where the agents alternate messages (up to 5 turns). The target agent can reply REPLY_SKIP to stop early.

Status and orchestration helpers

session_status is the lightweight /status-equivalent tool for the current or another visible session. It reports usage, time, model/runtime state, and linked background-task context when present. Like /status, it can backfill sparse token/cache counters from the latest transcript usage entry, and model=default clears a per-session override.

sessions_yield intentionally ends the current turn so the next message can be the follow-up event you are waiting for. Use it after spawning sub-agents when you want completion results to arrive as the next message instead of building poll loops.

subagents is the control-plane helper for already spawned OpenClaw sub-agents. It supports:

• action: "list" to inspect active/recent runs
• action: "steer" to send follow-up guidance to a running child
• action: "kill" to stop one child or all

Spawning sub-agents

sessions_spawn creates an isolated session for a background task. It is always non-blocking -- it returns immediately with a runId and childSessionKey.

Key options:

• runtime: "subagent" (default) or "acp" for external harness agents.
• model and thinking overrides for the child session.
• thread: true to bind the spawn to a chat thread (Discord, Slack, etc.).
• sandbox: "require" to enforce sandboxing on the child.

Default leaf sub-agents do not get session tools. When maxSpawnDepth >= 2, depth-1 orchestrator sub-agents additionally receive sessions_spawn, subagents, sessions_list, and sessions_history so they can manage their own children. Leaf runs still do not get recursive orchestration tools.

After completion, an announce step posts the result to the requester's channel. Completion delivery preserves bound thread/topic routing when available, and if the completion origin only identifies a channel OpenClaw can still reuse the requester session's stored route (lastChannel / lastTo) for direct delivery.

For ACP-specific behavior, see ACP Agents.

Visibility

Session tools are scoped to limit what the agent can see:

Level	Scope
self	Only the current session
tree	Current session + spawned sub-agents
agent	All sessions for this agent
all	All sessions (cross-agent if configured)

Default is tree. Sandboxed sessions are clamped to tree regardless of config.

Further reading

• Session Management -- routing, lifecycle, maintenance
• ACP Agents -- external harness spawning
• Multi-agent -- multi-agent architecture
• Gateway Configuration -- session tool config knobs