OpenClaw session tools: inspect and coordinate agent work safely
OpenClaw session tools let an agent inspect, hand off, and coordinate work across visible sessions without treating every transcript as public context. The important limit is simple: a session key identifies a routing target. It is not an authorization token.
That distinction matters once an agent can search history, start a child run, or deliver a result back to a chat. A loose session model can turn a useful coordination feature into accidental cross-project visibility. OpenClaw keeps these tools behind the active tool policy and a configured visibility scope, then returns bounded, redacted views instead of raw transcript files.
Table of contents
- What OpenClaw session tools do
- Use the smallest visibility scope
- Read status before reaching for history
- Coordinate work without losing the delivery target
- A practical operating pattern
- FAQ
What OpenClaw session tools do
OpenClaw separates a session from an external conversation. A session is the model’s local work context. A conversation is a specific DM, channel, room, or thread. One session can be connected to an external conversation, but the two should not be used as interchangeable identifiers.
The session tool set covers several jobs:
| Need | Tool family | Good use |
|---|---|---|
| Find relevant work | sessions_list, sessions_search | Locate a recent visible session or a specific transcript excerpt |
| Inspect the state | session_status, sessions_history | Check current runtime, usage, or bounded history before acting |
| Coordinate a turn | sessions_send, sessions_spawn, sessions_yield | Ask another visible session to continue work or create an isolated child run |
| Track children | subagents | List or cancel background work in the current session tree |
| Maintain session state | sessions | Pin, archive, label, reset, or assign an owner within the allowed scope |
| Deliver to a chat | conversations_send, conversations_turn | Address one exact external conversation rather than guessing from a session label |
This is an operational interface, not a transcript export API. sessions_history normalizes assistant text, strips tool-call scaffolding and thinking-like content, redacts credential-like text, and bounds oversized responses. For a scoped incident investigation, use the appropriate SQLite transcript path rather than assuming this coordination tool returns raw data.
For the broader lifecycle of session context, background work, and durable recall, see AI agent session management. It covers why a live task should not be confused with permanent memory.
Use the smallest visibility scope
OpenClaw session tools can be scoped to self, tree, agent, or all. The default is tree: the current session and its spawned work. That is usually the right default for a multi-step task because it gives an agent enough context to collect child results without exposing unrelated work.
| Visibility | What an agent can see | When it fits |
|---|---|---|
self | Only the current session | A tightly bounded workflow that should not inspect anything else |
tree | The current session and its spawned work | A parent agent coordinating delegated tasks |
agent | Sessions owned by the same agent | A trusted single-agent workspace with several related jobs |
all | Sessions across configured agents | An explicit operator or fleet-management role, not a casual default |
Visibility is not cosmetic. OpenClaw’s documentation states that incognito sessions remain hidden from cross-session tools, and that a sandboxed spawned caller can remain limited to its own subtree. A session key alone should never widen that boundary.
Before enabling broad coordination, check the effective tool inventory from the session with /tools. The tool profile is only the first gate. Group, provider, sandbox, and per-agent policies may remove tools afterward. This is especially relevant for a chat-facing agent: a model that can read another session’s transcript and send messages to another conversation has a larger blast radius than one that can only answer the current user.
The OpenClaw security guide is the right companion here. It explains the higher-level controls around remote access, permissions, and tool exposure. Session visibility belongs in the same review, rather than being treated as an internal implementation choice.
Read status before reaching for history
A common mistake is to search or dump history when the decision only needs current status. session_status is the lighter starting point. It provides a /status-style view for a visible session and can report usage, runtime state, model context, and linked background-task information when available.
A parent agent deciding whether to wait for a child run often needs to know whether the child is active, stalled, or complete. It does not need every message the child exchanged with its model.
Use a narrow escalation path:
- List visible sessions with a recency or kind filter.
- Read
session_statusfor the candidate session. - Check
subagentsor the task record if the work was delegated. - Read a bounded tail with
sessions_historyonly when the status lacks the decision context. - Use
sessions_searchfor a specific term instead of scanning a long transcript.
OpenClaw background tasks reinforce this pattern. Tasks are activity records, not schedulers, and can be queued, running, succeeded, failed, timed out, cancelled, or lost. A task may have both a requester session and a child session. Checking the task state first helps an operator avoid waking a still-running child or treating a delivery problem as an execution failure.
If the work is long-running or shared among several agents, AI agent Workboard handoffs offers a useful higher-level view: keep ownership, active state, and the next human decision visible instead of relying on a long shared transcript.
Coordinate work without losing the delivery target
A coordination workflow needs two kinds of identity:
- The session key tells OpenClaw which model context should receive or continue work.
- The conversation address tells OpenClaw where a user-facing message should be delivered.
Keep those separate. Direct messages can share an agent’s main session while still having different reply addresses. If an agent uses a session label as though it were a destination, it can put a correct result in the wrong chat.
For cross-session work, sessions_send runs a turn in another visible session. For isolated delegated work, sessions_spawn creates a child session and sessions_yield lets the parent stop its current turn until a follow-up arrives. The parent retains the job of making sense of the result and deciding what becomes a visible reply.
When the goal is a direct message to one known external target, use the conversation tools rather than asking a session tool to infer it. That preserves the thread or channel routing OpenClaw associates with the conversation. It also makes an automation easier to audit: you can distinguish “this agent processed work in session X” from “this system sent a message to conversation Y.”
The same principle applies to coding and external harness workflows. How OpenClaw works describes the Gateway as the owner of connected channels, tools, and runtime state. Giving an external process a broad session identifier does not make it the new owner of that state. Use the product’s scoped handoff and authorization controls, then keep delivery tied to the intended conversation.
A practical operating pattern
Use this routine for a trusted agent that needs to coordinate its own work without becoming a global session administrator:
- Start with
treevisibility and a narrow tool profile. - Give each delegated job a specific task, owner, and expected delivery route.
- Inspect task or
session_statusdata before reading history. - Search bounded visible excerpts when a specific fact is missing.
- Keep raw-transcript access and cross-agent visibility for an operator workflow with a documented reason.
- Send external messages through a stable conversation address, not a guessed session label.
- Archive or label finished sessions so the next coordination run does not mistake them for current work.
This makes failures easier to reason about: the agent can identify what it owns, find its child work, and return a result to the correct requester without turning session history into an ambient data source.
FAQ
What are OpenClaw session tools?
OpenClaw session tools let an agent inspect, search, update, coordinate, and manage sessions within its allowed visibility scope. They include tools for listing sessions, reading bounded history, sending work to another session, spawning children, and checking session status.
Is a session key an authorization token?
No. A session key selects routing or context. OpenClaw’s security documentation explicitly says it is not an authorization token. Tool policy, caller visibility, device or operator access, and Gateway security controls determine whether a session can be inspected or changed.
When should an agent use session_status instead of sessions_history?
Use session_status first when the question is about current runtime state, usage, model selection, or linked task state. Use bounded history only when the decision requires conversation context that status cannot provide.
Can session tools see incognito sessions?
No. OpenClaw documents that incognito sessions remain hidden from cross-session tools. They are intentionally excluded from the normal coordination and discovery path.
How do background tasks relate to sessions?
Tasks track detached activity such as subagent, automation, ACP, and CLI work. They can reference both the requester session and the child session that did the work. The task state shows what happened; the session provides the conversation context for decisions and follow-up.