セッション管理の詳細

• セッション ルーティング (受信メッセージを sessionKey にマッピングする方法)
• セッション ストア (sessions.json) とその追跡内容
• トランスクリプトの永続性 (*.jsonl) とその構造
• トランスクリプトの衛生管理 (実行前のプロバイダー固有の修正)
• コンテキストの制限 (コンテキスト ウィンドウと追跡されたトークン)
• 圧縮 (手動 + 自動圧縮) および圧縮前の作業をフックする場所
• サイレント ハウスキーピング (例: ユーザーに表示される出力を生成すべきではないメモリ書き込み)

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

​

真実の情報源: ゲートウェイ

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

​

2 つの永続化レイヤー

• キー/値マップ: sessionKey -> SessionEntry
• 小さく、変更可能で、安全に編集 (またはエントリを削除)
• セッションのメタデータ (現在のセッション ID、最後のアクティビティ、トグル、トークン カウンターなど) を追跡します。

2. トランスクリプト (<sessionId>.jsonl)
   • ツリー構造の追加専用トランスクリプト (エントリには id + parentId があります)
   • 実際の会話 + ツール呼び出し + 圧縮サマリーを保存します
   • 将来のターンに向けてモデル コンテキストを再構築するために使用されます

​

ディスク上の場所

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

​

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

• pruneAfter: 古いエントリの年齢カットオフ (デフォルト 30d)
• maxEntries: sessions.json のエントリを制限します (デフォルト 500)
• rotateBytes: サイズが大きい場合に sessions.json を回転します (デフォルト 10mb)
• resetArchiveRetention: *.reset.<timestamp> トランスクリプト アーカイブの保持 (デフォルト: pruneAfter と同じ。false はクリーンアップを無効にします)
• maxDiskBytes: オプションのセッション ディレクトリの予算
• highWaterBytes: クリーンアップ後のオプションのターゲット (デフォルトの 80% または maxDiskBytes)

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

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

​

Cron セッションと実行ログ

• 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:<job.id>
• Webhook: hook:<uuid> (オーバーライドされない限り)

​

セッション ID (sessionId)

• 毎日リセット (デフォルトはゲートウェイ ホストの現地時間午前 4 時) は、リセット境界後の次のメッセージで新しい sessionId を作成します。
• アイドル有効期限 (session.reset.idleMinutes またはレガシー session.idleMinutes) は、アイドル ウィンドウの後にメッセージが到着すると、新しい sessionId を作成します。 Daily + Idle の両方が設定されている場合は、先に期限切れになった方が優先されます。
• スレッド親フォーク ガード (session.parentForkMaxTokens、デフォルト 100000) は、親セッションがすでに大きすぎる場合、親トランスクリプトのフォークをスキップします。新しいスレッドは新しく始まります。 0 を無効に設定します。

​

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

• 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: このセッション キーの自動圧縮が完了する頻度
• memoryFlushAt: 最後の圧縮前のメモリフラッシュのタイムスタンプ
• memoryFlushCompactionCount: 最後のフラッシュが実行されたときの圧縮数

​

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

• 次に: id + parentId のセッション エントリ (ツリー)

• message: ユーザー/アシスタント/ツール結果メッセージ
• custom_message: モデル コンテキストに do 入る拡張機能によって挿入されたメッセージ (UI から非表示にすることができます)
• custom: モデル コンテキストに「入らない」拡張状態
• compaction: firstKeptEntryId および tokensBefore による永続化圧縮の概要
• branch_summary: ツリー ブランチを移動するときに持続される概要

​

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

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

• コンテキスト ウィンドウはモデル カタログから取得されます (構成によってオーバーライドできます)。
• ストア内の contextTokens は実行時の推定値/レポート値です。厳密な保証として扱わないでください。

​

圧縮: 圧縮とは何か圧縮により、古い会話がトランスクリプト内の永続化された compaction エントリに要約され、最近のメッセージはそのまま保持されます

• 圧縮の概要
• firstKeptEntryId 以降のメッセージ

​

自動圧縮が行われる場合 (Pi ランタイム)

1. オーバーフロー回復: モデルはコンテキスト オーバーフロー エラーを返し、→ 圧縮→ 再試行します。
2. 閾値メンテナンス: ターンが成功した後、次の場合:

• contextWindow はモデルのコンテキスト ウィンドウです
• reserveTokens は、プロンプト + 次のモデル出力用に予約されたヘッドルームです。

​

圧縮設定 (reserveTokens、keepRecentTokens)

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

• compaction.reserveTokens < reserveTokensFloor の場合、OpenClaw はそれをバンプします。
• デフォルトのフロアは 20000 トークンです。
• agents.defaults.compaction.reserveTokensFloor: 0 を設定してフロアを無効にします。
• すでにそれより高い場合、OpenClaw はそれをそのままにします。

​

ユーザーに見える表面

• /status (チャット セッション中)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• 詳細モード: 🧹 Auto-compaction complete + 圧縮カウント

​

サイレントハウスキーピング (NO_REPLY)

• アシスタントは出力を NO_REPLY で開始し、「ユーザーに応答しない」ことを示します。
• OpenClaw は、配信層でこれを削除/抑制します。

​

圧縮前の「メモリフラッシュ」(実装)

1. セッションコンテキストの使用状況を監視します。
2. 「ソフトしきい値」(Pi の圧縮しきい値を下回る) を超えると、サイレント メソッドを実行します。 「今すぐメモリに書き込む」という指示をエージェントに送信します。
3. ユーザーには何も表示されないように、NO_REPLY を使用します。

• softThresholdTokens (デフォルト: 4000)
• prompt (フラッシュターンのユーザーメッセージ)
• systemPrompt (フラッシュ ターン用に追加された追加のシステム プロンプト)

• デフォルトのプロンプト/システム プロンプトには、配信を抑制するための NO_REPLY ヒントが含まれています。
• フラッシュは圧縮サイクルごとに 1 回実行されます (sessions.json で追跡されます)。
• フラッシュは埋め込み Pi セッションに対してのみ実行されます (CLI バックエンドはフラッシュをスキップします)。
• セッション ワークスペースが読み取り専用 (workspaceAccess: "ro" または "none") の場合、フラッシュはスキップされます。
• ワークスペースファイルのレイアウトと書き込みパターンについては、メモリを参照してください。

​

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

• セッションキーが間違っていますか? /concepts/session から始めて、/status の sessionKey を確認します。
• ストアとトランスクリプトの不一致? openclaw status からゲートウェイ ホストとストア パスを確認します。
• 圧縮スパム?確認してください:
  • モデル コンテキスト ウィンドウ (小さすぎる)
  • 圧縮設定 (reserveTokens がモデル ウィンドウに対して高すぎると、圧縮が早まる可能性があります)
  • ツール結果の肥大化: セッション プルーニングの有効化/調整
• サイレントターンが漏れていませんか？応答が NO_REPLY (正確なトークン) で始まり、ストリーミング抑制修正を含むビルドを使用していることを確認します。