​

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

​

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

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

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

Session tools are scoped to limit what the agent can see: 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