Skip to main content
OpenClaw は、エージェントごとに 1 つのメイン（ダイレクトチャット）セッション を主要なものとして扱います。通常のダイレクトメッセージ（DM）は agent:<agentId>:<mainKey> (デフォルトのメインキーは main) に集約されますが、グループチャットや各チャネルの固有チャットはそれぞれ独立したキーを持ちます。 session.dmScope 設定を使用して、ダイレクトメッセージ のグループ化方法を制御できます:
  • main (デフォルト): すべての DM がメインセッションを共有し、デバイスを跨いでも会話が継続されます。
  • per-peer: 送信者 ID ごとに、チャネルを跨いでセッションを分離します。
  • per-channel-peer: チャネル + 送信者の組み合わせごとに分離します（複数人で 1 つのボットを共有する場合に推奨）。
  • per-account-channel-peer: アカウント + チャネル + 送信者の組み合わせごとに分離します。
session.identityLinks を使用して、異なるチャネルのユーザー ID を 1 つの「正規のアイデンティティ」に紐付けることができます。これにより、同じユーザーであればチャネルが変わっても同じ DM セッションを継続できるようになります。

​
セキュア DM モード (複数人での利用時に推奨)

セキュリティ警告: エージェントが 複数のユーザー から DM を受け取る可能性がある場合は、セキュア DM モードの有効化を強く検討してください。無効な場合、すべてのユーザーが同じ会話コンテキストを共有することになり、プライベートな情報が他のユーザーに漏洩するリスクがあります。
デフォルト設定で発生しうる問題の例:
  1. アリスがエージェントにプライベートな相談（例: 通院の予約）を送信します。
  2. その後、ボブが同じエージェントに「さっきは何の話をしていた？」と尋ねます。
  3. すべての DM が同じセッションを共有しているため、エージェントはアリスとの会話内容を元にボブに回答してしまいます。
解決策: dmScope を設定して、ユーザーごとにセッションを分離します。 
// ~/.openclaw/openclaw.json
{
  session: {
    // セキュア DM モード: チャネル + 送信者ごとにコンテキストを分離。
    dmScope: "per-channel-peer",
  },
}
有効にすべき状況:
  • 複数の送信者に対してペアリングを承認している。
  • 複数のエントリを持つ DM 許可リストを使用している。
  • dmPolicy: "open" (誰でも許可) を設定している。
  • 複数の電話番号やアカウントがエージェントにメッセージを送信できる。
補足事項:
  • 1 人だけで利用する場合は、継続性を重視したデフォルトの dmScope: "main" のままで問題ありません。
  • ローカル CLI でのオンボーディング時、未設定であればデフォルトで session.dmScope: "per-channel-peer" が書き込まれます。
  • 同じチャネルで複数のアカウントを運用している場合は、per-account-channel-peer が最適です。
  • openclaw security audit コマンドで現在の DM 設定の安全性を確認できます。

​
ゲートウェイが「真実のソース」

すべてのセッション状態は ゲートウェイが所有 します。UI クライアント（macOS アプリ、WebChat、TUI など）は、ローカルファイルを直接読み取るのではなく、ゲートウェイに問い合わせてセッション一覧やトークン数を取得します。
  • リモートモード の場合、セッションデータはローカルの Mac ではなく、接続先のリモートホスト上に存在します。
  • UI に表示されるトークン数はゲートウェイのデータに基づきます。クライアント側で JSONL 履歴を解析して計算し直すことはありません。

​
データの保存場所

  • ゲートウェイホスト上:
    • 管理ファイル: ~/.openclaw/agents/<agentId>/sessions/sessions.json (エージェントごと)。
    • 会話履歴（JSONL）: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl。
  • 管理ファイルは sessionKey -> { sessionId, updatedAt, ... } のマップ構造です。このファイル内のエントリを削除しても安全です（必要に応じて再作成されます）。
  • 履歴ファイルには、UI での識別のために displayName, channel, subject などのメタデータが含まれる場合があります。
  • OpenClaw は、古い Pi や Tau のセッションフォルダを読み込むことはありません。

​
メンテナンス (クリーンアップ)

OpenClaw は、sessions.json や履歴ファイルが際限なく増え続けるのを防ぐため、自動的なメンテナンス機能を備えています。

​
デフォルト設定

  • 保持期間: 30 日間 (pruneAfter: "30d")
  • 最大件数: 500 件 (maxEntries: 500)
  • ローテーション: 10MB を超えたら sessions.json を新しくする (rotateBytes: "10mb")
  • ディスク容量制限: デフォルトでは無効 (maxDiskBytes)

​
仕組み

セッションの書き込み時にメンテナンスが実行されます。openclaw sessions cleanup コマンドで手動実行も可能です。
  • mode: "warn" (デフォルト): 削除対象となるエントリを報告するだけで、実際の削除は行いません。
  • mode: "enforce": 以下の順序で実際にクリーンアップを行います:
    1. 保持期間を過ぎた古いエントリを削除。
    2. 上限件数を超える古いエントリを削除。
    3. 参照されなくなった履歴ファイルをアーカイブ。
    4. 構成されたディスク容量予算 (maxDiskBytes) を守るよう、古いものから順に削除。

​
転送手段（トランスポート）とセッションキーの紐付け

  • ダイレクトチャット: session.dmScope に従います。
    • main: agent:<agentId>:<mainKey>。複数の電話番号やチャネルが 1 つのメインセッションに紐付き、単一の会話として機能します。
    • per-peer: agent:<agentId>:dm:<peerId>。
    • per-channel-peer: agent:<agentId>:<channel>:dm:<peerId>。
  • グループチャット: チャネルごとに独立した状態を持ちます。
    • 形式: agent:<agentId>:<channel>:group:<id> (ルームの場合は ...:channel:<id>)。
    • Telegram のトピック（フォーラム）機能では、グループ ID に :topic:<threadId> が付加され、トピックごとに分離されます。
  • その他のソース:
    • Cron ジョブ: cron:<job.id>
    • Webhook: hook:<uuid>
    • ノード実行: node-<nodeId>

​
ライフサイクルとリセット

  • リセットポリシー: セッションは有効期限が切れるまで再利用されます。期限切れの判定は、次にメッセージが届いた際に行われます。
  • 日次リセット: デフォルトは ゲートウェイホストの現地時間で午前 4:00 です。前回の更新がこの時間を跨いでいる場合、新しいセッション ID が発行されます。
  • アイドルリセット: idleMinutes を設定することで、一定時間操作がない場合にリセットできます。日次リセットと併用した場合、どちらか早い方のタイミングでリセットされます。
  • リセットトリガー: /new または /reset メッセージを送ると、即座に新しいセッションが開始されます。/new <モデル名> のように指定して、新しいセッションで使用するモデルを変更することも可能です。
  • 手動リセット: sessions.json から特定のエントリを削除するか、JSONL ファイルを削除することで、強制的にリセットできます。

​
送信ポリシー (Send Policy)

特定のセッションタイプ（例: Discord のグループチャットのみ等）に対して、一括で送信を制限できます。 
{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
      ],
      default: "allow",
    },
  },
}
チャット内からの上書き（所有者のみ）:
  • /send on → このセッションでの送信を許可。
  • /send off → このセッションでの送信を拒否。
  • /send inherit → 上書きを解除し、構成ファイルの設定に従う。

​
検査とデバッグ

  • openclaw status: ストアのパスと最近のセッションを表示します。
  • openclaw sessions --json: すべてのエントリをダンプします。
  • チャットで /status を送る: エージェントの到達可能性、コンテキストの消費量、現在の設定などを確認できます。
  • チャットで /context list を送る: システムプロンプトに含まれる内容や、消費量の多い要因を確認できます。
  • チャットで /stop を送る: 現在の実行を中止し、キューに溜まったメッセージをクリアします。
  • チャットで /compact を送る: 古い履歴を要約して、コンテキストウィンドウの空きを増やします。詳細は 圧縮（コンパクション） を参照してください。