Manage OpenClaw Sessions: List, Fetch, and Send Messages

Ever felt like your AI agents are stuck in silos? It is frustrating when you build a great agent, but it has no way to know what happened in a previous conversation or what its “colleague” is currently working on. You end up having to manually bridge the gap between sessions, which defeats the purpose of automation.

OpenClaw fixes this by giving your agents a set of tools to work across different sessions. Your agents can now look up history, talk to other sessions, and even spin up sub-agents to handle background tasks. Here is how you can use these tools to make your agents much smarter.

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

Listing and reading sessions

When you need to find a specific conversation, sessions_list is your go-to. It returns sessions with their key, kind, channel, model, token counts, and timestamps. You can filter the results by kind (main, group, cron, hook, node) or by how recently they were active using activeMinutes.

If you need to see the actual words exchanged, sessions_history fetches the transcript for you. By default, tool results are hidden to keep things clean, but you can pass includeTools: true if you need to see exactly what the tools returned. Both of these tools work with either a session key (like "main") or a session ID you got from a previous list call.

Sending cross-session messages

You can use sessions_send to deliver a message to another session. This is great for coordinating between different parts of your system. You have two main ways to handle this:

• Fire-and-forget: Set timeoutSeconds: 0 to put the message in the queue and return to your work immediately.
• Wait for reply: Set a timeout and the agent will get the response back directly.

Once the target agent responds, OpenClaw can manage a reply-back loop. This allows agents to go back and forth for up to 5 turns. If the target agent wants to stop the conversation early, it can just reply with REPLY_SKIP.

Spawning sub-agents

If an agent has a big task that can run in the background, use sessions_spawn. This creates an isolated session that does not block the main agent. It returns a runId and childSessionKey right away so the main agent can keep moving.

You have several options to control how the sub-agent behaves:

• 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 have access to the full tool set, but they cannot use session tools. This prevents them from spawning their own sub-agents recursively. Once the sub-agent finishes its work, an announce step automatically posts the result back to the requester’s channel. For specific ACP behaviors, you should check the ACP Agents documentation.

Visibility

You need to control what an agent can see to keep things secure. Session tools use different scope levels to limit access:

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)

The default level is tree. If you are running a sandboxed session, it is always restricted to tree regardless of your other configurations.

Further reading

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

Next steps

If you want to see these tools in action, try setting up a multi-agent workflow in your local environment. You can also check out how to configure your gateway to adjust these visibility settings.

AI Setup Assistant