​

Session Management & Compaction（詳細解説）

• セッションルーティング（受信メッセージがどのように sessionKey に対応付けられるか）
• セッションストア（sessions.json）と、そこで追跡される内容
• Transcript の永続化（*.jsonl）とその構造
• Transcript hygiene（実行前の provider 固有 fixup）
• コンテキスト制限（コンテキストウィンドウと追跡トークンの違い）
• Compaction（手動 + 自動 compaction）と、pre-compaction 処理をフックする場所
• サイレントなハウスキーピング（例: ユーザーに見える出力を生成すべきでないメモリ書き込み）

• /concepts/session
• /concepts/compaction
• /concepts/memory
• /concepts/memory-search
• /concepts/session-pruning
• /reference/transcript-hygiene

​

信頼できる唯一の情報源: Gateway

• UI（macOS app、web Control UI、TUI）は、セッション一覧とトークン数を Gateway に問い合わせるべきです。
• リモートモードでは、セッションファイルはリモートホスト上にあります。「ローカル Mac 上のファイルを確認する」だけでは、Gateway が実際に使っている内容は反映されません。

​

2 つの永続化レイヤー

1. Session store（sessions.json）
   • キー/値マップ: sessionKey -> SessionEntry
   • 小さく、可変で、編集も安全（エントリの削除も可能）
   • セッションメタデータ（現在の session id、最終アクティビティ、トグル、トークンカウンターなど）を追跡します
2. Transcript（<sessionId>.jsonl）
   • ツリー構造を持つ追記専用 transcript（エントリは id + parentId を持つ）
   • 実際の会話 + tool call + compaction summary を保存します
   • 将来のターンでモデルコンテキストを再構築するために使われます

​

ディスク上の場所

• Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcript: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram topic セッション: .../<sessionId>-topic-<threadId>.jsonl

​

Store メンテナンスとディスク制御

• mode: warn（デフォルト）または enforce
• pruneAfter: 古いエントリの期限切れしきい値（デフォルト 30d）
• maxEntries: sessions.json 内のエントリ数上限（デフォルト 500）
• rotateBytes: サイズ超過時に sessions.json をローテーションするしきい値（デフォルト 10mb）
• resetArchiveRetention: *.reset.<timestamp> transcript archive の保持期間（デフォルト: pruneAfter と同じ。false でクリーンアップ無効）
• maxDiskBytes: 任意の sessions ディレクトリ予算
• highWaterBytes: クリーンアップ後の任意ターゲット（デフォルトは maxDiskBytes の 80%）

1. まず、最も古い archive 済みまたは orphan の transcript アーティファクトを削除します。
2. まだターゲットを超えている場合は、最も古いセッションエントリとそれに対応する transcript ファイルを削除します。
3. 使用量が highWaterBytes 以下になるまで続けます。

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

​

Cron セッションと実行ログ

• cron.sessionRetention（デフォルト 24h）は、session store から古い分離 cron 実行セッションを削除します（false で無効）。
• cron.runLog.maxBytes + cron.runLog.keepLines は ~/.openclaw/cron/runs/<jobId>.jsonl ファイルを剪定します（デフォルト: 2_000_000 bytes と 2000 lines）。

​

Session key（sessionKey）

• Main/direct chat（agent ごと）: agent:<agentId>:<mainKey>（デフォルト main）
• Group: agent:<agentId>:<channel>:group:<id>
• Room/channel（Discord/Slack）: agent:<agentId>:<channel>:channel:<id> または ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid>（上書きされない限り）

​

Session id（sessionId）

• Reset（/new、/reset）は、その sessionKey 用に新しい sessionId を作成します。
• 日次リセット（デフォルトでは Gateway ホストのローカル時刻で午前 4:00）は、リセット境界を越えた後の次のメッセージで新しい sessionId を作成します。
• Idle expiry（session.reset.idleMinutes またはレガシーの session.idleMinutes）は、アイドル期間後にメッセージが到着すると新しい sessionId を作成します。日次と idle の両方が設定されている場合は、先に期限切れになる方が優先されます。
• Thread parent fork guard（session.parentForkMaxTokens、デフォルト 100000）は、親セッションがすでに大きすぎる場合に親 transcript の fork をスキップします。新しいスレッドは新規開始されます。無効にするには 0 を設定します。

​

Session store schema（sessions.json）

• sessionId: 現在の transcript id（sessionFile が設定されていない限りファイル名はこれから導出される）
• updatedAt: 最終アクティビティのタイムスタンプ
• sessionFile: 任意の明示的 transcript パス override
• chatType: direct | group | room（UI や送信 policy の補助）
• provider, subject, room, space, displayName: group/channel ラベル用メタデータ
• トグル:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy（セッションごとの override）
• モデル選択:
  • providerOverride, modelOverride, authProfileOverride
• トークンカウンター（ベストエフォート / provider 依存）:
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: この session key で自動 compaction が完了した回数
• memoryFlushAt: 最後の pre-compaction memory flush のタイムスタンプ
• memoryFlushCompactionCount: 最後の flush 実行時点の compaction count

​

Transcript 構造（*.jsonl）

• 1 行目: セッションヘッダー（type: "session"、id、cwd、timestamp、任意で parentSession を含む）
• 以降: id + parentId を持つセッションエントリ（ツリー）

• message: user/assistant/toolResult メッセージ
• custom_message: 拡張機能が注入するメッセージで、モデルコンテキストには入るもの（UI では非表示にもできる）
• custom: モデルコンテキストには入らない拡張状態
• compaction: firstKeptEntryId と tokensBefore を含む永続化された compaction summary
• branch_summary: ツリー分岐を移動するときの永続化 summary

​

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

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

• コンテキストウィンドウはモデルカタログから取得されます（config で override も可能）。
• store の contextTokens はランタイムの推定/報告値であり、厳密な保証として扱わないでください。

​

Compaction とは何か

• compaction summary
• firstKeptEntryId 以降のメッセージ

​

Compaction のチャンク境界と tool のペアリング

• トークン比率による分割が tool call とその結果の間に来る場合、OpenClaw はペアを分離する代わりに境界を assistant の tool-call message 側へずらします。
• 末尾の tool-result ブロックのせいでチャンクがターゲットを超えてしまう場合、OpenClaw はその保留中 tool ブロックを保持し、未要約の tail をそのまま残します。
• 中断/エラーになった tool-call ブロックは、保留中の分割を維持しません。

​

自動 compaction が発生するタイミング（Pi runtime）

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、およびそれに類する provider 固有のバリエーション）→ compact → retry。
2. しきい値メンテナンス: 成功したターンの後で、次を満たす場合:

• contextWindow はモデルのコンテキストウィンドウ
• reserveTokens はプロンプト + 次のモデル出力のために確保される余裕領域

​

Compaction 設定（reserveTokens, keepRecentTokens）

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

• compaction.reserveTokens < reserveTokensFloor の場合、OpenClaw はそれを引き上げます。
• デフォルトの下限は 20000 トークンです。
• 下限を無効にするには agents.defaults.compaction.reserveTokensFloor: 0 を設定します。
• すでにそれより高い場合、OpenClaw は変更しません。

​

プラガブルな compaction provider

• provider: 登録済み compaction provider plugin の id。デフォルトの LLM 要約を使う場合は未設定のままにします。
• provider を設定すると mode: "safeguard" が強制されます。
• provider には、組み込み経路と同じ compaction 指示と ID 保持ポリシーが渡されます。
• safeguard は provider 出力後も recent-turn と split-turn の suffix コンテキストを保持します。
• provider が失敗したり空結果を返した場合、OpenClaw は自動的に組み込み LLM 要約へフォールバックします。
• Abort/timeout シグナルは呼び出し元のキャンセルを尊重するため再スローされます（握りつぶされません）。

​

ユーザーに見える surface

• /status（任意のチャットセッション内）
• openclaw status（CLI）
• openclaw sessions / sessions --json
• 詳細モード: 🧹 Auto-compaction complete + compaction count

​

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

• assistant は、ユーザーに返信を配信しないことを示すために、出力を正確な silent token NO_REPLY / no_reply で開始します。
• OpenClaw は配信レイヤーでこれを取り除く/抑制します。
• 正確な silent-token 抑制は大文字小文字を区別しないため、ペイロード全体が silent token だけである場合、NO_REPLY と no_reply の両方が有効です。
• これは本当にバックグラウンド/未配信のターン専用であり、通常の実行可能なユーザー要求の近道ではありません。

​

Pre-compaction の「memory flush」（実装済み）

1. セッションのコンテキスト使用量を監視する。
2. それが「ソフトしきい値」（Pi の compaction しきい値より低い）を超えたら、agent にサイレントな 「今すぐ memory を書き込む」指示を実行する。
3. ユーザーに何も見せないため、正確な silent token NO_REPLY / no_reply を使用する。

• enabled（デフォルト: true）
• softThresholdTokens（デフォルト: 4000）
• prompt（flush turn 用 user message）
• systemPrompt（flush turn に追加される追加 system prompt）

• デフォルトの prompt/system prompt には、配信を抑制するための NO_REPLY ヒントが含まれます。
• flush は compaction サイクルごとに 1 回だけ実行されます（sessions.json で追跡）。
• flush は組み込み Pi セッションでのみ実行されます（CLI バックエンドではスキップ）。
• セッション workspace が読み取り専用（workspaceAccess: "ro" または "none"）の場合、flush はスキップされます。
• workspace ファイルレイアウトと書き込みパターンについては Memory を参照してください。

​

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

• Session key がおかしいですか？ まず /concepts/session を確認し、/status の sessionKey を確認してください。
• Store と transcript が一致しませんか？ Gateway ホストと openclaw status から取得した store path を確認してください。
• Compaction が多すぎますか？ 次を確認してください:
  • モデルコンテキストウィンドウ（小さすぎないか）
  • compaction 設定（モデルウィンドウに対して reserveTokens が高すぎると、より早い compaction の原因になります）
  • tool-result の肥大化: session pruning を有効化/調整する
• Silent turn が漏れていますか？ 返信が NO_REPLY（大文字小文字を区別しない正確なトークン）で始まっていること、および streaming suppression 修正を含むビルドであることを確認してください。