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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• セッションルーティング (受信メッセージを sessionKey に対応付ける方法)
• セッションストア (sessions.json) と、それが追跡する内容
• トランスクリプトの永続化 (*.jsonl) とその構造
• トランスクリプト衛生 (実行前のプロバイダー固有の修正)
• コンテキスト制限 (コンテキストウィンドウと追跡トークン)
• Compaction (手動および自動 Compaction) と、Compaction 前処理をフックする場所
• サイレントハウスキーピング (ユーザーに見える出力を生成すべきではないメモリ書き込み)

• セッション管理
• Compaction
• メモリ概要
• メモリ検索
• セッション枝刈り
• トランスクリプト衛生

​

信頼できる情報源: Gateway

• UI (macOS アプリ、Web コントロール UI、TUI) は、セッション一覧とトークン数を Gateway に問い合わせる必要があります。
• リモートモードでは、セッションファイルはリモートホスト上にあります。「ローカル Mac ファイルを確認する」だけでは、Gateway が使用している内容は反映されません。

​

2 つの永続化レイヤー

1. セッションストア (sessions.json)
   • キー/値マップ: sessionKey -> SessionEntry
   • 小さく、変更可能で、編集 (またはエントリ削除) しても安全
   • セッションメタデータ (現在のセッション ID、最終アクティビティ、トグル、トークンカウンターなど) を追跡します
2. トランスクリプト (<sessionId>.jsonl)
   • ツリー構造を持つ追記専用トランスクリプト (エントリには id + parentId があります)
   • 実際の会話 + ツール呼び出し + Compaction サマリーを保存します
   • 将来のターンでモデルコンテキストを再構築するために使用されます
   • アクティブなトランスクリプトがチェックポイントサイズ上限を超えると、大きな Compaction 前デバッグチェックポイントはスキップされ、 2 つ目の巨大な .checkpoint.*.jsonl コピーを避けます。

​

ディスク上の場所

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

​

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

• mode: warn (デフォルト) または enforce
• pruneAfter: 古いエントリの経過時間カットオフ (デフォルト 30d)
• maxEntries: sessions.json 内のエントリ上限 (デフォルト 500)
• resetArchiveRetention: *.reset.<timestamp> トランスクリプトアーカイブの保持期間 (デフォルト: pruneAfter と同じ。false でクリーンアップを無効化)
• maxDiskBytes: 任意のセッションディレクトリ予算
• highWaterBytes: クリーンアップ後の任意の目標値 (デフォルトは maxDiskBytes の 80%)

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

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

​

Cron セッションと実行ログ

• cron.sessionRetention (デフォルト 24h) は、古い分離 cron 実行セッションをセッションストアから枝刈りします (false で無効化)。
• cron.runLog.maxBytes + cron.runLog.keepLines は、~/.openclaw/cron/runs/<jobId>.jsonl ファイルを枝刈りします (デフォルト: 2_000_000 バイトおよび 2000 行)。

​

セッションキー (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> (上書きされていない場合)

​

セッション ID (sessionId)

• リセット (/new, /reset) は、その sessionKey に対して新しい sessionId を作成します。
• 日次リセット (デフォルトでは Gateway ホストのローカル時刻で午前 4:00) は、リセット境界後の次のメッセージで新しい sessionId を作成します。
• アイドル期限切れ (session.reset.idleMinutes または従来の session.idleMinutes) は、アイドルウィンドウ後にメッセージが到着したときに新しい sessionId を作成します。日次とアイドルの両方が設定されている場合は、先に期限切れになったほうが優先されます。
• システムイベント (heartbeat、cron wakeup、exec 通知、gateway ブックキーピング) は、セッション行を変更する場合がありますが、日次/アイドルリセットの新鮮さは延長しません。リセットのロールオーバーでは、新しいプロンプトが構築される前に、前のセッション向けにキューされたシステムイベント通知が破棄されます。
• 親フォークポリシー は、スレッドまたはサブエージェントフォークを作成するときに PI のアクティブブランチを使用します。そのブランチが大きすぎる場合、OpenClaw は失敗したり使用不能な履歴を継承したりする代わりに、分離コンテキストで子を開始します。サイズ決定ポリシーは自動です。従来の session.parentForkMaxTokens 設定は openclaw doctor --fix によって削除されます。

​

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

• sessionId: 現在のトランスクリプト ID (sessionFile が設定されていない限り、ファイル名はこれから派生します)
• sessionStartedAt: 現在の sessionId の開始タイムスタンプ。日次リセットの 新鮮さはこれを使用します。従来の行では、JSONL セッションヘッダーから派生する場合があります。
• lastInteractionAt: 最後の実ユーザー/チャンネルインタラクションのタイムスタンプ。アイドルリセットの 新鮮さはこれを使用するため、heartbeat、cron、exec イベントによってセッションが 生き続けることはありません。このフィールドのない従来の行は、復元されたセッション開始 時刻にフォールバックしてアイドルの新鮮さを判断します。
• updatedAt: 最後のストア行変更タイムスタンプ。一覧表示、枝刈り、 ブックキーピングに使用されます。これは日次/アイドルリセットの新鮮さに関する権威ではありません。
• 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 回数

​

トランスクリプト構造 (*.jsonl)

• 最初の行: セッションヘッダー (type: "session"、id、cwd、timestamp、任意の parentSession を含みます)
• その後: id + parentId を持つセッションエントリ (ツリー)

• message: ユーザー/アシスタント/toolResult メッセージ
• custom_message: モデルコンテキストに 入る 拡張機能注入メッセージ (UI から非表示にできます)
• custom: モデルコンテキストに 入らない 拡張機能状態
• compaction: firstKeptEntryId と tokensBefore を持つ永続化された Compaction サマリー
• branch_summary: ツリーブランチを移動するときに永続化されるサマリー

​

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

1. モデルコンテキストウィンドウ: モデルごとのハード上限 (モデルに見えるトークン)
2. セッションストアカウンター: sessions.json に書き込まれるローリング統計 (/status とダッシュボードに使用)

• コンテキストウィンドウはモデルカタログから取得されます (設定で上書き可能)。
• ストア内の contextTokens はランタイムの推定/レポート値です。厳密な保証として扱わないでください。

​

Compaction: 概要

• Compaction サマリー
• firstKeptEntryId 以降のメッセージ

​

Compaction チャンク境界とツールのペアリング

• トークン比率による分割位置がツール呼び出しとその結果の間に来る場合、OpenClaw はそのペアを分離する代わりに、境界をアシスタントのツール呼び出しメッセージへ移動します。
• 末尾のツール結果ブロックによってチャンクが目標を超えてしまう場合でも、OpenClaw はその保留中のツールブロックを保持し、要約されていない末尾部分をそのまま維持します。
• 中止またはエラーになったツール呼び出しブロックは、保留中の分割を開いたままにはしません。

​

自動 Compaction が発生するタイミング（Pi ランタイム）

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、および同様のプロバイダー形式の変種）を返す → 圧縮 → 再試行。
2. しきい値メンテナンス: 成功したターンの後、次の場合:

• contextWindow はモデルのコンテキストウィンドウ
• reserveTokens はプロンプトと次のモデル出力のために予約された余裕

​

Compaction 設定（reserveTokens、keepRecentTokens）

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

• compaction.reserveTokens < reserveTokensFloor の場合、OpenClaw はそれを引き上げます。
• デフォルトの下限は 20000 トークンです。
• 下限を無効にするには agents.defaults.compaction.reserveTokensFloor: 0 を設定します。
• すでにそれより高い場合、OpenClaw はそのままにします。
• 手動の /compact は明示的な agents.defaults.compaction.keepRecentTokens を尊重し、Pi の直近末尾の切断点を維持します。明示的な保持予算がない場合、手動 Compaction はハードチェックポイントのままで、再構築されたコンテキストは新しい要約から開始されます。
• 新しいツール結果の後、次のモデル呼び出しの前に任意のツールループプリチェックを実行するには、agents.defaults.compaction.midTurnPrecheck.enabled: true を設定します。これはトリガーのみです。要約生成は引き続き設定済みの Compaction パスを使います。これは maxActiveTranscriptBytes とは独立しており、maxActiveTranscriptBytes はターン開始時のアクティブトランスクリプトのバイトサイズガードです。
• アクティブなトランスクリプトが大きくなったとき、ターン前にローカル Compaction を実行するには、agents.defaults.compaction.maxActiveTranscriptBytes にバイト値または "20mb" のような文字列を設定します。このガードは truncateAfterCompaction も有効な場合にのみ有効です。無効にするには未設定のままにするか、0 を設定します。
• agents.defaults.compaction.truncateAfterCompaction が有効な場合、OpenClaw は Compaction 後に、アクティブなトランスクリプトを圧縮済みの後続 JSONL へローテートします。古い完全なトランスクリプトはその場で書き換えられるのではなく、アーカイブされたまま Compaction チェックポイントからリンクされます。

​

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

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

​

ユーザーに表示されるサーフェス

• /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）

• アシスタントは、ユーザーに返信を届けないことを示すために、正確なサイレントトークン NO_REPLY / no_reply で出力を開始します。
• OpenClaw は配信レイヤーでこれを取り除くか抑制します。
• 正確なサイレントトークンの抑制は大文字小文字を区別しないため、ペイロード全体がそのサイレントトークンだけである場合、NO_REPLY と no_reply はどちらも対象になります。
• これは真のバックグラウンドまたは未配信ターン専用です。通常の実行可能なユーザー要求のショートカットではありません。

​

Compaction 前の「メモリフラッシュ」（実装済み）

1. セッションコンテキスト使用量を監視します。
2. Pi の Compaction しきい値より低い「ソフトしきい値」を超えたら、エージェントにサイレントな「今すぐメモリを書き込む」指示を実行します。
3. ユーザーに何も見えないように、正確なサイレントトークン NO_REPLY / no_reply を使います。

• enabled（デフォルト: true）
• model（任意。フラッシュターン用の正確なプロバイダー/モデル上書き。例: ollama/qwen3:8b）
• softThresholdTokens（デフォルト: 4000）
• prompt（フラッシュターン用のユーザーメッセージ）
• systemPrompt（フラッシュターン用に追加される追加システムプロンプト）

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

​

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

• セッションキーが間違っていますか？/concepts/session から始めて、/status の sessionKey を確認してください。
• ストアとトランスクリプトが一致しませんか？openclaw status で Gateway ホストとストアパスを確認してください。
• Compaction が多発しますか？確認してください:
  • モデルのコンテキストウィンドウ（小さすぎる）
  • Compaction 設定（reserveTokens がモデルウィンドウに対して高すぎると、より早い Compaction が発生する可能性があります）
  • ツール結果の肥大化: セッションプルーニングを有効化/調整してください
• サイレントターンが漏れていますか？返信が NO_REPLY（大文字小文字を区別しない正確なトークン）で始まっていること、およびストリーミング抑制修正を含むビルドを使っていることを確認してください。

​

関連

• セッション管理
• セッションプルーニング
• コンテキストエンジン