OpenClaw Session Tools: How Agents Hand Work Off Cleanly

One of the fastest ways to make an AI operator unreliable is to force everything through one busy chat. A long-running agent can absolutely keep context, but that does not mean every task belongs in the same session. Reviews, detached investigations, coding runs, cron work, and cross-agent routing all benefit from cleaner boundaries.

That is exactly what OpenClaw session tools are for. They give an agent a small set of ways to inspect active sessions, fetch transcript history, and hand work off without turning routing into improvisation. The docs keep the surface area intentionally tight: sessions_list, sessions_history, sessions_send, and sessions_spawn.

The practical goal is simple. You want your agent to answer three questions cleanly: what conversations already exist, what happened in them, and should this next unit of work stay here or move somewhere else?

If you already care about recall quality, this sits right beside memory search. Memory helps an agent remember durable facts. Session tools help it navigate active work.

What the session model actually looks like

OpenClaw does not treat every conversation as the same bucket. The docs define a few important session shapes:

• the main direct chat bucket is always the literal key main, resolved to the current agent's main key
• group chats use full keys like agent:<agentId>:<channel>:group:<id> or agent:<agentId>:<channel>:channel:<id>
• cron jobs use keys like cron:<job.id>
• hooks use hook:<uuid> unless explicitly set
• node sessions use node-<nodeId> unless explicitly set

That detail matters because handoffs only stay clean when the target session means something operationally. A main session is where an ongoing human conversation lives. A cron session is an automation run. A detached sub-agent session is a delegated workspace. Treating those as interchangeable is how transcript sprawl begins.

Use openclaw sessions when you need the storage-level view

The CLI gives you a straightforward way to inspect stored sessions outside a live chat. According to the docs, the basic commands are:

openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --json

A few capabilities here are more useful than they look:

• --agent <id> scopes to one configured agent store
• --all-agents aggregates configured agent stores
• --active 120 shows recently active sessions
• --store <path> points directly at a specific sessions.json file
• --json returns a machine-readable summary including store paths and session rows

The docs also note something easy to miss: openclaw sessions --all-agents reads configured agent stores, while Gateway and ACP discovery can be broader because they also discover disk-only stores under the default agents root or a templated session store root. That means the CLI is useful not just for active chats, but for sanity-checking where session data is actually being found.

If your workflow involves multiple isolated agents, that lines up neatly with multi-agent operations. Separate agents get separate workspaces, separate auth profiles, and separate session stores. Session tools are how you stop that isolation from becoming fragmentation.

sessions_list is the agent-facing directory

Inside a live run, sessions_list is the first tool to reach for when you need to discover what else exists. The docs describe it as a row-based list with filters for kinds, active recency, and recent messages.

The supported kinds filter includes main, group, cron, hook, node, and other. Results can include fields like session key, channel, display name, token usage metadata, delivery context, and transcript path. If you set messageLimit > 0, OpenClaw can include the last few chat messages in the list view.

There are two practical rules I like here:

1. Use sessions_list to discover, not to reconstruct a whole conversation.
2. Use small previews first, then fetch targeted history only for the session that actually matters.

That is not just a style preference. The docs explicitly say tool results are filtered out of list output, and if you want tool messages you should use sessions_history. In other words, sessions_list is the map, not the full archive.

sessions_history is for targeted context recovery

When an agent already knows which conversation matters, sessions_history pulls transcript messages for exactly that session. It accepts a sessionKey and optional limit, plus includeTools if you want the tool-result rows too.

{
  "sessionKey": "agent:main:main",
  "limit": 20,
  "includeTools": true
}

The docs are precise about the behavior:

• includeTools=false filters out role: "toolResult" entries
• it returns raw transcript-format messages
• you can pass a sessionId instead of a session key, and OpenClaw resolves it

This is the clean answer to a common problem: an agent knows some work already happened somewhere else, but does not need to drag that entire transcript into the current chat. Fetch the last relevant messages, recover exactly enough context, then continue.

I would use it for things like checking what a cron run already concluded, reviewing the last exchange in a long group thread, or confirming what a delegated child session already tried before issuing a new instruction.

sessions_send is for cross-session delivery, not chaos

The docs describe sessions_send as a way to send a message into another session, with either fire-and-forget or wait-for-reply behavior. That makes it useful when a different live session is already the right home for the work.

A few details are worth keeping straight:

• timeoutSeconds = 0 enqueues the message and returns an accepted status
• a positive timeout waits for completion and may return ok, timeout, or error
• inter-session messages are persisted with message.provenance.kind = "inter_session"
• after the primary run, OpenClaw can run a reply-back loop with bounded ping-pong turns
• once the loop ends, there is an announce step, and the target can reply ANNOUNCE_SKIP to stay silent

This matters because handoffs are not just “send text over there.” OpenClaw preserves provenance and manages a structured back-and-forth instead of pretending every routed instruction is just another user message. That keeps audits and transcript reading saner.

The docs also spell out a policy layer for this. session.sendPolicy can deny sends by channel and chat type, and a per-session runtime override can be set to allow, deny, or inherit. For example:

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

If you are routing across many channels, that policy boundary is a big deal. It stops a “helpful” agent from spraying cross-session messages into spaces where that behavior is not appropriate.

sessions_spawn is the right answer when the work deserves isolation

This is the part most operators care about most. According to the docs, sessions_spawn creates an isolated delegated session. By default it uses the OpenClaw sub-agent runtime, but it can also target ACP harnesses with runtime: "acp".

{
  "task": "Review the failing deployment and propose a fix",
  "runtime": "subagent",
  "label": "deploy-debug",
  "runTimeoutSeconds": 900,
  "cleanup": "keep"
}

And for ACP-targeted delegation:

{
  "task": "Implement the refactor in Codex",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

The important operational differences from sessions_send are:

• sessions_send talks to an existing session
• sessions_spawn starts a new isolated delegated session

The docs also specify a few behaviors that make this safer than improvised delegation:

• spawns are always non-blocking and return accepted status immediately
• sub-agents start as sessions like agent:<agentId>:subagent:<uuid>
• sub-agents default to the full tool set minus session tools, unless reconfigured
• after completion, OpenClaw runs an announce step back to the requester chat channel
• sub-agent sessions are auto-archived after the configured archive window

That last detail is underrated. One reason delegation becomes messy in other systems is that child work never folds back into the original operator view cleanly. OpenClaw makes the announce path part of the model.

How to decide between staying here, sending there, or spawning new work

Here is the decision rule I would actually run:

• Stay in the current session when the user is still in the loop and the task is part of the same conversation.
• Use sessions_history when you only need targeted context from another session.
• Use sessions_send when another existing session already owns the work.
• Use sessions_spawn when the work is substantial enough to deserve a new isolated run.

If the agent is getting overloaded, that last option is usually the healthiest one. It preserves the main conversation while letting the delegated session focus on a bounded task. That is a much better pattern than dumping a hundred lines of exploration into the same user thread and hoping context windows stay kind.

Do not forget session maintenance

The CLI docs also include openclaw sessions cleanup, which is worth mentioning because session hygiene is part of handoff hygiene.

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --all-agents --dry-run --json
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"

The cleanup command uses session.maintenance settings, supports --dry-run, --enforce, and --active-key, and can return JSON summaries. The docs are explicit that this only maintains session stores and transcripts, not cron run logs.

I would not treat cleanup as an emergency button. It is routine maintenance. If your session strategy depends on never pruning or capping anything, your strategy is probably weak.

Bottom line

OpenClaw session tools are not flashy, and that is exactly why they are useful. They give agents a controlled way to discover active work, inspect the right transcript, message an existing session, or spin up a new isolated run. That is the difference between deliberate delegation and conversational pile-up.

If you remember just one model, make it this:

• sessions_list finds the conversation
• sessions_history reads the relevant part
• sessions_send talks to an existing owner
• sessions_spawn creates a fresh isolated owner

Once you internalize that split, agent handoffs get a lot cleaner, and your main chat stops carrying work it should never have owned in the first place.

Want the complete guide? Get ClawKit — $9.99