セッション管理

OpenClaw は、すべての受信メッセージを、その送信元（DM、グループチャット、cron ジョブなど）に基づいてセッションへルーティングします。すべてのセッション状態は Gateway が所有し、UI クライアントは Gateway にセッションデータを照会します。

パーソナルエージェントのデフォルト（すべての DM チャンネルで共有される継続的な 1 つの会話に、グループでのアクティビティやバックグラウンド作業が流れ込む構成）については、メインセッションを参照してください。

メッセージのルーティング方法

DM の分離

デフォルトでは、会話の連続性を維持するため、すべての DM が 1 つのセッションを共有します。これは単一ユーザー構成では問題ありません。

{  session: {    dmScope: "per-channel-peer", // チャンネル + 送信者ごとに分離  },}

session.dmScope のオプション:

リンク済みチャンネルのドッキング

ドッキングコマンドは、新しいセッションを開始せずに、現在のダイレクトチャットセッションの返信ルートを別のリンク済みチャンネルへ移動します。例、設定、トラブルシューティングについては、チャンネルのドッキングを参照してください。

openclaw security audit で設定を確認します。

シークレットモードのセッション

シークレットモードのセッションは、Control UI の New thread 画面からのみ利用できます。スレッドを開始する前に Incognito をオンにすると、セッションエントリ、トランスクリプト、Compaction 状態がディスクではなくプロセスメモリに保持されます。スレッドは Gateway の再起動時に消失し、OpenClaw の自動メモリフラッシュは実行されず、リセットまたは削除してもトランスクリプトのアーカイブは作成されません。Codex ベースの実行でもハーネススレッドが一時モードで開始されるため、Codex はロールアウトファイルやローカルのセッション状態ファイルを書き込みません。他のモデルプロバイダーは HTTP API を使用し、OpenClaw 内にローカルのプロバイダートランスクリプトを保持しません。

incognito- セグメントは、ダッシュボード、サブエージェント、非表示の内部セッションキー用に予約されています。openclaw doctor --fix は、競合する従来の永続キーを名前変更します。

シークレットモードは、エージェントの通常のツールを制限しません。情報の保存を明示的に要求した場合や、ツールによってファイルが書き込まれた場合は、シークレットモードのセッションストア外にデータが永続化される可能性があります。設定済みのモデルプロバイダーは送信したメッセージを引き続き処理し、診断ログの動作も変わりません。また、OpenClaw は HMAC 参照など、コンテンツを含まない監査メタデータを引き続き記録します。

マルチユーザー Gateway では、シークレットモードのスレッドは管理者スコープの接続にのみ表示され、別のセッションのエージェントセッションツールやトランスクリプト検索には決して表示されません。これは、ストレージや Gateway を介する他のユーザーからスレッドを保護するものであり、ライブセッションを常に監視できる Gateway の所有者やプロセスオペレーターから保護するものではありません。

会話をまたいで記憶する

個別のトランスクリプトが、それぞれの会話のローカル履歴を制御します。パーソナルエージェントまたは完全に信頼できるエージェントの場合、memory.search.rememberAcrossConversations: true は、そのエージェントの他のプライベートな会話を横断する任意の取得ステップを追加しますが、トランスクリプトを結合することはありません。

プライベートなダイレクト会話と、明示的に永続化された UI 会話は、相互に関連するコンテキストを提供できます。グループとチャンネルは、どちらの方向でも分離されたままです。それらのトランスクリプトはプライベートな想起元にはならず、それらの会話内の返信にもプライベートなトランスクリプトのコンテキストは提供されません。現在の会話は、その履歴がすでに読み込まれているため除外されます。

この設定は、セッションキー、DM スコープ、ルーティング、配信、tools.sessions.visibility を変更しません。MEMORY.md と memory/*.md の共有ワークスペースメモリも、既存の動作を維持します。現在のメモリプロバイダーは、保護されたプライベートトランスクリプトの想起をサポートしている必要があります。Lossless Claw などのコンテキストエンジンは独立したままで、これと併用できます。設定と実行時の詳細については、Active Memoryを参照してください。

セッションのライフサイクル

セッションは、手動でリセットするか、自動リセットポリシーを有効にするまで再利用されます。

• 自動リセットなし（デフォルト mode: "none"）- セッションは同じ sessionId を維持し、会話が長くなるにつれて Compaction がアクティブコンテキストを管理します。
• 毎日リセット（mode: "daily"）- Gateway ホスト上で設定したローカル時刻（session.reset.atHour、デフォルト 4、0-23）に新しいセッションへ切り替えるよう設定します。毎日の鮮度は、後続のメタデータ書き込みではなく、現在の sessionId が開始された時点に基づきます。
• アイドル時リセット（mode: "idle"）- session.reset.idleMinutes の非アクティブ期間後に新しいセッションへ切り替えるよう設定します。アイドル状態の鮮度は、最後の実際のユーザー/チャンネル操作に基づくため、Heartbeat、Cron、exec のシステムイベントによってセッションが維持されることはありません。
• 手動リセット - チャットで /new または /reset と入力します。/new <model> はモデルも切り替えます。

毎日リセットとアイドル時リセットの両方を設定した場合は、先に期限切れになる方が適用されます。Heartbeat、Cron、exec、その他のシステムイベントのターンによってセッションメタデータが書き込まれることはありますが、それらの書き込みによって毎日リセットまたはアイドル時リセットの鮮度が延長されることはありません。リセットによってセッションが切り替わると、古いセッションのキューに入っていたシステムイベント通知は破棄されるため、古いバックグラウンド更新が新しいセッションの最初のプロンプトの先頭に追加されることはありません。

プロバイダー所有のアクティブな CLI セッションがあるセッションにも、同じ「自動リセットなし」のデフォルトが適用されます。これらのセッションをタイマーで期限切れにする場合は、/reset を使用するか、session.reset を明示的に設定します。

自動リセットをグローバルに有効にしてから、チャットタイプまたはチャンネルごとに上書きします。

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType は direct、group、thread をサポートします。Doctor は従来の dm エントリを direct に、session.idleMinutes を session.reset.idleMinutes に移行します。スキーマは廃止された両方の形式を拒否します。

状態の保存場所

• 実行時セッション行: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• アーカイブ済みトランスクリプトファイル: ~/.openclaw/agents/<agentId>/sessions/
• 従来行の移行元: ~/.openclaw/agents/<agentId>/sessions/sessions.json

エージェントごとの SQLite データベース内のセッション行には、個別のライフサイクルタイムスタンプが保持されます。

• sessionStartedAt: 現在の sessionId が開始された時点。毎日リセットで使用されます。
• lastInteractionAt: アイドル有効期間を延長する最後のユーザー/チャンネル操作。
• updatedAt: ストア行の最終変更時点。一覧表示やプルーニングには有用ですが、毎日リセット/アイドル時リセットの鮮度を決定する正式な値ではありません。

古いインストールからの移行中、Gateway の起動時および openclaw doctor --fix は、従来の sessions.json 行と使用中のトランスクリプト JSONL 履歴を SQLite に自動的にインポートします。sessionStartedAt がない行は、利用可能な場合、従来のトランスクリプト JSONL セッションヘッダーから解決されます。古い行に lastInteractionAt もない場合、アイドル状態の鮮度には、後続の管理用書き込みではなく、そのセッションの開始時刻が使用されます。明示的な検査または検証証拠が必要な場合は、openclaw doctor --session-sqlite inspect --session-sqlite-all-agents と Doctor の移行手順を使用してください。

セッションのメンテナンス

OpenClaw は session.maintenance によってセッションストレージを長期的に制限します。以下はデフォルト値です。

{  session: {    maintenance: {      mode: "enforce", // "enforce" はクリーンアップを適用し、"warn" は報告のみ      pruneAfter: "30d",      maxEntries: 500,    },  },}

本番規模の maxEntries 制限では、Gateway の実行時書き込みは小さな高水位バッファを使用し、バッチ単位で設定済み上限まで削減します。セッションストアの読み取りでは、Gateway 起動時にエントリのプルーニングや上限制限を行わないため、起動処理や分離された Cron セッションでストア全体のクリーンアップコストは発生しません。openclaw sessions cleanup --enforce は上限を直ちに適用します。

Gateway のモデル実行プローブセッションは、デフォルトでは短命です。agent:*:explicit:model-run-<uuid> に一致する行には固定の 24h 保持期間が適用されますが、クリーンアップは負荷条件付きです。セッションエントリのメンテナンス/上限負荷に達した場合にのみ古いプローブ行を削除し、より広範な古いエントリの経過時間しきい値およびエントリ上限より先に実行されます。通常のダイレクト、グループ、スレッド、Cron、フック、Heartbeat、ACP、サブエージェントのセッションには、この 24h の保持期間は継承されません。

メンテナンスでは、グループセッションやスレッドスコープのチャットセッションなどの永続的な外部会話ポインターを保持しながら、合成された Cron、フック、Heartbeat、ACP、サブエージェントのエントリは経過時間に応じて削除できます。

アーカイブ済みセッションはユーザーによって保管されたものであり、経過時間によるプルーニング、エントリ上限、モデル実行のクリーンアップ、ディスク容量に基づく削除を含む、すべての自動メンテナンス処理の対象外です。アーカイブを解除するか明示的に削除するまで、アーカイブ状態が維持されます。

以前に DM の分離を使用し、その後 session.dmScope を main に戻した場合は、openclaw sessions cleanup --dry-run --fix-dm-scope で古いピアキー単位の DM 行をプレビューします。同じフラグを適用すると、それらの古いダイレクト DM 行が廃止され、そのトランスクリプトは削除済みアーカイブとして保持されます。

openclaw sessions cleanup --dry-run で任意のメンテナンス実行をプレビューします。

セッションの確認

関連資料

• セッション検索 - 過去のトランスクリプトを横断する全文想起
• セッションのプルーニング - ツール結果の切り詰め
• Compaction - 長い会話の要約
• セッションツール - セッションをまたぐ作業用のエージェントツール
• セッション管理の詳細 - ストアスキーマ、トランスクリプト、送信ポリシー、送信元メタデータ、高度な設定
• マルチエージェント - エージェント間のルーティングとセッション分離
• バックグラウンドタスク - 分離された作業によって、セッション参照を持つタスクレコードが作成される仕組み
• チャンネルルーティング - 受信メッセージがセッションへルーティングされる仕組み

関連項目

• セッションのプルーニング
• セッションツール
• コマンドキュー