Session tools

OpenClaw gives agents tools to work across sessions, inspect status, and orchestrate sub-agents.

Available tools

These tools are still subject to the active tool profile and allow/deny policy.

includes the full session orchestration set, including , , and . includes cross-session messaging tools (, , , ) but does not include sub-agent spawning. To keep a messaging profile and still allow native delegation, add:

json5
Copy
{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}

Group, provider, sandbox, and per-agent policies can still remove those tools after the profile stage. Use

from the affected session to inspect the effective tool list.

Listing and reading sessions

returns sessions with their key, agentId, kind, channel, model, token counts, and timestamps. Filter by kind (, , , , ), exact , exact , search text, or recency (). When you need mailbox-style triage, it can also ask for a visibility-scoped derived title, a last-message preview snippet, or bounded recent messages on each row. Derived titles and previews are produced only for sessions the caller can already see under the configured session tool visibility policy, so unrelated sessions stay hidden.

fetches the conversation transcript for a specific session. By default, tool results are excluded -- pass to see them. The returned view is intentionally bounded and safety-filtered:

• assistant text is normalized before recall:
  • thinking tags are stripped
  • text

    Copy

    <relevant-memories>
    /
    text

    Copy

    <relevant_memories>
    scaffolding blocks are stripped
  • plain-text tool-call XML payload blocks such as
    text

    Copy

    <tool_call>...</tool_call>
    ,
    text

    Copy

    <function_call>...</function_call>
    ,
    text

    Copy

    <tool_calls>...</tool_calls>
    , and
    text

    Copy

    <function_calls>...</function_calls>
    are stripped, including truncated payloads that never close cleanly
  • downgraded tool-call/result scaffolding such as
    text

    Copy

    [Tool Call: ...]
    ,
    text

    Copy

    [Tool Result ...]
    , and
    text

    Copy

    [Historical context ...]
    is stripped
  • leaked model control tokens such as
    text

    Copy

    <|assistant|>
    , other ASCII
    text

    Copy

    <|...|>
    tokens, and full-width
    text

    Copy

    <｜...｜>
    variants are stripped
  • malformed MiniMax tool-call XML such as
    text

    Copy

    <invoke ...>
    /
    text

    Copy

    </minimax:tool_call>
    is stripped
• credential/token-like text is redacted before it is returned
• long text blocks are truncated
• very large histories can drop older rows or replace an oversized row with
  text

  Copy

  [sessions_history omitted: message too large]
• the tool reports summary flags such as
  text

  Copy

  truncated
  ,
  text

  Copy

  droppedMessages
  ,
  text

  Copy

  contentTruncated
  ,
  text

  Copy

  contentRedacted
  , and
  text

  Copy

  bytes

Both tools accept either a session key (like

) or a session ID from a previous list call.

If you need the exact byte-for-byte transcript, inspect the transcript file on disk instead of treating

as a raw dump.

Sending cross-session messages

delivers a message to another session and optionally waits for the response:

• Fire-and-forget: set
  text

  Copy

  timeoutSeconds: 0
  to enqueue and return immediately.
• Wait for reply: set a timeout and get the response inline.

Messages and A2A follow-up replies are marked as inter-session data in the receiving prompt (

) and in transcript provenance. The receiving agent should treat them as tool-routed data, not as a direct end-user-authored instruction.

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

to stop early.

Status and orchestration helpers

is the lightweight -equivalent tool for the current or another visible session. It reports usage, time, model/runtime state, and linked background-task context when present. Like , it can backfill sparse token/cache counters from the latest transcript usage entry, and clears a per-session override. Use for the caller's current session; visible client labels such as are not session keys.

intentionally ends the current turn so the next message can be the follow-up event you are waiting for. Use it after spawning sub-agents when you want completion results to arrive as the next message instead of building poll loops.

is the control-plane helper for already spawned OpenClaw sub-agents. It supports:

• text

  Copy

  action: "list"
  to inspect active/recent runs
• text

  Copy

  action: "steer"
  to send follow-up guidance to a running child
• text

  Copy

  action: "kill"
  to stop one child or
  text

  Copy

  all

Spawning sub-agents

creates an isolated session for a background task by default. It is always non-blocking -- it returns immediately with a and .

Key options:

• text

  Copy

  runtime: "subagent"
  (default) or
  text

  Copy

  "acp"
  for external harness agents.
• text

  Copy

  model
  and
  text

  Copy

  thinking
  overrides for the child session.
• text

  Copy

  thread: true
  to bind the spawn to a chat thread (Discord, Slack, etc.).
• text

  Copy

  sandbox: "require"
  to enforce sandboxing on the child.
• text

  Copy

  context: "fork"
  for native sub-agents when the child needs the current requester transcript; omit it or use
  text

  Copy

  context: "isolated"
  for a clean child.

Default leaf sub-agents do not get session tools. When

, depth-1 orchestrator sub-agents additionally receive , , , and so they can manage their own children. Leaf runs still do not get recursive orchestration tools.

After completion, an announce step posts the result to the requester's channel. Completion delivery preserves bound thread/topic routing when available, and if the completion origin only identifies a channel OpenClaw can still reuse the requester session's stored route (

/ ) for direct delivery.

For ACP-specific behavior, see ACP Agents.

Visibility

Session tools are scoped to limit what the agent can see:

Default is

. Sandboxed sessions are clamped to 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

Related

• Session management
• Session pruning