設定

各チャンネルは`channels.<provider>`配下に独自の設定セクションを持ちます。セットアップ手順は各チャンネルの専用ページを参照してください：

- [WhatsApp](/docs/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/docs/channels/telegram) — `channels.telegram`
- [Discord](/docs/channels/discord) — `channels.discord`
- [Slack](/docs/channels/slack) — `channels.slack`
- [Signal](/docs/channels/signal) — `channels.signal`
- [iMessage](/docs/channels/imessage) — `channels.imessage`
- [Google Chat](/docs/channels/googlechat) — `channels.googlechat`
- [Mattermost](/docs/channels/mattermost) — `channels.mattermost`
- [MS Teams](/docs/channels/msteams) — `channels.msteams`

すべてのチャンネルは同じDMポリシーパターンを共有します：

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // allowlist/openの場合のみ
    },
  },
}
```

プライマリモデルとオプションのフォールバックを設定：

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
```

- `agents.defaults.models`はモデルカタログを定義し、`/model`の許可リストとして機能します。
- モデル参照は`provider/model`形式（例：`anthropic/claude-opus-4-6`）を使用します。
- `agents.defaults.imageMaxDimensionPx`はプロバイダー呼び出し前のトランスクリプト/ツール画像のダウンスケーリングを制御（デフォルト`1200`）。低い値は通常、スクリーンショットの多い実行でビジョントークンの使用量を削減します。
- チャットでのモデル切り替えについては[Models CLI](/docs/concepts/models)を、認証ローテーションとフォールバック動作については[Model Failover](/docs/concepts/model-failover)を参照してください。
- カスタム/セルフホストプロバイダーについてはリファレンスの[Custom providers](/docs/gateway/configuration-reference#custom-providers-and-base-urls)を参照してください。

DMアクセスはチャンネルごとに`dmPolicy`で制御されます：

- `"pairing"`（デフォルト）：不明な送信者にワンタイムペアリングコードを発行して承認
- `"allowlist"`：`allowFrom`（またはペアリング済み許可ストア）内の送信者のみ
- `"open"`：すべての受信DMを許可（`allowFrom: ["*"]`が必要）
- `"disabled"`：すべてのDMを無視

グループの場合は`groupPolicy` + `groupAllowFrom`またはチャンネル固有の許可リストを使用。

チャンネルごとの詳細は[完全リファレンス](/docs/gateway/configuration-reference#dm-and-group-access)を参照してください。

グループメッセージはデフォルトで**メンション必須**です。エージェントごとにパターンを設定：

```json5
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **メタデータメンション**：ネイティブの@メンション（WhatsAppのタップしてメンション、Telegramの@botなど）
- **テキストパターン**：`mentionPatterns`内の正規表現パターン
- 完全リファレンスのチャンネルごとのオーバーライドとセルフチャットモードについては[完全リファレンス](/docs/gateway/configuration-reference#group-chat-mention-gating)を参照してください。

セッションは会話の継続性と分離を制御します：

```json5
{
  session: {
    dmScope: "per-channel-peer",  // マルチユーザーに推奨
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`：`main`（共有） | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：スレッドバウンドセッションルーティングのグローバルデフォルト（Discordでは`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`をサポート）。
- スコープ、アイデンティティリンク、送信ポリシーについては[Session Management](/docs/concepts/session)を参照してください。
- すべてのフィールドについては[完全リファレンス](/docs/gateway/configuration-reference#session)を参照してください。

エージェントセッションを分離されたDockerコンテナで実行：

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
```

まずイメージをビルド：`scripts/sandbox-setup.sh`

完全なガイドは[Sandboxing](/docs/gateway/sandboxing)を、すべてのオプションは[完全リファレンス](/docs/gateway/configuration-reference#sandbox)を参照してください。

リレーバックドプッシュは`openclaw.json`で設定されます。

ゲートウェイ設定に以下を記述：

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // オプション。デフォルト：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

CLI相当：

```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```

これにより：

- ゲートウェイが外部リレー経由で`push.test`、ウェイクナッジ、再接続ウェイクを送信可能になります。
- ペアリング済みiOSアプリによって転送される登録スコープ付き送信グラントを使用します。ゲートウェイはデプロイメント全体のリレートークンを必要としません。
- 各リレーバックド登録をiOSアプリがペアリングしたゲートウェイアイデンティティにバインドし、別のゲートウェイが保存済み登録を再利用できないようにします。
- ローカル/手動iOSビルドはダイレクトAPNsのまま。リレーバックド送信はリレー経由で登録した公式配布ビルドにのみ適用されます。
- 公式/TestFlightのiOSビルドにベイクされたリレーベースURLと一致する必要があり、登録と送信トラフィックが同じリレーデプロイメントに到達するようにします。

エンドツーエンドフロー：

1. 同じリレーベースURLでコンパイルされた公式/TestFlightのiOSビルドをインストール。
2. ゲートウェイで`gateway.push.apns.relay.baseUrl`を設定。
3. iOSアプリをゲートウェイにペアリングし、ノードとオペレーターの両セッションを接続。
4. iOSアプリがゲートウェイアイデンティティを取得し、App Attestとアプリレシートを使用してリレーに登録、その後リレーバックドの`push.apns.register`ペイロードをペアリング済みゲートウェイに公開。
5. ゲートウェイがリレーハンドルと送信グラントを保存し、`push.test`、ウェイクナッジ、再接続ウェイクに使用。

運用上の注意：

- iOSアプリを別のゲートウェイに切り替えた場合、アプリを再接続してそのゲートウェイにバインドされた新しいリレー登録を公開してください。
- 別のリレーデプロイメントを指す新しいiOSビルドを出荷した場合、アプリは古いリレーオリジンを再利用する代わりにキャッシュされたリレー登録をリフレッシュします。

互換性に関する注意：

- `OPENCLAW_APNS_RELAY_BASE_URL`と`OPENCLAW_APNS_RELAY_TIMEOUT_MS`は一時的な環境変数オーバーライドとして引き続き動作。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`はループバック限定の開発用エスケープハッチとして残存。HTTP リレーURLを設定に永続化しないでください。

エンドツーエンドフローについては[iOS App](/docs/platforms/ios#relay-backed-push-for-official-builds)を、リレーセキュリティモデルについては[Authentication and trust flow](/docs/platforms/ios#authentication-and-trust-flow)を参照してください。

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
```

- `every`：duration文字列（`30m`、`2h`）。`0m`で無効化。
- `target`：`last` | `whatsapp` | `telegram` | `discord` | `none`
- `directPolicy`：`allow`（デフォルト）または`block`（DMスタイルのハートビートターゲット用）
- 完全なガイドは[Heartbeat](/docs/gateway/heartbeat)を参照。

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`：完了済みの分離cron実行セッションを`sessions.json`から削除するまでの期間（デフォルト`24h`。`false`で無効化）。
- `runLog`：`cron/runs/<jobId>.jsonl`をサイズと保持行数で刈り込み。
- 機能の概要とCLI例については[Cron jobs](/docs/automation/cron-jobs)を参照。

Gateway上でHTTP webhookエンドポイントを有効化：

```json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
```

セキュリティ上の注意：
- すべてのhook/webhookペイロードコンテンツを信頼できない入力として扱ってください。
- unsafe-contentバイパスフラグ（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）は、厳密にスコープされたデバッグ以外は無効のままにしてください。
- hookドリブンのエージェントでは、強力な最新モデルティアと厳格なツールポリシー（例：メッセージングのみ＋可能な場合はサンドボックス化）を推奨。

すべてのマッピングオプションとGmail統合については[完全リファレンス](/docs/gateway/configuration-reference#hooks)を参照。

個別のワークスペースとセッションを持つ複数の分離エージェントを実行：

```json5
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
```

バインディングルールとエージェントごとのアクセスプロファイルについては[Multi-Agent](/docs/concepts/multi-agent)と[完全リファレンス](/docs/gateway/configuration-reference#multi-agent-routing)を参照。

`$include`で大きな設定を整理：

```json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
```

- **単一ファイル**：含むオブジェクトを置換
- **ファイルの配列**：順序通りにディープマージ（後のものが優先）
- **兄弟キー**：include後にマージ（インクルードされた値をオーバーライド）
- **ネストされたinclude**：10レベルまでサポート
- **相対パス**：インクルードするファイルからの相対解決
- **エラー処理**：欠落ファイル、パースエラー、循環includeに対する明確なエラー

設定全体を検証＋書き込み、1ステップでGatewayを再起動します。

> **警告：** `config.apply`は**設定全体**を置換します。部分更新には`config.patch`を、単一キーには`openclaw config set`を使用してください。

パラメータ：

- `raw`（文字列） — 設定全体のJSON5ペイロード
- `baseHash`（オプション） — `config.get`からの設定ハッシュ（設定が存在する場合は必須）
- `sessionKey`（オプション） — 再起動後のウェイクアップping用セッションキー
- `note`（オプション） — 再起動センチネル用のメモ
- `restartDelayMs`（オプション） — 再起動までの遅延（デフォルト2000）

再起動リクエストは保留中/実行中のものがある間は統合され、再起動サイクル間に30秒のクールダウンが適用されます。

```bash
openclaw gateway call config.get --params '{}'  # payload.hashをキャプチャ
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
```

既存の設定に部分更新をマージします（JSONマージパッチセマンティクス）：

- オブジェクトは再帰的にマージ
- `null`はキーを削除
- 配列は置換

パラメータ：

- `raw`（文字列） — 変更するキーのみのJSON5
- `baseHash`（必須） — `config.get`からの設定ハッシュ
- `sessionKey`、`note`、`restartDelayMs` — `config.apply`と同じ

再起動動作は`config.apply`と同じ：保留中の再起動の統合＋再起動サイクル間の30秒クールダウン。

```bash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
```

有効にすると、期待するキーが設定されていない場合、OpenClawはログインシェルを実行して不足キーのみをインポートします：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

環境変数相当：OPENCLAW_LOAD_SHELL_ENV=1

${VAR_NAME}で設定文字列値内の環境変数を参照：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

ルール：

• 大文字名のみマッチ：[A-Z_][A-Z0-9_]*
• 欠落/空の変数は読み込み時にエラー
• $${VAR}でリテラル出力にエスケープ
• $includeファイル内でも動作
• インライン置換："${BASE}/v1" → "https://api.example.com/v1"

SecretRefオブジェクトをサポートするフィールドでは以下を使用可能：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRefの詳細（env/file/exec用のsecrets.providersを含む）はSecrets Managementにあります。 対応する資格情報パスはSecretRef Credential Surfaceに記載されています。