세션 관리 심층 분석

OpenClaw는 다음 영역 전반에서 세션을 처음부터 끝까지 관리합니다.

• 세션 라우팅(수신 메시지가 sessionKey에 매핑되는 방식)
• 세션 저장소(sessions.json)와 추적 항목
• 트랜스크립트 지속성(*.jsonl)과 그 구조
• 트랜스크립트 위생(실행 전 공급자별 보정)
• 컨텍스트 제한(컨텍스트 창과 추적된 토큰)
• Compaction(수동 및 자동 Compaction)과 Compaction 전 작업을 연결할 위치
• 무음 하우스키핑(사용자에게 보이는 출력을 만들면 안 되는 메모리 쓰기)

먼저 더 높은 수준의 개요를 보려면 다음에서 시작하세요.

• 세션 관리
• Compaction
• 메모리 개요
• 메모리 검색
• 세션 정리
• 트랜스크립트 위생

진실의 원천: Gateway

OpenClaw는 세션 상태를 소유하는 단일 Gateway 프로세스를 중심으로 설계되었습니다.

• UI(macOS 앱, 웹 Control UI, TUI)는 세션 목록과 토큰 수를 Gateway에 질의해야 합니다.
• 원격 모드에서는 세션 파일이 원격 호스트에 있습니다. "로컬 Mac 파일 확인"은 Gateway가 사용하는 내용을 반영하지 않습니다.

두 가지 지속성 계층

OpenClaw는 두 계층에 세션을 지속합니다.

1. 세션 저장소(sessions.json)

   • 키/값 맵: sessionKey -> SessionEntry
   • 작고, 변경 가능하며, 편집(또는 항목 삭제)해도 안전함
   • 세션 메타데이터(현재 세션 ID, 마지막 활동, 토글, 토큰 카운터 등)를 추적함

2. 트랜스크립트(<sessionId>.jsonl)

   • 트리 구조를 가진 추가 전용 트랜스크립트(항목에는 id + parentId가 있음)
   • 실제 대화 + 도구 호출 + Compaction 요약을 저장함
   • 이후 턴의 모델 컨텍스트를 다시 구성하는 데 사용됨
   • Compaction 체크포인트는 압축된 후속 트랜스크립트 위의 메타데이터입니다. 새 Compaction은 두 번째 .checkpoint.*.jsonl 사본을 쓰지 않습니다.

Gateway 기록 리더는 해당 표면에서 임의의 과거 접근이 명시적으로 필요한 경우가 아니라면 전체 트랜스크립트를 구체화하지 않아야 합니다. 첫 페이지 기록, 임베드된 채팅 기록, 재시작 복구, 토큰/사용량 검사는 제한된 꼬리 읽기를 사용합니다. 전체 트랜스크립트 스캔은 비동기 트랜스크립트 인덱스를 통하며, 이 인덱스는 파일 경로와 mtimeMs/size로 캐시되고 동시 리더 간에 공유됩니다.

디스크 위치

Gateway 호스트의 에이전트별 위치:

• 저장소: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• 트랜스크립트: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram 토픽 세션: .../<sessionId>-topic-<threadId>.jsonl

OpenClaw는 src/config/sessions.ts를 통해 이를 확인합니다.

저장소 유지관리 및 디스크 제어

세션 지속성에는 sessions.json, 트랜스크립트 아티팩트, 트래젝터리 사이드카를 위한 자동 유지관리 제어(session.maintenance)가 있습니다.

• mode: enforce(기본값) 또는 warn
• pruneAfter: 오래된 항목 연령 기준(기본값 30d)
• maxEntries: sessions.json의 항목 상한(기본값 500)
• 수명이 짧은 Gateway 모델 실행 프로브 보존 기간은 24h로 고정되어 있지만, 압력 기반으로 제한됩니다. 세션 항목 유지관리/상한 압력에 도달했을 때만 오래된 엄격 프로브 행을 제거합니다. 이는 agent:*:explicit:model-run-<uuid>와 일치하는 엄격한 명시적 프로브 키에만 적용되며, 실행될 때 전역 오래된 항목 정리/상한 적용 전에 실행됩니다.
• resetArchiveRetention: *.reset.<timestamp> 트랜스크립트 아카이브의 보존 기간(기본값: pruneAfter와 동일, false는 정리 비활성화)
• maxDiskBytes: 선택적 세션 디렉터리 예산
• highWaterBytes: 정리 후 선택적 목표값(기본값은 maxDiskBytes의 80%)

일반 Gateway 쓰기는 런타임 파일 잠금을 잡지 않고 프로세스 내 변이를 직렬화하는 저장소별 세션 작성기를 통해 흐릅니다. 핫 경로 패치 헬퍼는 해당 작성기 슬롯을 보유하는 동안 검증된 변경 가능 캐시를 빌리므로, 큰 sessions.json 파일을 모든 메타데이터 업데이트마다 복제하거나 다시 읽지 않습니다. 런타임 코드는 updateSessionStore(...) 또는 updateSessionStoreEntry(...)를 선호해야 합니다. 직접 전체 저장소 저장은 호환성 및 오프라인 유지관리 도구입니다. Gateway에 연결할 수 있으면, dry-run이 아닌 openclaw sessions cleanup 및 openclaw agents delete는 저장소 변이를 Gateway에 위임하여 정리가 같은 작성기 큐에 합류하게 합니다. --store <path>는 직접 파일 유지관리를 위한 명시적 오프라인 복구 경로입니다. maxEntries 정리는 여전히 프로덕션 크기 상한에 맞게 일괄 처리되므로, 다음 하이워터 정리가 이를 다시 낮춰 쓸 때까지 저장소가 구성된 상한을 잠시 초과할 수 있습니다. 세션 저장소 읽기는 Gateway 시작 중 항목을 정리하거나 상한을 적용하지 않습니다. 정리에는 쓰기 또는 openclaw sessions cleanup --enforce를 사용하세요. openclaw sessions cleanup --enforce는 디스크 예산이 구성되어 있지 않아도 구성된 상한을 즉시 적용하고 오래된 참조되지 않은 트랜스크립트, 체크포인트, 트래젝터리 아티팩트를 정리합니다.

유지관리는 그룹 세션 및 스레드 범위 채팅 세션 같은 내구성 있는 외부 대화 포인터를 유지하지만, Cron, 훅, Heartbeat, ACP, 하위 에이전트의 합성 런타임 항목은 구성된 연령, 개수 또는 디스크 예산을 초과하면 계속 제거될 수 있습니다. Gateway 모델 실행 프로브 세션은 키가 agent:*:explicit:model-run-<uuid>와 정확히 일치할 때만 별도의 24h 모델 실행 보존을 사용합니다. 다른 명시적 세션은 해당 보존 대상에 포함되지 않습니다. 모델 실행 정리는 세션 항목 상한 압력 아래에서만 적용됩니다. 격리된 Cron 실행은 모델 실행 프로브 보존과 독립적으로 자체 cron.sessionRetention 제어를 유지합니다.

OpenClaw는 더 이상 Gateway 쓰기 중 자동 sessions.json.bak.* 순환 백업을 만들지 않습니다. 레거시 session.maintenance.rotateBytes 키는 무시되며, openclaw doctor --fix는 이전 구성에서 이를 제거합니다.

트랜스크립트 변이는 트랜스크립트 파일의 세션 쓰기 잠금을 사용합니다. 잠금 획득은 사용 중인 세션 오류를 표시하기 전에 최대 session.writeLock.acquireTimeoutMs까지 기다립니다. 기본값은 60000ms입니다. 합법적인 준비, 정리, Compaction 또는 트랜스크립트 미러 작업이 느린 머신에서 더 오래 경합하는 경우에만 이를 올리세요. session.writeLock.staleMs는 기존 잠금을 오래된 것으로 간주해 회수할 수 있는 시점을 제어합니다. 기본값은 1800000ms입니다. session.writeLock.maxHoldMs는 프로세스 내 watchdog 해제 임계값을 제어합니다. 기본값은 300000ms입니다. 긴급 환경 변수 재정의는 OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS, OPENCLAW_SESSION_WRITE_LOCK_STALE_MS, OPENCLAW_SESSION_WRITE_LOCK_MAX_HOLD_MS입니다.

디스크 예산 정리의 적용 순서(mode: "enforce"):

1. 가장 오래된 보관된 아티팩트, 고아 트랜스크립트 또는 고아 트래젝터리 아티팩트를 먼저 제거합니다.
2. 그래도 목표값을 초과하면 가장 오래된 세션 항목과 해당 트랜스크립트/트래젝터리 파일을 제거합니다.
3. 사용량이 highWaterBytes 이하가 될 때까지 계속합니다.

mode: "warn"에서 OpenClaw는 잠재적 제거를 보고하지만 저장소/파일은 변경하지 않습니다.

필요 시 유지관리를 실행하세요.

openclaw sessions cleanup --dry-runopenclaw sessions cleanup --enforce

Cron 세션 및 실행 로그

격리된 Cron 실행도 세션 항목/트랜스크립트를 만들며, 전용 보존 제어가 있습니다.

• cron.sessionRetention(기본값 24h)은 세션 저장소에서 오래된 격리 Cron 실행 세션을 정리합니다(false는 비활성화).
• cron.runLog.keepLines는 Cron 작업별로 보존된 SQLite 실행 기록 행을 정리합니다(기본값: 2000). cron.runLog.maxBytes는 이전 파일 기반 실행 로그를 위해 계속 허용됩니다.

Cron이 새 격리 실행 세션을 강제로 만들 때, 새 행을 쓰기 전에 이전 cron:<jobId> 세션 항목을 정리합니다. thinking/fast/verbose 설정, 레이블, 명시적으로 사용자가 선택한 모델/auth 재정의 같은 안전한 기본 설정은 유지합니다. 채널/그룹 라우팅, 전송 또는 큐 정책, 승격, 출처, ACP 런타임 바인딩 같은 주변 대화 컨텍스트는 제거하여, 새 격리 실행이 이전 실행의 오래된 전달 또는 런타임 권한을 상속하지 못하게 합니다.

세션 키(sessionKey)

sessionKey는 사용자가 있는 대화 버킷(라우팅 + 격리)을 식별합니다.

일반적인 패턴:

• 기본/직접 채팅(에이전트별): agent:<agentId>:<mainKey>(기본값 main)
• 그룹: agent:<agentId>:<channel>:group:<id>
• 방/채널(Discord/Slack): agent:<agentId>:<channel>:channel:<id> 또는 ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid>(재정의되지 않은 경우)

표준 규칙은 /concepts/session에 문서화되어 있습니다.

세션 ID(sessionId)

각 sessionKey는 현재 sessionId(대화를 이어가는 트랜스크립트 파일)를 가리킵니다.

경험칙:

• 재설정(/new, /reset)은 해당 sessionKey에 대해 새 sessionId를 만듭니다.
• 일일 재설정(Gateway 호스트의 현지 시간 기준 기본 오전 4:00)은 재설정 경계 이후 다음 메시지에서 새 sessionId를 만듭니다.
• 유휴 만료(session.reset.idleMinutes 또는 레거시 session.idleMinutes)는 유휴 기간 후 메시지가 도착하면 새 sessionId를 만듭니다. 일일 + 유휴가 둘 다 구성된 경우 먼저 만료되는 쪽이 적용됩니다.
• Control UI 재연결 재개는 Gateway가 운영자 UI 클라이언트에서 일치하는 sessionId를 받으면 한 번의 재연결 전송에 대해 현재 표시된 세션을 보존할 수 있습니다. 일반적인 오래된 전송은 여전히 새 sessionId를 만듭니다.
• 시스템 이벤트(Heartbeat, Cron 깨우기, exec 알림, Gateway 부기)는 세션 행을 변경할 수 있지만 일일/유휴 재설정 신선도를 연장하지 않습니다. 재설정 롤오버는 새 프롬프트가 구성되기 전에 이전 세션의 대기 중인 시스템 이벤트 알림을 버립니다.
• 부모 포크 정책은 스레드 또는 하위 에이전트 포크를 만들 때 OpenClaw의 활성 브랜치를 사용합니다. 해당 브랜치가 너무 크면 OpenClaw는 실패하거나 사용할 수 없는 기록을 상속하는 대신 격리된 컨텍스트로 자식을 시작합니다. 크기 정책은 자동입니다. 레거시 session.parentForkMaxTokens 구성은 openclaw doctor --fix로 제거됩니다.

구현 세부사항: 이 결정은 src/auto-reply/reply/session.ts의 initSessionState()에서 이루어집니다.

세션 저장소 스키마(sessions.json)

저장소의 값 타입은 src/config/sessions.ts의 SessionEntry입니다.

주요 필드(전체 목록은 아님):

• sessionId: 현재 트랜스크립트 ID(sessionFile이 설정되지 않은 경우 파일 이름은 여기서 파생됨)
• sessionStartedAt: 현재 sessionId의 시작 타임스탬프. 일일 초기화 신선도는 이 값을 사용합니다. 레거시 행은 JSONL 세션 헤더에서 이를 파생할 수 있습니다.
• lastInteractionAt: 마지막 실제 사용자/채널 상호작용 타임스탬프. 유휴 초기화 신선도는 이 값을 사용하므로 Heartbeat, Cron, exec 이벤트가 세션을 계속 살아 있게 유지하지 않습니다. 이 필드가 없는 레거시 행은 유휴 신선도에 대해 복구된 세션 시작 시간으로 폴백합니다.
• updatedAt: 마지막 저장소 행 변경 타임스탬프로, 목록 표시, 정리, 그리고 부기 작업에 사용됩니다. 일일/유휴 초기화 신선도의 기준이 아닙니다.
• archivedAt: 선택적 아카이브 타임스탬프. 아카이브된 세션은 트랜스크립트를 그대로 유지한 채 저장소에 남으며 일반 활성 목록에서 제외됩니다.
• pinnedAt: 선택적 고정 타임스탬프. 활성 고정 세션은 고정되지 않은 세션보다 앞에 정렬됩니다. 세션을 아카이브하면 고정이 해제됩니다.
• Codex 스레드 상호 운용: 두 필드는 모두 Codex 스레드 관리 형식을 따릅니다 — 와이어의 archived/pinned 불리언은 항상 타임스탬프에서 파생되고 서버 측에서 스탬프되며, Codex threads.archived_at 의미 체계 및 camelCase 직렬화와 일치합니다. OpenClaw 타임스탬프는 epoch 밀리초인 반면 Codex는 epoch 초를 사용하므로 브리지는 codex Plugin 경계에서 변환합니다. Codex에는 아직 고정 API가 없습니다(thread/archive/thread/unarchive 전용). 고정 상태는 해당 API가 생길 때까지 OpenClaw 측에 남으며, 그 시점에는 일치하는 형식 덕분에 바인딩된 세션이 고정 상태를 기계적으로 왕복할 수 있습니다.
• sessionFile: 선택적 명시적 트랜스크립트 경로 재정의
• chatType: direct | group | room(UI와 전송 정책에 도움)
• provider, subject, room, space, displayName: 그룹/채널 레이블링용 메타데이터
• 토글:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy(세션별 재정의)
• 모델 선택:
  • providerOverride, modelOverride, authProfileOverride
• 토큰 카운터(최선의 노력 / 제공자에 따라 다름):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: 이 세션 키에 대해 자동 Compaction이 완료된 횟수
• memoryFlushAt: 마지막 사전 Compaction 메모리 플러시의 타임스탬프
• memoryFlushCompactionCount: 마지막 플러시가 실행되었을 때의 Compaction 횟수

저장소는 편집해도 안전하지만, Gateway가 기준입니다. 세션이 실행되는 동안 항목을 다시 쓰거나 재수화할 수 있습니다.

트랜스크립트 구조(*.jsonl)

트랜스크립트는 openclaw/plugin-sdk/agent-sessions의 SessionManager가 관리합니다.

파일은 JSONL입니다.

• 첫 줄: 세션 헤더(type: "session", id, cwd, timestamp, 선택적 parentSession 포함)
• 이후: id + parentId가 있는 세션 항목(트리)

주요 항목 유형:

• message: 사용자/어시스턴트/toolResult 메시지
• custom_message: 모델 컨텍스트에 들어가는 확장 주입 메시지(UI에서는 숨길 수 있음)
• custom: 모델 컨텍스트에 들어가지 않는 확장 상태
• compaction: firstKeptEntryId와 tokensBefore가 있는 영속화된 Compaction 요약
• branch_summary: 트리 브랜치를 탐색할 때 영속화되는 요약

OpenClaw는 의도적으로 트랜스크립트를 "수정"하지 않습니다. Gateway는 SessionManager를 사용해 이를 읽고 씁니다.

컨텍스트 창과 추적 토큰

두 가지 서로 다른 개념이 중요합니다.

1. 모델 컨텍스트 창: 모델별 하드 상한(모델에 보이는 토큰)
2. 세션 저장소 카운터: sessions.json에 기록되는 롤링 통계(/status와 대시보드에 사용)

한도를 조정하는 경우:

• 컨텍스트 창은 모델 카탈로그에서 가져옵니다(설정으로 재정의 가능).
• 저장소의 contextTokens는 런타임 추정/보고 값입니다. 이를 엄격한 보장으로 취급하지 마세요.

자세한 내용은 /token-use를 참조하세요.

Compaction: 정의

Compaction은 이전 대화를 트랜스크립트의 영속화된 compaction 항목으로 요약하고 최근 메시지는 그대로 유지합니다.

Compaction 이후 향후 턴에는 다음이 보입니다.

• Compaction 요약
• firstKeptEntryId 이후의 메시지

Compaction 이후 AGENTS.md 섹션 재주입은 agents.defaults.compaction.postCompactionSections를 통해 옵트인합니다. 설정되지 않았거나 []이면 OpenClaw는 Compaction 요약 위에 AGENTS.md 발췌문을 추가하지 않습니다.

Compaction은 영속적입니다(세션 정리와 다름). /concepts/session-pruning을 참조하세요.

Compaction 청크 경계와 도구 페어링

OpenClaw가 긴 트랜스크립트를 Compaction 청크로 나눌 때, 어시스턴트 도구 호출을 일치하는 toolResult 항목과 함께 유지합니다.

• 토큰 비율 분할 지점이 도구 호출과 그 결과 사이에 놓이면 OpenClaw는 쌍을 분리하는 대신 경계를 어시스턴트 도구 호출 메시지로 이동합니다.
• 뒤따르는 도구 결과 블록 때문에 청크가 목표를 초과하게 되는 경우, OpenClaw는 해당 대기 중인 도구 블록을 보존하고 요약되지 않은 꼬리 부분을 그대로 유지합니다.
• 중단/오류 도구 호출 블록은 대기 중인 분할을 열린 상태로 유지하지 않습니다.

자동 Compaction이 발생하는 시점(OpenClaw 런타임)

임베드된 OpenClaw 에이전트에서 자동 Compaction은 두 경우에 트리거됩니다.

1. 오버플로 복구: 모델이 컨텍스트 오버플로 오류를 반환함 (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded, 및 유사한 제공자 형식 변형) → 압축 → 재시도. 제공자가 시도한 토큰 수를 보고하면 OpenClaw는 관찰된 해당 수를 오버플로 복구 Compaction으로 전달합니다. 제공자가 오버플로를 확인하지만 파싱 가능한 수를 노출하지 않는 경우, OpenClaw는 예산을 최소한으로 초과한 합성 수를 Compaction 엔진과 진단에 전달합니다. 오버플로 복구가 여전히 실패하면 OpenClaw는 사용자에게 명시적인 지침을 표시하고, 세션 키를 새 세션 ID로 조용히 회전하는 대신 현재 세션 매핑을 보존합니다. 다음 단계는 운영자가 제어합니다. 메시지를 재시도하거나, /compact를 실행하거나, 새 세션이 더 적합하면 /new를 실행합니다.
2. 임계값 유지 관리: 성공적인 턴 이후 다음 조건일 때:

contextTokens > contextWindow - reserveTokens

여기서:

• contextWindow는 모델의 컨텍스트 창입니다.
• reserveTokens는 프롬프트 + 다음 모델 출력을 위해 예약된 여유 공간입니다.

이것이 OpenClaw 런타임 의미 체계입니다.

OpenClaw는 agents.defaults.compaction.maxActiveTranscriptBytes가 설정되어 있고 활성 트랜스크립트 파일이 해당 크기에 도달하면 다음 실행을 열기 전에 사전 local compaction도 트리거할 수 있습니다. 이는 로컬 재개방 비용을 위한 파일 크기 가드이지 원시 아카이브가 아닙니다. OpenClaw는 여전히 일반적인 의미론적 Compaction을 실행하며, 압축된 요약이 새 후속 트랜스크립트가 될 수 있도록 truncateAfterCompaction이 필요합니다.

임베드된 OpenClaw 실행의 경우 agents.defaults.compaction.midTurnPrecheck.enabled: true는 옵트인 도구 루프 가드를 추가합니다. 도구 결과가 추가된 후, 다음 모델 호출 전에 OpenClaw는 턴 시작 시 사용되는 것과 동일한 사전 검사 예산 로직을 사용해 프롬프트 압력을 추정합니다. 컨텍스트가 더 이상 맞지 않으면 가드는 OpenClaw 런타임의 transformContext 훅 안에서 압축하지 않습니다. 구조화된 턴 중간 사전 검사 신호를 발생시키고 현재 프롬프트 제출을 중지한 뒤, 외부 실행 루프가 기존 복구 경로를 사용하게 합니다. 충분한 경우 과도한 도구 결과를 잘라내거나, 구성된 Compaction 모드를 트리거하고 재시도합니다. 이 옵션은 기본적으로 비활성화되어 있으며 제공자 기반 safeguard Compaction을 포함해 default와 safeguard Compaction 모드 모두에서 작동합니다. 이는 maxActiveTranscriptBytes와 독립적입니다. 바이트 크기 가드는 턴이 열리기 전에 실행되고, 턴 중간 사전 검사는 새 도구 결과가 추가된 뒤 임베드된 OpenClaw 도구 루프에서 나중에 실행됩니다.

Compaction 설정(reserveTokens, keepRecentTokens)

OpenClaw 런타임의 Compaction 설정은 에이전트 설정에 있습니다.

{  compaction: {    enabled: true,    reserveTokens: 16384,    keepRecentTokens: 20000,  },}

OpenClaw는 임베드된 실행에 대해 안전 하한도 적용합니다.

• compaction.reserveTokens < reserveTokensFloor이면 OpenClaw가 이를 올립니다.
• 기본 하한은 20000 토큰입니다.
• 하한을 비활성화하려면 agents.defaults.compaction.reserveTokensFloor: 0을 설정하세요.
• 이미 더 높으면 OpenClaw는 그대로 둡니다.
• 수동 /compact는 명시적인 agents.defaults.compaction.keepRecentTokens를 존중하며 OpenClaw 런타임의 최근 꼬리 절단 지점을 유지합니다. 명시적인 유지 예산이 없으면 수동 Compaction은 하드 체크포인트로 남고 재구성된 컨텍스트는 새 요약에서 시작합니다.
• 새 도구 결과 이후, 다음 모델 호출 전에 선택적 도구 루프 사전 검사를 실행하려면 agents.defaults.compaction.midTurnPrecheck.enabled: true를 설정하세요. 이는 트리거일 뿐입니다. 요약 생성은 여전히 구성된 Compaction 경로를 사용합니다. 이는 턴 시작 활성 트랜스크립트 바이트 크기 가드인 maxActiveTranscriptBytes와 독립적입니다.
• 활성 트랜스크립트가 커졌을 때 턴 전에 local compaction을 실행하려면 agents.defaults.compaction.maxActiveTranscriptBytes를 바이트 값이나 "20mb" 같은 문자열로 설정하세요. 이 가드는 truncateAfterCompaction도 활성화된 경우에만 작동합니다. 비활성화하려면 설정하지 않거나 0으로 설정하세요.
• agents.defaults.compaction.truncateAfterCompaction이 활성화되면, OpenClaw는 Compaction 이후 활성 트랜스크립트를 압축된 후속 JSONL로 회전합니다. 브랜치/복원 체크포인트 작업은 해당 압축된 후속 항목을 사용합니다. 레거시 사전 Compaction 체크포인트 파일은 참조되는 동안 계속 읽을 수 있습니다.

이유: Compaction이 불가피해지기 전에 여러 턴의 "하우스키핑"(예: 메모리 쓰기)을 위한 충분한 여유 공간을 남기기 위해서입니다.

구현: src/agents/agent-settings.ts의 applyAgentCompactionSettingsFromConfig() (임베드된 러너 턴 및 Compaction 설정 경로에서 호출됨).

플러그형 Compaction 제공자

Plugin은 Plugin API의 registerCompactionProvider()를 통해 Compaction 제공자를 등록할 수 있습니다. agents.defaults.compaction.provider가 등록된 제공자 ID로 설정되면, safeguard 확장은 내장 summarizeInStages 파이프라인 대신 해당 제공자에게 요약을 위임합니다.

• provider: 등록된 Compaction 제공자 Plugin의 ID입니다. 기본 LLM 요약을 사용하려면 설정하지 마세요.
• provider를 설정하면 mode: "safeguard"가 강제됩니다.
• 제공자는 내장 경로와 동일한 Compaction 지침 및 식별자 보존 정책을 받습니다.
• safeguard는 제공자 출력 이후에도 최근 턴 및 분할 턴 접미사 컨텍스트를 보존합니다.
• 내장 safeguard 요약은 이전 요약 전체를 그대로 보존하는 대신 새 메시지와 함께 이전 요약을 다시 증류합니다.
• safeguard 모드는 기본적으로 요약 품질 감사를 활성화합니다. 잘못된 형식의 출력에 대한 재시도 동작을 건너뛰려면 qualityGuard.enabled: false를 설정하세요.
• 제공자가 실패하거나 빈 결과를 반환하면 OpenClaw는 자동으로 내장 LLM 요약으로 폴백합니다.
• 중단/타임아웃 신호는 호출자 취소를 존중하기 위해 다시 던져집니다(삼키지 않음).

소스: src/plugins/compaction-provider.ts, src/agents/agent-hooks/compaction-safeguard.ts.

사용자에게 보이는 표면

Compaction과 세션 상태는 다음을 통해 관찰할 수 있습니다.

• /status(모든 채팅 세션에서)
• openclaw status(CLI)
• openclaw sessions / sessions --json
• Gateway 로그(pnpm gateway:watch 또는 openclaw logs --follow): embedded run auto-compaction start + complete
• 자세한 모드: 🧹 Auto-compaction complete + Compaction 횟수

조용한 하우스키핑(NO_REPLY)

OpenClaw는 사용자가 중간 출력을 보지 않아야 하는 백그라운드 작업을 위한 "조용한" 턴을 지원합니다.

규칙:

• 어시스턴트는 "사용자에게 답장을 전달하지 않음"을 나타내기 위해 정확한 무음 토큰 NO_REPLY / no_reply로 출력을 시작합니다.
• OpenClaw는 전달 계층에서 이를 제거/억제합니다.
• 정확한 무음 토큰 억제는 대소문자를 구분하지 않으므로, 전체 페이로드가 무음 토큰만인 경우 NO_REPLY와 no_reply가 모두 해당됩니다.
• 이는 진정한 백그라운드/전달 없음 턴 전용입니다. 일반적인 실행 가능한 사용자 요청을 위한 지름길이 아닙니다.

2026.1.10부터 OpenClaw는 부분 청크가 NO_REPLY로 시작할 때 초안/입력 중 스트리밍도 억제하므로, 무음 작업이 턴 도중 부분 출력을 누출하지 않습니다.

Compaction 전 "메모리 플러시" (구현됨)

목표: 자동 Compaction이 발생하기 전에 지속 상태를 디스크에 쓰는 무음 에이전트 턴을 실행합니다 (예: 에이전트 워크스페이스의 memory/YYYY-MM-DD.md). 이렇게 하면 Compaction이 중요한 컨텍스트를 지울 수 없습니다.

OpenClaw는 사전 임계값 플러시 방식을 사용합니다.

1. 세션 컨텍스트 사용량을 모니터링합니다.
2. 사용량이 "소프트 임계값"(OpenClaw 런타임의 Compaction 임계값보다 낮음)을 넘으면 에이전트에 무음 "지금 메모리 쓰기" 지시를 실행합니다.
3. 정확한 무음 토큰 NO_REPLY / no_reply를 사용하여 사용자가 아무것도 보지 않도록 합니다.

설정(agents.defaults.compaction.memoryFlush):

• enabled (기본값: true)
• model (플러시 턴에 대한 선택적 정확한 제공자/모델 재정의, 예: ollama/qwen3:8b)
• softThresholdTokens (기본값: 4000)
• prompt (플러시 턴의 사용자 메시지)
• systemPrompt (플러시 턴에 추가로 덧붙이는 시스템 프롬프트)

참고:

• 기본 프롬프트/시스템 프롬프트에는 전달을 억제하기 위한 NO_REPLY 힌트가 포함됩니다.
• model이 설정되면 플러시 턴은 활성 세션 폴백 체인을 상속하지 않고 해당 모델을 사용하므로, 로컬 전용 하우스키핑이 유료 대화 모델로 조용히 폴백하지 않습니다.
• 플러시는 Compaction 주기마다 한 번 실행됩니다(sessions.json에서 추적됨).
• 플러시는 임베디드 OpenClaw 세션에서만 실행됩니다(CLI 백엔드는 건너뜁니다).
• 세션 워크스페이스가 읽기 전용(workspaceAccess: "ro" 또는 "none")이면 플러시를 건너뜁니다.
• 워크스페이스 파일 레이아웃과 쓰기 패턴은 메모리를 참조하세요.

OpenClaw는 확장 API에 session_before_compact 훅도 노출하지만, 현재 OpenClaw의 플러시 로직은 Gateway 측에 있습니다.

문제 해결 체크리스트

• 세션 키가 잘못되었나요? /concepts/session에서 시작하고 /status의 sessionKey를 확인하세요.
• 저장소와 트랜스크립트가 일치하지 않나요? openclaw status에서 Gateway 호스트와 저장소 경로를 확인하세요.
• Compaction이 과도하게 발생하나요? 다음을 확인하세요.
  • 모델 컨텍스트 창(너무 작음)
  • Compaction 설정(모델 창에 비해 reserveTokens가 너무 높으면 Compaction이 더 일찍 발생할 수 있음)
  • 도구 결과 팽창: 세션 가지치기를 활성화/조정하세요
• 무음 턴이 누출되나요? 답장이 NO_REPLY(대소문자를 구분하지 않는 정확한 토큰)로 시작하는지, 그리고 스트리밍 억제 수정이 포함된 빌드인지 확인하세요.

관련

• 세션 관리
• 세션 가지치기
• 컨텍스트 엔진