Session state awareness

기준일: 2026-07-26
공식 기준: Session state awareness

Session state awareness 문서는 OpenClaw 공식 문서(concepts/session-state)를 한국어로 정리한 가이드입니다. Durable session state signal log: state versions, watchers, stale-state notices, and reconciliation 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Durable session state signal log: state versions, watchers, stale-state notices, and reconciliation

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

문서 구성

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

• The signal log
• Watchers
• Notices: one, not many
• Reconciling
• Storage and limits
• 관련 문서

상세 내용

본문

When several sessions work on the same problem — a manager delegating to children, a human jumping directly into a worker session, two agents coordinating over sessions_send — each session builds assumptions about the others. Those assumptions go stale the moment another actor intervenes. Session state awareness is the machinery that detects the intervention, tells the affected session once, and gives it a cheap way to catch up before acting.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

The signal log

OpenClaw appends a typed event to the shared state database (session_state_events) when a watched session materially changes. Events carry metadata and a one-line summary — never message content.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Kind	Recorded when	Notifies watchers
human_direct_message	A human sends a turn directly to a watched session	Yes
upstream_missing	An adopted session's upstream source disappears	Yes
goal_changed	The session's goal state is created, updated, or cleared	Yes
child_spawned	A sub-agent or ACP child session is created	No (seeds cursor)
run_completed	A child run ends successfully	No (log only)
run_failed	A child run fails, times out, or is cancelled	No (log only)
compacted	The session's history is compacted	No (log only)
adopted	A catalog session is adopted into OpenClaw	No (log only)

Watchers

A watcher is a session that holds a cursor (session_watch_cursors) on a target. Cursors come from two places:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Implicit (spawn edges). When a session spawns a sub-agent or ACP child, the parent's cursor is seeded automatically at the child's spawn version. Parents never subscribe manually.
• Explicit (sessions_send watch: true). Any coordinator can watch a non-spawned target: pass watch: true on sessions_send, and after the send dispatches successfully the sender is registered as a watcher of the session that actually received the message. Registration starts at the target's current state version — prior history never produces notices. The tool result reports watched: true|false when the parameter was set.

Notices: one, not many

When a notify-eligible event lands and a watcher's cursor is behind, the watcher receives one system notice on its next turn:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• One pending notice per watcher/target pair. The notice text is byte-stable while pending and the system-event queue dedupes on it, so twenty rapid changes to the same target still produce a single line in the watcher's prompt.
• Frozen watermark. The cursor freezes its notified position when a notice is queued. Further material events advance only the material watermark; they do not re-notify.
• Acknowledge on drain, reopen only for interleaved work. When the watcher's turn consumes the notice, the cursor advances. If more material events arrived between queueing and draining, exactly one fresh notice is opened for the remainder.
• Self-suppression. A watcher never gets notified about events it caused itself.
• Restart recovery. Pending notices live in an in-memory queue; a startup sweep re-materializes them from durable cursors after a gateway restart.

Session "agent:main:subagent:child" changed (other actor). Reconcile before acting: session_status sessionKey "agent:main:subagent:child" changesSince 12.

Reconciling

The notice tells the watcher exactly what to do. session_status with changesSince: returns the typed events after that version (up to 200), without advancing any cursors:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "human message via telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "goal updated" }
    ],
    "historyGap": false
  }
}

Storage and limits

History lives in the shared state database, bounded to 30 days and 50,000 rows; per-session heads stay monotonic after pruning. Recording is best-effort — a failed append is logged and never fails the originating turn — so stateVersion is a signal-log head, not a transactional change-data-capture version.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Notice delivery assumes one gateway process owns the shared state database. Multiple gateways share the durable log and changesSince, but v1 does not push notices across processes.
• Compaction events cover the embedded runtime's compaction owners; native-harness-only compaction is not fully logged.
• Cancelled-outcome payload detail is currently produced by ACP child runs; native sub-agent cancellations surface as generic failures.
• Upstream self-echo detection compares normalized user text. An external prompt matching one of the session's 10 most recent OpenClaw-side user messages is treated as self-echo.
• A single local Claude JSONL row larger than the 1 MiB per-cadence scan cap blocks that session's cursor in v1; unclassified bytes are never skipped.
• Paired-node Claude checks classify the latest 50 transcript items per cadence. Larger bursts can fall outside the v1 scan window.
• Paired-node Claude history reads do not expose a definitive thread-not-found result, so remote Claude deletions are not classified as upstream_missing in v1.
• Catalog sessions that have not been adopted remain outside the awareness layer in v1.
• Sessions adopted before this feature carry no upstream link; continue them from the catalog once to start upstream monitoring.
• Upstream links assume each adopted session key maps to one owning agent (adoption uses the default store agent). Multi-agent adoption of the same external thread is not monitored in v1.

관련 문서

주요 항목:

• Session tools — sessions_send, session_status, sessions_list
• Sub-agents — spawn edges and completion announcements
• Heartbeat — how queued notices wake main sessions
• Session management — session keys, scopes, lifecycle

실습 체크리스트

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

자주 쓰는 명령·설정 예시

Session "agent:main:subagent:child" changed (other actor). Reconcile before acting: session_status sessionKey "agent:main:subagent:child" changesSince 12.

{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "human message via telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "goal updated" }
    ],
    "historyGap": false
  }
}

관련 링크

• 공식 원문: concepts/session-state
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.