セッション管理
チャットセッションの管理規則、キー形式、永続化方式。
OpenClaw は''各エージェントの 1 つの DM（ダイレクトメッセージ）セッション''をメインセッションとして扱います。DM はデフォルトで ''agent:<agentId>:<mainKey>''（デフォルト ''main''）に折りたたまれ、グループ/チャネルはそれぞれ独自のセッションキーを持ちます。''session.mainKey''が尊重されます。
''session.dmScope'' を使用して''ダイレクトメッセージ''をグループ化する方法を制御します：
- ''main''（デフォルト）：すべての DM がメインセッションを共有し、デバイス間/チャネル間の連続性を維持します。
- ''per-peer''：送信者 ID で分離（チャネル間で共有）。
- ''per-channel-peer''：チャネル + 送信者で分離（複数人受信トレイ推奨）。
- ''per-account-channel-peer''：アカウント + チャネル + 送信者で分離（複数アカウント受信トレイ推奨）。
Use ''session.identityLinks'' to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using ''per-peer'', ''per-channel-peer'', or ''per-account-channel-peer''.
Gateway は唯一の真実のソース
すべてのセッション状態は gateway（OpenClaw の「マスター」）によって保持されます。UI クライアント（macOS アプリ、WebChat など）は、ローカルファイルを読み取るのではなく、gateway にセッションリストとトークンカウントをクエリする必要があります。
- remote mode では、気になるセッションストアはリモート gateway ホスト上にあり、Mac 上にはありません。
- UI に表示されるトークンカウントは、gateway ストアフィールド（''inputTokens''、''outputTokens''、''totalTokens''、''contextTokens''）から取得されます。クライアントは JSONL トランスクリプトを解析して合計を「修正」しません。
状態の保存場所
- gateway ホスト上：
- ストアファイル（エージェントごとに 1 つ）：''~/.openclaw/agents/<agentId>/sessions/sessions.json''
- openclaw gateway call sessions.list --params {}' — fetch sessions from the running gateway (use --url/--token for remote gateway access).
- ストアは ''/status'' のマップです。エントリの削除は安全です。必要に応じて再構築されます。
- Send ''/context list'' or ''/context detail'' to see what's in the system prompt and injected workspace files (and the biggest context contributors).
- セッションエントリには、UI がセッションの由来を理解するのに役立つ ''/stop'' メタデータ（ラベル + ルーティングヒント）が含まれます。
- Send ''/compact'' (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).
セッションプルーニング
Each session entry records where it came from (best-effort) in ''origin'':
- ''label'': human label (resolved from conversation label + group subject/channel)
圧縮前のメモリフラッシュ
セッションが自動圧縮に近づくと、OpenClaw は''サイレントメモリフラッシュ''ターンを実行して、モデルに「永続化可能な要点」をディスクに書き込むよう促すことができます。ワークスペースが書き込み可能な場合にのみ有効です。''Memory''、''Compaction'' を参照してください。
トランスポート → セッションキーのマッピング
- DM は ''session.dmScope'' に従います（デフォルト ''main''）。
- ''main''：''agent:<agentId>:<mainKey>''（デバイス間/チャネル間の連続性）。
- 複数の電話番号とチャネルが同じエージェントのメインキーにマップできます。それらは同じ会話への異なるトランスポートパスです。
- ''per-peer''：''agent:<agentId>:dm:<peerId>''。
- ''per-channel-peer''：''agent:<agentId>:<channel>:dm:<peerId>''。
- ''per-account-channel-peer''：''agent:<agentId>:<channel>:<accountId>:dm:<peerId>''（''accountId'' はデフォルトで ''default''）。
''session.identityLinks'' が設定されている場合（例：''telegram:123''）、''<peerId>'' は正規 ID に置き換えられ、同じ人が異なるチャネルで同じ DM セッションを共有できるようになります。
- グループ/チャネルの会話は分離されます：''agent:<agentId>:<channel>:group:<id>''（ルーム/チャネルは ''agent:<agentId>:<channel>:channel:<id>'' を使用します）。
- Telegram フォーラムトピックは、トピックごとの分離のためにグループ ID に '':topic:<threadId>'' を追加します。
- レガシー ''group:<id>'' キーは移行用に認識されます。
- インバウンドコンテキストはまだ ''group:<id>'' を使用する場合があります。チャネルは ''Provider'' から推測され、''agent:<agentId>:<channel>:group:<id>'' に正規化されます。
- その他のソース：
- Cron ジョブ：''cron:<job.id>''
ライフサイクル
- リセットポリシー：セッションは古くなるまで再利用されます。古さは次のインバウンドメッセージで評価されます。
- 日次リセット：デフォルトはgateway ホストの現地時間の午前 4:00です。セッションの最終更新が最新の日次リセット時間より古い場合、古いと見なされます。
- アイドルリセット（オプション）：''idleMinutes'' はスライディングウィンドウを導入します。日次とアイドルの両方が設定されている場合、''どちらか早く期限切れになる方が優先されます''（期限切れが早いと新しいセッションが強制されます）。
- レガシーアイドルオンリー：''resetByType''/''session.reset'' なしで ''resetByType'' のみが設定されている場合、後方互換性のためにアイドルオンリーモードが維持されます。
- タイプ別オーバーライド（オプション）：''resetByType'' は ''dm''、''group''、''thread'' のリセットポリシーをオーバーライドできます（thread = Slack/Discord スレッド、Telegram トピック、コネクタが提供する場合は Matrix スレッド）。
- チャネル別オーバーライド（オプション）：''resetByChannel'' は特定のチャネルのリセットポリシーをオーバーライドします（そのチャネルのすべてのセッションタイプに適用され、''reset''/''resetByType'' より優先度が高い）。
- リセットトリガー：''/new'' または ''/reset'' の完全一致（および ''resetTriggers'' の追加項目）は新しいセッション ID を開始し、コマンドの末尾のテキストを残りのメッセージとして渡します。''/new <model>'' はモデルエイリアス、''provider/model''、またはプロバイダー名（あいまい一致）をサポートし、新しいセッションのモデルを設定します。''/new'' または ''/reset'' が単独で送信された場合、OpenClaw はリセットを確認するために短い "hello" ターンを実行します。
- 手動リセット：ストアから特定のキーを削除するか、JSONL トランスクリプトを削除します。次のメッセージが再構築します。
- Cron ジョブ（分離）は実行ごとに新しい ''sessionId'' を生成します（アイドル再利用されません）。
送信ポリシー（オプション）
すべての ID を列挙せずに、セッションタイプ/ソースごとに配信をブロックします：
{
session: {
sendPolicy: {
rules: [
{ action: "deny", match: { channel: "discord", chatType: "group" } },
{ action: "deny", match: { keyPrefix: "cron:" } }
],
default: "allow"
}
}
}ランタイムオーバーライド（所有者のみ）：
- ''/send on'' → このセッションの配信を許可
- ''/send off'' → このセッションの配信をブロック
- ''/send inherit'' → オーバーライドをクリアし、設定ルールにフォールバック
これらのコマンドは認識されるように別のメッセージとして送信してください。
設定例（名前変更付き）
// ~/.openclaw/openclaw.json
{
session: {
scope: "per-sender",
dmScope: "main",
identityLinks: {
alice: ["telegram:123456789", "discord:987654321012345678"]
},
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 120
},
resetByType: {
thread: { mode: "daily", atHour: 4 },
dm: { mode: "idle", idleMinutes: 240 },
group: { mode: "idle", idleMinutes: 120 }
},
resetByChannel: {
discord: { mode: "idle", idleMinutes: 10080 }
},
resetTriggers: ["/new", "/reset"],
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
mainKey: "main"
}
}検査とトラブルシューティング
- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.
- openclaw gateway call sessions.list --params {}' — 実行中の gateway からセッションを取得します（リモートには --url/--token を使用）。
- チャットで ''/status'' を単独で送信して、エージェントが到達可能かどうか、コンテキスト使用量、思考/詳細状態、および WhatsApp web 資格情報の最近の更新時間を確認できます（再リンクが必要かどうかを判断するのに役立ちます）。
- ''/context list'' または ''/context detail'' を送信して、システムプロンプトと注入されたワークスペースファイル（および最大のコンテキスト貢献者）を表示します。
- ''/stop'' を単独で送信して現在の実行を中止し、そのセッションのキューに入れられたフォローアップをクリアし、それから派生したサブエージェント実行を停止します（応答には停止数が含まれます）。
- ''/compact'' を単独で送信して（オプションの指示付き）、古いコンテキストを要約して圧縮し、ウィンドウスペースを解放します。''/concepts/compaction'' を参照してください。
- JSONL トランスクリプトは直接開いて完全なターンを表示できます。
ヒント
Each session entry records where it came from (best-effort) in ''origin'':
- ''label'': human label (resolved from conversation label + group subject/channel)
セッションオリジンメタデータ
各セッションエントリは ''origin'' にそのソースを記録します（ベストエフォート）：
- ''label''：人間が読めるラベル（会話ラベル + グループ件名/チャネルから派生）
- ''provider''：正規化されたチャネル ID（拡張機能付き）
- ''from''/''to''：インバウンドエンベロープの元のルーティング ID
- ''accountId''：プロバイダーアカウント ID（マルチアカウント時）
- ''threadId''：チャネルがスレッド/トピックをサポートする場合のスレッド/トピック ID