> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# セッション管理

> OpenClaw は、エージェントごとに 1 つのメイン（ダイレクトチャット）セッション を主要なものとして扱います。セキュア DM モード (複数人での利用時に推奨)、ゲートウェイが「真実のソース」、データの保存場所を確認できます。

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` を設定して、ユーザーごとにセッションを分離します。

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
// ~/.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 のグループチャットのみ等）に対して、一括で送信を制限できます。

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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` を送る: 古い履歴を要約して、コンテキストウィンドウの空きを増やします。詳細は [圧縮（コンパクション）](/concepts/compaction) を参照してください。