セッション管理の詳細解説

​

2つの永続化レイヤー

1. セッションストア (sessions.json) - キー/値マップ sessionKey -> SessionEntry。小さく、変更可能で、エントリの編集や削除が安全です。現在のセッション ID、最終アクティビティ、トグル、トークンカウンターなどのメタデータを追跡します。
2. トランスクリプト (<sessionId>.jsonl) - 追記専用でツリー構造（エントリは id + parentId を持つ）。会話、ツール呼び出し、Compaction サマリーを保存し、将来のターンのモデルコンテキストを再構築します。Compaction チェックポイントは、圧縮後の後続トランスクリプト上のメタデータです。新しい Compaction は、2つ目の .checkpoint.*.jsonl コピーを書き込みません。

​

ディスク上の場所

• ストア: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• トランスクリプト: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram トピックセッション: .../<sessionId>-topic-<threadId>.jsonl

​

ストアメンテナンスとディスク制御

1. 最も古いアーカイブ、孤立トランスクリプト、または孤立 trajectory 成果物を最初に削除します。
2. それでも目標を超えている場合は、最も古いセッションエントリとそのトランスクリプト/trajectory ファイルを削除します。
3. 使用量が highWaterBytes 以下になるまで繰り返します。

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Cron セッションと実行ログ

• cron.sessionRetention（デフォルト "24h"）は、古い分離 cron 実行セッションをストアからプルーニングします。false は無効化します。
• cron.runLog.keepLines は、cron ジョブごとに保持される SQLite 実行履歴行をプルーニングします（デフォルト 2000）。cron.runLog.maxBytes は、古いファイルベースの実行ログとの互換性のためにのみ受け付けられます。

​

セッションキー (sessionKey)

​

セッション ID (sessionId)

• リセット（/new、/reset）は、その sessionKey の新しい sessionId を作成します。
• 日次リセット（デフォルトは Gateway ホストのローカル時間で午前 4:00）は、リセット境界後の次のメッセージで新しい sessionId を作成します。
• アイドル期限切れ（session.reset.idleMinutes、またはレガシーの session.idleMinutes）は、アイドルウィンドウ後にメッセージが到着したときに新しい sessionId を作成します。日次とアイドルの両方が設定されている場合は、先に期限切れになった方が優先されます。
• Control UI 再接続再開は、Gateway がオペレーター UI クライアントから一致する sessionId を受け取った場合、1回の再接続送信について現在表示中のセッションを保持します。これは一度限りのシグナルです。通常の古い送信は引き続き新しい sessionId を作成します。
• システムイベント（heartbeat、cron wakeup、exec 通知、gateway bookkeeping）はセッション行を変更する場合がありますが、日次/アイドルリセットの鮮度を延長することはありません。リセットのロールオーバーは、新しいプロンプトが構築される前に、以前のセッションに対するキュー済みシステムイベント通知を破棄します。
• 親フォークポリシーは、スレッドまたはサブエージェントフォークを作成する際に OpenClaw のアクティブブランチを使用します。そのブランチが大きすぎる場合（固定の内部上限を超える場合。現在は 100K トークン）、OpenClaw は失敗したり使用不能な履歴を継承したりする代わりに、分離コンテキストで子を開始します。サイズ判定は自動で、設定できません。レガシーの session.parentForkMaxTokens 設定は openclaw doctor --fix によって削除されます。
• オペレーターフォーク: sessions.create { parentSessionKey, fork: true } は、親の現在の状態からトランスクリプトが分岐する新しいセッションを作成します（上記のサイズ上限を含む、サブエージェント spawn と同じフォーク機構）。親にアクティブな実行がある間はフォークが拒否され、明示的に渡されない限り親のモデル選択を継承し、子を新しいトークンカウンター付きの forkedFromParent としてマークします。

​

セッションストアスキーマ (sessions.json)

• sessionId: 現在のトランスクリプト id（sessionFile が設定されていない限り、ファイル名はこれから派生します）
• sessionStartedAt: 現在の sessionId の開始タイムスタンプ。日次リセットの鮮度判定にはこれを使用します。レガシー行では、JSONL セッションヘッダーから派生する場合があります。
• lastInteractionAt: 最後の実ユーザー/チャネル操作タイムスタンプ。アイドルリセットの鮮度判定にはこれを使用するため、Heartbeat、cron、exec イベントによってセッションが生存状態に保たれることはありません。このフィールドがないレガシー行では、復元されたセッション開始時刻にフォールバックします。
• updatedAt: 最後のストア行ミューテーションのタイムスタンプ。一覧表示/枝刈り/帳簿管理に使用されます。日次/アイドル鮮度判定の権威ではありません。
• archivedAt: 任意のアーカイブタイムスタンプ。アーカイブ済みセッションはトランスクリプトを保持したままストアに残り、通常のアクティブ一覧からは除外されます。
• pinnedAt: 任意のピン留めタイムスタンプ。アクティブなピン留め済みセッションは、ピン留めされていないセッションより前にソートされます。セッションをアーカイブすると、そのピン留めは解除されます。
• Codex スレッド相互運用: 両フィールドは Codex のスレッド管理形状に従います。ワイヤ上の archived/pinned ブール値は常にタイムスタンプから派生し、サーバー側でスタンプされます。これは Codex threads.archived_at セマンティクスと camelCase シリアライズに一致します。OpenClaw のタイムスタンプはエポックミリ秒ですが、Codex はエポック秒を使用するため、ブリッジは codex plugin 境界で変換します。Codex にはまだピン留め API がありません（thread/archive/thread/unarchive のみ）。そのため、ピン留め状態は API が存在するまで OpenClaw 側に留まり、存在した時点で、一致する形状によりバインド済みセッションがピン留め状態を機械的にラウンドトリップできるようになります。
• lastReadAt / markedUnreadAt: sessions.patch { unread } によってサーバー側でスタンプされる既読状態タイムスタンプ。unread: false は既読を記録します（lastReadAt を設定し、markedUnreadAt をクリアします）。unread: true は次の既読までセッションを未読としてマークします。セッション行は派生 unread ブール値を公開します。明示的に未読としてマークされている、または最新アクティビティより前に既読にされた場合です。一度も既読マークされていないセッションは unread: false のままなので、既存インストールがアップグレード時に点灯することはありません。
• lastActivityAt: 未読に値するアクティビティとしてカウントされる最後の完了済みエージェント実行（ユーザー、チャネル、cron 実行）のタイムスタンプ。Heartbeat と内部イベントターン、およびメタデータパッチでは更新されません。updatedAt はアクティビティ信号ではありません。
• sessionFile: 任意の明示的なトランスクリプトパス上書き
• chatType: direct | group | room
• provider, subject, room, space, displayName: グループ/チャネルのラベル付けメタデータ
• トグル: thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel, sendPolicy（セッション単位の上書き）
• モデル選択: providerOverride, modelOverride, authProfileOverride
• トークンカウンター（ベストエフォート/プロバイダー依存）: inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: このセッションキーで自動 Compaction が完了した回数
• memoryFlushAt / memoryFlushCompactionCount: 最後の Compaction 前メモリフラッシュのタイムスタンプと Compaction 回数

​

トランスクリプト構造（*.jsonl）

• 先頭行: セッションヘッダー - type: "session", id, cwd, timestamp, 任意の parentSession。
• 以降: id + parentId（ツリー構造）を持つエントリ。

• message: ユーザー/アシスタント/toolResult メッセージ
• custom_message: モデルコンテキストに入る拡張注入メッセージ（display: true の場合は TUI に表示され、display: false の場合は完全に非表示）
• custom: モデルコンテキストに入らない拡張状態（リロードをまたいで拡張状態を永続化するため）
• compaction: firstKeptEntryId と tokensBefore を持つ永続化された Compaction サマリー
• branch_summary: ツリーブランチを移動するときの永続化されたサマリー

​

コンテキストウィンドウと追跡トークン

1. モデルコンテキストウィンドウ: モデルごとのハード上限（モデルに見えるトークン）。モデルカタログから取得され、設定で上書きできます。
2. セッションストアカウンター: sessions.json に書き込まれるローリング統計（/status とダッシュボードで使用）。contextTokens はランタイムの推定/レポート値です。厳密な保証として扱わないでください。

​

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、およびその他のプロバイダー形状のバリアント）を返した場合、Compaction してから再試行します。プロバイダーが試行されたトークン数を報告する場合、OpenClaw はその観測値をオーバーフロー回復 Compaction に転送します。プロバイダーがオーバーフローを確認したものの解析可能な数値を公開しない場合、OpenClaw は Compaction エンジンと診断に、最小限に予算超過した合成カウントを渡します。オーバーフロー回復がそれでも失敗した場合、OpenClaw は明示的なガイダンスを表示し、新しいセッション id に暗黙的にローテーションする代わりに現在のセッションマッピングを保持します。メッセージを再試行するか、/compact を実行するか、/new を実行してください。
2. しきい値メンテナンス: 成功したターンの後、contextTokens > contextWindow - reserveTokens の場合。ここで contextWindow はモデルのコンテキストウィンドウで、reserveTokens はプロンプトと次のモデル出力のために予約された余裕です。

• プリフライトローカル Compaction: agents.defaults.compaction.maxActiveTranscriptBytes（バイト、または "20mb" のような文字列）を設定すると、アクティブなトランスクリプトファイルがそのサイズに達した後、次の実行を開く前にローカル Compaction をトリガーします。これはローカル再オープンコストのためのファイルサイズガードであり、生のアーカイブではありません。通常の意味的 Compaction は引き続き実行され、Compaction 済みサマリーが新しい後続トランスクリプトになるよう truncateAfterCompaction が必要です。
• ターン中プリチェック: agents.defaults.compaction.midTurnPrecheck.enabled: true（デフォルトは false）を設定すると、ツールループガードを追加します。ツール結果が追加された後、次のモデル呼び出しの前に、OpenClaw はターン開始時に使用するものと同じプリフライト予算ロジックでプロンプト圧力を推定します。コンテキストが収まらなくなった場合、このガードはインラインで Compaction しません。構造化されたターン中プリチェック信号を発生させ、現在のプロンプト送信を停止し、外側の実行ループに既存の回復パスを使用させます（それで十分な場合は過大なツール結果を切り詰める、または設定された Compaction モードをトリガーして再試行する）。プロバイダー支援 safeguard Compaction を含め、default と safeguard の両 Compaction モードで動作します。maxActiveTranscriptBytes とは独立しています。バイトサイズガードはターンを開く前に実行され、ターン中プリチェックは後で、新しいツール結果が追加された後に実行されます。

​

Compaction 設定

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

​

プラグ可能な Compaction プロバイダー

• provider: 登録済み Compaction プロバイダー plugin の id。デフォルトの LLM 要約を使う場合は未設定のままにします。provider を設定すると mode: "safeguard" が強制されます。
• プロバイダーは組み込みパスと同じ Compaction 指示および識別子保持ポリシーを受け取り、safeguard はプロバイダー出力後も最近ターンと分割ターンの接尾コンテキストを保持します。
• 組み込み safeguard 要約は、以前のサマリー全体を逐語的に保持するのではなく、新しいメッセージとともに以前のサマリーを再蒸留します。
• safeguard モードでは、サマリー品質監査がデフォルトで有効になります。形式不正出力時の再試行動作をスキップするには qualityGuard.enabled: false を設定します。
• プロバイダーが失敗するか空の結果を返した場合、OpenClaw は自動的に組み込み LLM 要約へフォールバックします。呼び出し元が明示的にトリガーした中止/タイムアウト信号は握りつぶされず再スローされるため、キャンセルは常に尊重されます。

​

ユーザーに見えるサーフェス

• 任意のチャットセッション内の /status
• openclaw status（CLI）
• openclaw sessions / openclaw sessions --json
• Gateway ログ（pnpm gateway:watch または openclaw logs --follow）: embedded run auto-compaction start + complete
• 詳細モード: 🧹 Auto-compaction complete と Compaction 回数

​

サイレントハウスキーピング（NO_REPLY）

• アシスタントは出力の先頭に正確なサイレントトークン NO_REPLY / no_reply を付けることで、「ユーザーに返信を配信しない」ことを意味します。OpenClaw は配信レイヤーでこれを除去/抑制します。
• 正確なサイレントトークンの抑制は大文字小文字を区別しません。ペイロード全体がサイレントトークンだけの場合、NO_REPLY と no_reply はどちらも該当します。
• 2026.1.10 以降、OpenClaw は部分チャンクが NO_REPLY で始まる場合、下書き/入力中ストリーミングも抑制するため、サイレント操作がターン途中で部分出力を漏らしません。
• これは真のバックグラウンド/非配信ターン専用です - 通常の対応可能なユーザーリクエストの近道ではありません。

​

Compaction 前のメモリフラッシュ

• デフォルトのプロンプト/システムプロンプトには、配信を抑制するための NO_REPLY ヒントが含まれています。
• model が設定されている場合、フラッシュターンはアクティブなセッションのフォールバックチェーンを継承せずにそのモデルを使用します。そのため、ローカル専用のハウスキーピングが失敗時に有料の会話モデルへ暗黙にフォールバックすることはありません。
• フラッシュは Compaction サイクルごとに1回実行されます（sessions.json で追跡）。
• フラッシュは埋め込み OpenClaw セッションでのみ実行されます。CLI バックエンドと Heartbeat ターンではスキップされます。
• セッションワークスペースが読み取り専用（workspaceAccess: "ro" または "none"）の場合、フラッシュはスキップされます。
• ワークスペースのファイルレイアウトと書き込みパターンについては、メモリ を参照してください。

​

トラブルシューティングチェックリスト

• セッションキーが間違っていますか？ /concepts/session から始め、/status の sessionKey を確認してください。
• ストアとトランスクリプトが一致しませんか？ openclaw status で Gateway ホストとストアパスを確認してください。
• Compaction が頻発しますか？ モデルのコンテキストウィンドウ（小さすぎると頻繁な Compaction が発生します）、reserveTokens（モデルウィンドウに対して高すぎると早期の Compaction が発生します）、ツール結果の肥大化（セッション pruning を調整）を確認してください。
• 小さなローカルモデルですべてのプロンプトがオーバーフローするように見えますか？ プロバイダーが正しいモデルコンテキストウィンドウを報告していることを確認してください。OpenClaw は、そのウィンドウが既知の場合にのみ有効な予約量を上限設定できます。
• サイレントターンが漏れていますか？ 返信が正確なサイレントトークン NO_REPLY（大文字小文字を区別しない）で始まっていること、およびストリーミング抑制修正（2026.1.10 以降）を含むビルドを使用していることを確認してください。

​

関連

• セッション管理
• セッション pruning
• コンテキストエンジン
• エージェント設定リファレンス