Session Tool

Seven agent-facing tools for cross-session inspection and sub-agent orchestration. Agents use these to query history, send messages across sessions, spawn background workers, and manage child agents.

Tools

sessions_list

List sessions with optional filters by kind or recency. Returns: key, kind, channel, model, token counts, timestamps.

Session kinds: main, group, cron, hook, node.

sessions_history

Retrieve conversation transcript for a session. Excludes tool results by default. Normalizes output: strips thinking tags, scaffolding blocks, and control tokens.

sessions_send

Deliver a message to another session.

• timeoutSeconds: 0 — fire-and-forget (no response waited)
• Synchronous mode — reply-back loop up to 5 turns, with optional early termination

sessions_spawn

Create an isolated background task session. Non-blocking — returns immediately with runId + childSessionKey.

Orchestrator agents (depth ≥ 1) receive expanded tool access.

sessions_yield

Terminate the current turn early to receive follow-up results from a spawned session.

subagents

Control spawned sub-agents: list, steer, kill.

session_status

Display current session status and any active model overrides.

Visibility Scoping

Controls which sessions an agent can see and interact with:

Related

• Session Management (OpenClaw) — session routing and lifecycle
• Agent Loop (OpenClaw) — where tool calls are dispatched
• OpenClaw Hooks — hook points around agent execution
• Source - Session Tool (OpenClaw Docs)