Session tools

Session tools 문서는 OpenClaw 공식 문서(concepts/session-tool)를 한국어로 정리한 가이드입니다. Agent tools for cross-session status, recall, messaging, and sub-agent orchestration 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Agent tools for cross-session status, recall, messaging, and sub-agent orchestration

한국어 가이드 범위: concepts/session-tool 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Available tools
Listing and reading sessions
Managing session settings and groups
Sessions versus conversations
Sending cross-session messages
Status and orchestration helpers
Session state changes
Spawning sub-agents
Visibility
Further reading
관련 문서

상세 내용

본문

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. tools.profile: "coding" includes the full session orchestration set. tools.profile: "messaging" includes session self-service, discovery, recall, cross-session messaging, external-conversation tools, and the complete spawn lifecycle (sessions_spawn, sessions_yield, and subagents). The UI-only task-suggestion tools spawn_task and dismiss_task remain coding-profile tools.

Tool	What it does
`sessions`	Patch visible session settings and manage the global session-group catalog
`sessions_list`	List sessions with optional filters (kind, label, agent, archive, preview)
`sessions_search`	Search visible session transcripts and return matching excerpts
`sessions_history`	Read the transcript of a specific session
`sessions_send`	Run another session on the same Gateway and optionally wait
`conversations_list`	List stable external conversation addresses
`conversations_send`	Send to one exact external conversation without running a local session
`conversations_turn`	Send to one exact external conversation and wait for its correlated reply
`sessions_spawn`	Spawn an isolated sub-agent session for background work
`sessions_yield`	End the current turn and wait for follow-up sub-agent results
`subagents`	List or cancel background work in this session tree
`session_status`	Show a `/status`-style card and optionally set a per-session model override

Listing and reading sessions

sessions_list returns focused discovery rows: session key, agent, kind, channel, label/title/preview fields, parent and child relationships, last update, archive/pin state, state version, model, context/total token counts, run status, and whether the last run aborted. Filter by kinds (array; accepted values: main, group, cron, hook, node, other), exact label, exact agentId, search text, or recency (activeMinutes). Active sessions are returned by default; pass archived: true to inspect archived sessions instead. Set includeDerivedTitles, includeLastMessage, or messageLimit (capped at 20) when you need mailbox-style triage: a visibility-scoped derived title, a last-message preview snippet, or bounded recent messages on each row. Delivery routing, internal session IDs, per-run timings/settings, cost estimates, and transcript paths are intentionally omitted; use session_status, conversation tools, and sessions_history for those owner-specific details. 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. When visibility is restricted, sessions_list returns optional visibility metadata showing the effective mode and a warning that results may be scope-limited.

주요 항목:

assistant text is normalized before recall:
thinking tags are stripped
<relevant-memories> / <relevant_memories> scaffolding blocks are stripped
plain-text tool-call XML payload blocks such as <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, and <function_calls>...</function_calls> are stripped, including truncated payloads that never close cleanly
downgraded tool-call/result scaffolding such as [Tool Call: ...], [Tool Result ...], and [Historical context ...] is stripped
leaked model control tokens such as <|assistant|>, other ASCII <|...|> tokens, and full-width <｜...｜> variants are stripped
malformed MiniMax tool-call XML such as <invoke ...> / </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 [sessions_history omitted: message too large]
the tool reports summary flags such as truncated, droppedMessages, contentTruncated, contentRedacted, bytes, and pagination metadata

Managing session settings and groups

The owner-gated sessions tool exposes two bounded self-service surfaces:

주요 항목:

action: "patch" changes the current session by default, or another visible session selected by sessionKey. It can set the label, sidebar icon, pin/archive state, model, and thinking level. It does not expose reset, delete, or compact actions.
group_list, group_set, group_rename, and group_delete manage the global ordered session-group catalog. group_set replaces the ordered name list rather than patching one entry.

Sessions versus conversations

A session is local model context. A conversation is an exact external address such as one peer, channel, or thread. The two are linked, but they are not interchangeable: direct messages can share one main session while retaining separate conversation addresses.

Sending cross-session messages

sessions_send runs another session on the same Gateway and optionally waits for the response. Its sessionKey, label, or agentId selects local model context, not an external destination. The resulting reply can still be announced through the established requester or target delivery context; that existing behavior is unchanged. For exact external delivery, use a conversation tool or message with an explicit channel and target.

주요 항목:

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

Status and orchestration helpers

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

주요 항목:

origin is where the session was created, or the provider inferred from a deliverable session-key prefix when older state lacks stored origin metadata.
active is the current live-run route. It is only reported for the live or current session being handled now.
deliveryContext is the persisted delivery route stored on the session, which OpenClaw can reuse for later delivery even when the active surface differs.

Session state changes

OpenClaw keeps a durable signal log of material session state changes (direct human messages to watched sessions, child-run outcomes, goal changes, compaction). sessions_list rows and session_status expose the session's stateVersion, and session_status accepts changesSince: to return the typed events after that version, with exact historyGap signaling when the requested version predates retained history. Watchers — spawn parents automatically, sessions_send watch: true explicitly — receive one coalesced stale-state notice when another actor changes a watched session.

Spawning sub-agents

sessions_spawn creates an isolated session for a background task by default. It is always non-blocking; it returns immediately with a runId and childSessionKey. Native sub-agent runs receive the delegated task in the child session's first visible [Subagent Task] message, while the system prompt carries only sub-agent runtime rules and routing context.

주요 항목:

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.
context: "fork" for native sub-agents when the child needs the current requester transcript; omit it or use context: "isolated" for a clean child. context: "fork" is only valid with runtime: "subagent". Thread-bound native sub-agents default to context: "fork" unless threadBindings.defaultSpawnContext says otherwise.
visible: true to create a persistent dashboard session instead of a hidden sub-agent session. Visible spawns support an explicit model, working directory, same-agent transcript fork, and an optional managed worktree; see Sub-agents for the exact compatibility limits.

Visibility

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

Level	Scope
`self`	Only the current session
`tree`	Current + spawned; reads include watched same-agent groups
`agent`	All sessions for this agent
`all`	All sessions (cross-agent if configured)

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/session-tool
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Session tools

핵심 요약

Agent tools for cross-session status, recall, messaging, and sub-agent orchestration

한국어 가이드 범위: concepts/session-tool 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Available tools
Listing and reading sessions
Managing session settings and groups
Sessions versus conversations
Sending cross-session messages
Status and orchestration helpers
Session state changes
Spawning sub-agents
Visibility
Further reading
관련 문서

상세 내용

본문

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

Available tools

Tool	What it does
`sessions`	Patch visible session settings and manage the global session-group catalog
`sessions_list`	List sessions with optional filters (kind, label, agent, archive, preview)
`sessions_search`	Search visible session transcripts and return matching excerpts
`sessions_history`	Read the transcript of a specific session
`sessions_send`	Run another session on the same Gateway and optionally wait
`conversations_list`	List stable external conversation addresses
`conversations_send`	Send to one exact external conversation without running a local session
`conversations_turn`	Send to one exact external conversation and wait for its correlated reply
`sessions_spawn`	Spawn an isolated sub-agent session for background work
`sessions_yield`	End the current turn and wait for follow-up sub-agent results
`subagents`	List or cancel background work in this session tree
`session_status`	Show a `/status`-style card and optionally set a per-session model override

Listing and reading sessions

주요 항목:

assistant text is normalized before recall:
thinking tags are stripped
<relevant-memories> / <relevant_memories> scaffolding blocks are stripped
plain-text tool-call XML payload blocks such as <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, and <function_calls>...</function_calls> are stripped, including truncated payloads that never close cleanly
downgraded tool-call/result scaffolding such as [Tool Call: ...], [Tool Result ...], and [Historical context ...] is stripped
leaked model control tokens such as <|assistant|>, other ASCII <|...|> tokens, and full-width <｜...｜> variants are stripped
malformed MiniMax tool-call XML such as <invoke ...> / </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 [sessions_history omitted: message too large]
the tool reports summary flags such as truncated, droppedMessages, contentTruncated, contentRedacted, bytes, and pagination metadata

Managing session settings and groups

The owner-gated sessions tool exposes two bounded self-service surfaces:

주요 항목:

action: "patch" changes the current session by default, or another visible session selected by sessionKey. It can set the label, sidebar icon, pin/archive state, model, and thinking level. It does not expose reset, delete, or compact actions.
group_list, group_set, group_rename, and group_delete manage the global ordered session-group catalog. group_set replaces the ordered name list rather than patching one entry.

Sessions versus conversations

Sending cross-session messages

주요 항목:

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

Status and orchestration helpers

주요 항목:

origin is where the session was created, or the provider inferred from a deliverable session-key prefix when older state lacks stored origin metadata.
active is the current live-run route. It is only reported for the live or current session being handled now.
deliveryContext is the persisted delivery route stored on the session, which OpenClaw can reuse for later delivery even when the active surface differs.

Session state changes

Spawning sub-agents

주요 항목:

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.
context: "fork" for native sub-agents when the child needs the current requester transcript; omit it or use context: "isolated" for a clean child. context: "fork" is only valid with runtime: "subagent". Thread-bound native sub-agents default to context: "fork" unless threadBindings.defaultSpawnContext says otherwise.
visible: true to create a persistent dashboard session instead of a hidden sub-agent session. Visible spawns support an explicit model, working directory, same-agent transcript fork, and an optional managed worktree; see Sub-agents for the exact compatibility limits.

Visibility

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

Level	Scope
`self`	Only the current session
`tree`	Current + spawned; reads include watched same-agent groups
`agent`	All sessions for this agent
`all`	All sessions (cross-agent if configured)

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/session-tool
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Session tools

핵심 요약

문서 구성

상세 내용

본문

Available tools

Listing and reading sessions

Managing session settings and groups

Sessions versus conversations

Sending cross-session messages

Status and orchestration helpers

Session state changes

Spawning sub-agents

Visibility

Further reading

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Session tools

핵심 요약

문서 구성

상세 내용

본문

Available tools

Listing and reading sessions

Managing session settings and groups

Sessions versus conversations

Sending cross-session messages

Status and orchestration helpers

Session state changes

Spawning sub-agents

Visibility

Further reading

관련 문서

실습 체크리스트

관련 링크

관련 가이드