メインコンテンツへスキップ

​
セッション管理

OpenClaw は、エージェントごとに 1 つのダイレクトチャットセッションを基本として扱います。ダイレクトチャットは agent:<agentId>:<mainKey>（デフォルトは main）に集約され、グループ／チャンネルチャットはそれぞれ独自のキーを持ちます。session.mainKey は尊重されます。 OpenClaw は、エージェントごとに 1 つのダイレクトチャットセッションを基本として扱います。ダイレクトチャットは agent:<agentId>:<mainKey>（デフォルトは main）に集約され、グループ／チャンネルチャットはそれぞれ独自のキーを持ちます。session.mainKey は尊重されます。 直接チャットは agent:<agentId>:<mainKey> (デフォルトの main)に折り畳まれますが、グループ/チャンネルチャットは独自のキーを取得します。 session.mainKey が認証されました。 session.mainKey が認証されました。 ダイレクトメッセージのグルーピング方法は session.dmScope で制御します。
  • main（デフォルト）: すべての DM が継続性のためにメインセッションを共有します。
  • per-peer: チャンネルをまたいで送信者 ID ごとに分離します。
  • per-channel-peer: チャンネル + 送信者で分離します（マルチユーザー受信箱に推奨）。
  • per-account-channel-peer: アカウント + チャンネル + 送信者によって隔離されます (マルチアカウント受信ボックスに推奨されます)。 per-account-channel-peer: アカウント + チャンネル + 送信者で分離します（マルチアカウント受信箱に推奨）。 session.identityLinks を使用すると、プロバイダー接頭辞付きのピア ID を正規化された ID にマップでき、per-peer、per-channel-peer、または per-account-channel-peer 使用時に、同一人物がチャンネルをまたいでも同じ DM セッションを共有できます。

​
セキュア DM モード（マルチユーザー構成に推奨）

セキュリティ警告: エージェントが複数人から DM を受信できる場合は、セキュア DM モードを有効にすることを強く推奨します。無効の場合、すべてのユーザーが同じ会話コンテキストを共有し、ユーザー間で個人情報が漏洩する可能性があります。 それがなければ、すべてのユーザーは同じ会話コンテキストを共有し、ユーザー間の個人情報を漏洩させることができます。 それがなければ、すべてのユーザーは同じ会話コンテキストを共有し、ユーザー間の個人情報を漏洩させることができます。
デフォルト設定で発生する問題の例:
  • Alice（<SENDER_A>）が、個人的な話題（例: 医療予約）についてエージェントにメッセージを送信します。
  • Bob（<SENDER_B>）が、「さっき何を話していましたか？」とエージェントにメッセージを送信します。
  • 両方の DM が同じセッションを共有しているため、モデルが Alice の以前の文脈を使って Bob に回答してしまう可能性があります。
対処方法: ユーザーごとにセッションを分離するよう dmScope を設定します。 
// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}
有効にすべき場合:
  • 複数の送信者に対するペアリング承認がある
  • 複数エントリを含む DM 許可リストを使用している
  • dmPolicy: "open" を設定している
  • 複数の電話番号やアカウントからエージェントにメッセージできる
注記:
  • デフォルトは継続性重視の dmScope: "main"（すべての DM がメインセッションを共有）です。単一ユーザー構成では問題ありません。 これは、単一ユーザの設定では問題ありません。 これは、単一ユーザの設定では問題ありません。
  • 同一チャンネル上のマルチアカウント受信箱では、per-account-channel-peer を推奨します。
  • 同一人物が複数チャンネルから連絡してくる場合は、session.identityLinks を使用して DM セッションを 1 つの正規 ID に集約します。
  • DM 設定は openclaw security audit で確認できます（security を参照）。

​
Gateway（ゲートウェイ）が信頼できる唯一の情報源

すべてのセッション状態は ゲートウェイによって所有されています (「master」 OpenClaw)。 UI クライアント (macOS アプリ、WebChat など) ローカル ファイルを読み込む代わりに、セッション リストとトークン数のゲートウェイをクエリする必要があります。
  • リモートモードでは、重要なセッションストアは Mac ではなく、リモートの Gateway ホスト上に存在します。
  • UI に表示されるトークン数は、ゲートウェイのストアフィールド（inputTokens、outputTokens、totalTokens、contextTokens）に基づきます。クライアントが JSONL トランスクリプトを解析して合計を「補正」することはありません。 UI に表示されるトークン数は、ゲートウェイのストアフィールド（inputTokens、outputTokens、totalTokens、contextTokens）に基づきます。クライアントが JSONL トランスクリプトを解析して合計を「補正」することはありません。 クライアントはJSONL トランスクリプトを解析して合計を「修正」しません。

​
状態の保存先

  • Gateway ホスト上:
    • ストアファイル: ~/.openclaw/agents/<agentId>/sessions/sessions.json（エージェントごと）。
  • トランスクリプト: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl（Telegram のトピックセッションでは .../<SessionId>-topic-<threadId>.jsonl を使用）。
  • ストアは sessionKey -> { sessionId, updatedAt, ... }. エントリを削除することは安全です; それらはオンデマンドで再作成されます。
  • グループエントリには、UI でセッションを識別するために displayName、channel、subject、room、および space が含まれる場合があります。
  • セッションエントリには、セッションの由来を UI が説明できるよう、origin メタデータ（ラベル + ルーティングヒント）が含まれます。
  • OpenClaw は、従来の Pi/Tau セッションフォルダーを読み込みません。

​
セッションのプルーニング

OpenClaw はデフォルトで、LLM 呼び出し直前に、メモリ上のコンテキストから古いツール結果を削除します。 これは JSONL 履歴を書き換えるものではありません。詳細は /concepts/session-pruning を参照してください。 JSONL 履歴は 書き換えられません 。 /concepts/session-pruning を参照してください。

​
事前コンパクション時のメモリフラッシュ

セッションが自動コンパクションに近づくと、OpenClaw はサイレントなメモリフラッシュターンを実行し、モデルに対して永続的なメモをディスクに書き出すよう促すことがあります。これはワークスペースが書き込み可能な場合にのみ実行されます。詳細は Memory および Compaction を参照してください。 ワークスペースが書き込み可能である場合にのみ実行されます。 Memory と Compaction を参照してください。 ワークスペースが書き込み可能である場合にのみ実行されます。 Memory と Compaction を参照してください。

​
トランスポート → セッションキーの対応付け

  • ダイレクトチャットは session.dmScope に従います（デフォルトは main）。
    • main: agent:<agentId>:<mainKey>（デバイス／チャンネルをまたいだ継続性）。
      • 複数の電話番号やチャンネルが同じエージェントのメインキーにマップされ、1 つの会話へのトランスポートとして機能します。
    • 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 がプロバイダー接頭辞付きのピア ID（例: telegram:123）に一致する場合、正規キーが <peerId> を置き換え、同一人物がチャンネルをまたいでもセッションを共有します。
  • グループチャットは状態を分離します: 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>
    • Webhook: hook:<uuid>（フックで明示的に設定されていない場合）
    • ノード実行: node-<nodeId>

​
ライフサイクル

  • リセットポリシー: セッションは期限切れになるまで再利用され、期限判定は次のインバウンドメッセージ時に行われます。
  • 毎日のリセット: ゲートウェイホストでは、デフォルトは 4:00 AM ローカル時間 に設定します。 デイリーリセット: デフォルトは Gateway ホストのローカル時刻で午前 4:00 です。最終更新が直近のデイリーリセット時刻より前の場合、セッションは古いとみなされます。 デイリーリセット: デフォルトは Gateway ホストのローカル時刻で午前 4:00 です。最終更新が直近のデイリーリセット時刻より前の場合、セッションは古いとみなされます。
  • アイドルリセット(オプション):idleMinutesはスライドアイドルウィンドウを追加します。 デイリーリセットとアイドルリセットの両方が設定されている場合、どちらかの有効期限が切れるは新しいセッションを強制します。
  • 従来のアイドルのみモード: session.idleMinutes を設定し、session.reset/resetByType の設定がない場合、後方互換性のため OpenClaw はアイドルのみモードのまま動作します。
  • タイプ別の上書き（任意）: resetByType を使うと、direct、group、thread セッション（thread = Slack/Discord のスレッド、Telegram トピック、コネクタが提供する場合の Matrix スレッド）ごとにポリシーを上書きできます。
  • チャンネル別オーバーライド（任意）: resetByChannel はチャンネル単位でリセットポリシーを上書きします（そのチャンネルのすべてのセッションタイプに適用され、reset/resetByType より優先されます）。
  • リセットトリガー: 正確な /new または /reset（および resetTriggers 内の追加要素）に一致すると、新しいセッション ID が開始され、残りのメッセージが処理されます。/new <model> はモデルエイリアス、provider/model、またはプロバイダー名（あいまい一致）を受け取り、新しいセッションモデルを設定します。/new または /reset のみが送信された場合、OpenClaw は短い「hello」挨拶ターンを実行してリセットを確認します。 /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", // DM の継続性（共有受信箱では per-channel-peer / per-account-channel-peer を設定）
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // 既定: mode=daily, atHour=4（ゲートウェイホストのローカル時間）。
      // idleMinutes も設定した場合、先に期限が来た方が有効。
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { 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",
  },
}

​
検査

  • openclaw status — ストアパスと最近のセッションを表示します。
  • openclaw sessions --json — すべてのエントリをダンプします（--active <minutes> でフィルタ）。
  • openclaw gateway call sessions.list --params '{}' — 実行中のゲートウェイからセッションを取得します（リモート Gateway（ゲートウェイ）アクセスには --url/--token を使用）。
  • チャットで /status を単独メッセージとして送信すると、エージェントが到達可能かどうか、セッションコンテキストの使用量、現在の thinking/verbose トグル、WhatsApp Web 認証情報の最終更新時刻（再リンクが必要かどうかの判別に有用）が確認できます。
  • /context list または /context detail を送信すると、システムプロンプトや注入されたワークスペースファイルの内容（および最大のコンテキスト寄与要素）を確認できます。
  • /stop を単独メッセージとして送信すると、現在の実行を中断し、そのセッションにキューされたフォローアップをクリアし、そこから起動されたすべてのサブエージェント実行を停止します（応答には停止件数が含まれます）。
  • /compact（任意の指示）を単独メッセージとして送信すると、古いコンテキストを要約してウィンドウ領域を解放します。詳細は /concepts/compaction を参照してください。 /concepts/compaction を参照してください。 /concepts/compaction を参照してください。
  • JSONL トランスクリプトは直接開いて、完全なターンを確認できます。

​
ヒント

  • プライマリキーは 1:1 トラフィック専用に保ち、グループは独自のキーを使用させてください。
  • クリーンアップを自動化する場合は、ストア全体ではなく個々のキーを削除して、他のコンテキストを保持してください。

​
セッション起点メタデータ

各セッションエントリには、その由来が（ベストエフォートで）origin に記録されます。
  • label: 人間向けラベル（会話ラベル + グループ件名／チャンネルから解決）
  • provider: 正規化されたチャンネル ID（拡張を含む）
  • from/to: インバウンドエンベロープからの生のルーティング ID
  • accountId: プロバイダーのアカウント ID（マルチアカウント時）
  • threadId: チャンネルがサポートする場合のスレッド／トピック ID 起点フィールドは、ダイレクトメッセージ、チャンネル、グループに対して設定されます。コネクターが配信ルーティングのみを更新する場合（例: DM のメインセッションを新鮮に保つため）でも、セッションが説明用メタデータを保持できるよう、インバウンドコンテキストを提供する必要があります。拡張機能は、インバウンドコンテキストに ConversationLabel、GroupSubject、GroupChannel、GroupSpace、および SenderName を送信し、recordSessionMetaFromInbound を呼び出す（または同じコンテキストを updateLastRoute に渡す）ことでこれを実現できます。 19. コネクタが配信ルーティングのみを更新する場合（たとえば DM のメインセッションを新鮮に保つためなど）でも、セッションが説明用メタデータを保持できるよう、インバウンドコンテキストを提供する必要があります。 20. 拡張機能は、インバウンドコンテキストで ConversationLabel、GroupSubject、GroupChannel、GroupSpace、SenderName を送信し、recordSessionMetaFromInbound を呼び出す（または同じコンテキストを updateLastRoute に渡す）ことでこれを実現できます。