Skip to content
OpenClaw Docs

Session Tools

Session Tools

Section titled “Session Tools”

OpenClaw gives agents tools to work across sessions — listing conversations, reading history, sending messages to other sessions, and spawning sub-agents.

Available tools

Section titled “Available tools”
ToolWhat it does
sessions_listList sessions with optional filters (kind, recency)
sessions_historyRead the transcript of a specific session
sessions_sendSend a message to another session and optionally wait
sessions_spawnSpawn an isolated sub-agent session for background work

Listing and reading sessions

Section titled “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.

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

Sending cross-session messages

Section titled “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.

Spawning sub-agents

Section titled “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.

Sub-agents get the full tool set minus session tools (no recursive spawning). After completion, an announce step posts the result to the requester’s channel.

For ACP-specific behavior, see ACP Agents.

Visibility

Section titled “Visibility”

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

LevelScope
selfOnly the current session
treeCurrent session + spawned sub-agents
agentAll sessions for this agent
allAll sessions (cross-agent if configured)

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

Further reading

Section titled “Further reading”