設定

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

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

すべてのチャンネルで同じ DM ポリシーパターンを使用します：

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // ペアリング | 許可リスト | 開放 | 無効      allowFrom: ["tg:123"], // 許可リスト/開放の場合のみ    },  },}

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

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

• agents.defaults.models はエイリアスとモデルごとの設定を保存します。エントリを追加しても、/model または --model のオーバーライドが制限されることはありません。
• agents.defaults.modelPolicy.allow は、オーバーライドとモデル選択用の明示的な許可リストです。完全一致する参照と provider/* ワイルドカードを受け入れます。任意のモデルを許可するには、省略するか [] を使用します。
• モデル参照には provider/model 形式を使用します（例：anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx は、トランスクリプト/ツール画像のダウンスケーリングを制御します（デフォルトは 1200）。値を小さくすると通常、スクリーンショットが多い実行でビジョントークンの使用量が減少します。
• チャット内でのモデル切り替えについてはモデル CLI、認証のローテーションとフォールバック動作についてはモデルのフェイルオーバーを参照してください。
• カスタム/セルフホストのプロバイダーについては、リファレンスのカスタムプロバイダーを参照してください。

DM アクセスは、チャンネルごとに dmPolicy（デフォルトは "pairing"）で制御します：

• "pairing"：不明な送信者には、承認用の 1 回限りのペアリングコードが発行されます
• "allowlist"：allowFrom（またはペアリング済み許可ストア）に含まれる送信者のみ
• "open"：すべての受信 DM を許可します（allowFrom: ["*"] が必要）
• "disabled"：すべての DM を無視します

グループでは、groupPolicy（"allowlist" | "open" | "disabled"）と groupAllowFrom、またはチャンネル固有の許可リストを使用します。

チャンネルごとの詳細については、完全なリファレンスを参照してください。

グループメッセージでは、デフォルトでメンションが必須です。エージェントごとにトリガーパターンを設定します。通常のグループ/チャンネル返信は自動的に投稿されます。エージェントが発言するタイミングを判断する必要がある共有ルームでは、メッセージツール経由の処理を明示的に有効にします：

{  messages: {    visibleReplies: "automatic", // すべての場所でメッセージツールによる送信を必須にするには "message_tool" を設定    groupChat: {      visibleReplies: "message_tool", // 明示的に有効化。表示される出力には message(action=send) が必要      unmentionedInbound: "room_event", // メンションなしで常時流れるグループ会話は、通知されないコンテキスト    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• メタデータのメンション：ネイティブの @メンション（WhatsApp のタップによるメンション、Telegram の @bot など）
• テキストパターン：mentionPatterns 内の安全な正規表現パターン
• 表示される返信：messages.visibleReplies ではメッセージツールによる送信を全体で必須にでき、messages.groupChat.visibleReplies でグループ/チャンネル向けにオーバーライドできます。
• 表示される返信モード、チャンネルごとのオーバーライド、セルフチャットモードについては、完全なリファレンスを参照してください。

共有ベースラインには agents.defaults.skills を使用し、特定の エージェントを agents.entries.*.skills でオーバーライドします：

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // github、weather を継承      { id: "docs", skills: ["docs-search"] }, // デフォルトを置換      { id: "locked-down", skills: [] }, // Skills なし    ],  },}

• デフォルトで Skills を無制限にするには、agents.defaults.skills を省略します。
• デフォルトを継承するには、agents.entries.*.skills を省略します。
• Skills なしにするには、agents.entries.*.skills: [] を設定します。
• Skills、Skills の設定、および 設定リファレンスを参照してください。

チャンネルまたはアカウントの自動ヘルス再起動を無効または有効にします：

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• 1 つのチャンネルまたはアカウントの自動再起動を制御するには、channels.<provider>.healthMonitor.enabled または channels.<provider>.accounts.<id>.healthMonitor.enabled を使用します。
• 運用上のデバッグについてはヘルスチェック、すべてのフィールドについては完全なリファレンスを参照してください。

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

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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: スレッドにバインドされたセッションルーティングのグローバルなデフォルト。/focus、/unfocus、/agents、/session idle、/session max-ageを使用して、セッションごとにバインド、バインド解除、一覧表示、調整を行います（Discord はスレッド、Telegram はトピック／会話をバインドします）。
• スコープ、ID リンク、送信ポリシーについては、セッション管理を参照してください。
• すべてのフィールドについては、完全なリファレンスを参照してください。

エージェントセッションを分離されたサンドボックスランタイムで実行します。

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

まずイメージをビルドします。ソースチェックアウトでは scripts/sandbox-setup.sh を実行し、npm インストールではサンドボックス化 § イメージとセットアップに記載されたインラインの docker build コマンドを参照してください。

詳細なガイドについてはサンドボックス化、すべてのオプションについては完全なリファレンスを参照してください。

公開 App Store ビルドのリレー経由プッシュでは、ホストされた OpenClaw リレー https://ios-push-relay.openclaw.ai を使用します。

カスタムリレーのデプロイには、リレー URL が Gateway のリレー URL と一致する、意図的に分離された iOS ビルド／デプロイパスが必要です。カスタムリレービルドを使用している場合は、Gateway 設定で次のように指定します。

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

CLI での同等の設定:

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

この設定の動作:

• Gateway が外部リレーを介して push.test、ウェイク通知、再接続ウェイクを送信できるようにします。
• ペアリングされた iOS アプリから転送される、登録単位の送信許可を使用します。Gateway にデプロイ全体で共通のリレートークンは必要ありません。
• リレー経由の各登録を、iOS アプリがペアリングした Gateway の ID にバインドし、別の Gateway が保存済み登録を再利用できないようにします。
• ローカル／手動の iOS ビルドでは直接 APNs を使用し続けます。リレー経由の送信は、リレーを介して登録された公式配布ビルドにのみ適用されます。
• 登録トラフィックと送信トラフィックが同じリレーデプロイに到達するよう、iOS ビルドに組み込まれたリレーベース URL と一致させる必要があります。

エンドツーエンドのフロー:

1. 公式 iOS アプリをインストールします。
2. 任意: 意図的に分離されたカスタムリレービルドを使用する場合に限り、Gateway で gateway.push.apns.relay.baseUrl を設定します。
3. iOS アプリを Gateway とペアリングし、Node セッションとオペレーターセッションの両方を接続します。
4. iOS アプリは Gateway の ID を取得し、App Attest とアプリのレシートを使用してリレーに登録した後、リレー経由の push.apns.register ペイロードをペアリング済み Gateway に公開します。
5. Gateway はリレーハンドルと送信許可を保存し、それらを push.test、ウェイク通知、再接続ウェイクに使用します。

運用上の注意:

• iOS アプリを別の Gateway に切り替えた場合は、その Gateway にバインドされた新しいリレー登録を公開できるよう、アプリを再接続してください。
• 異なるリレーデプロイを参照する新しい iOS ビルドを配布した場合、アプリは古いリレーオリジンを再利用せず、キャッシュ済みのリレー登録を更新します。

互換性に関する注意:

• OPENCLAW_APNS_RELAY_BASE_URL と OPENCLAW_APNS_RELAY_TIMEOUT_MS は、一時的な環境変数によるオーバーライドとして引き続き機能します。
• カスタム Gateway のリレー URL は、iOS ビルドに組み込まれたリレーベース URL と一致する必要があります。公開 App Store リリースレーンでは、カスタム iOS リレー URL のオーバーライドが拒否されます。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true は local loopback 専用の開発用エスケープハッチとして引き続き使用できます。HTTP リレー URL を設定に永続化しないでください。

エンドツーエンドのフローについてはiOS アプリ、リレーのセキュリティモデルについては認証と信頼のフローを参照してください。

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

• every: 期間文字列（30m、2h）。無効にするには 0m を設定します。デフォルト: 30m。
• target: last | none | <channel-id>（例: discord、matrix、telegram、whatsapp）
• directPolicy: DM 形式の Heartbeat ターゲットでは allow（デフォルト）または block
• 詳細なガイドについては、Heartbeatを参照してください。

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: 完了した分離実行セッションを SQLite のセッション行から削除します（デフォルトは 24h。無効にするには false を設定）。
• 実行履歴では、ジョブごとに最新のターミナル行 2000 件が自動的に保持されます。失われた行には 24 時間のクリーンアップ期間が引き続き適用されます。
• 機能の概要と CLI の例については、Cron ジョブを参照してください。

Gateway で HTTP Webhook エンドポイントを有効にします。

{  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,      },    ],  },}

セキュリティ上の注意:

• すべてのフック／Webhook ペイロードの内容を信頼できない入力として扱ってください。
• 専用の hooks.token を使用し、使用中の Gateway 認証シークレット（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN または gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD）を再利用しないでください。
• フック認証はヘッダーのみ（Authorization: Bearer ... または x-openclaw-token）を使用します。クエリ文字列のトークンは拒否されます。
• hooks.path を / にすることはできません。Webhook の受信パスには /hooks などの専用サブパスを使用してください。
• 厳密に範囲を限定したデバッグを行う場合を除き、安全でないコンテンツのバイパスフラグ（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）は無効のままにしてください。
• hooks.allowRequestSessionKey を有効にする場合は、呼び出し元が選択するセッションキーを制限するため、hooks.allowedSessionKeyPrefixes も設定してください。
• フックによって駆動されるエージェントには、性能の高い最新モデルの階層と厳格なツールポリシー（可能であれば、メッセージングのみに制限し、サンドボックス化を併用するなど）を推奨します。

すべてのマッピングオプションと Gmail 連携については、完全なリファレンスを参照してください。

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

{  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" } },  ],}

バインドルールとエージェントごとのアクセスプロファイルについては、マルチエージェントと完全なリファレンスを参照してください。

大規模な設定を整理するには、$include を使用します。

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

• 単一ファイル: それを含むオブジェクトを置き換えます
• ファイルの配列: 順番にディープマージされ（後の値が優先）、最大 10 階層までネストできます
• 兄弟キー: インクルード後にマージされます（インクルードされた値を上書きします）
• 相対パス: インクルード元ファイルを基準に解決されます
• パス形式: インクルードパスに null バイトを含めることはできず、解決前と解決後の両方で 4096 文字未満である必要があります
• OpenClaw による書き込み: 書き込みによって、plugins: { $include: "./plugins.json5" } のような単一ファイルのインクルードに基づく最上位セクションが 1 つだけ変更される場合、 OpenClaw はそのインクルードファイルを更新し、openclaw.json はそのまま維持します
• サポートされていないライトスルー: ルートインクルード、インクルード配列、兄弟キーによるオーバーライドを持つインクルードでは、 設定をフラット化せず、OpenClaw による書き込みをフェイルクローズします
• 制限: $include パスは、 openclaw.json を格納するディレクトリ配下に解決される必要があります。複数のマシンまたはユーザー間でツリーを共有するには、 OPENCLAW_INCLUDE_ROOTS に、インクルードから参照可能な追加ディレクトリのパスリスト（POSIX では :、Windows では ;）を設定します。 シンボリックリンクは解決後に再チェックされるため、字句上は設定ディレクトリ内に存在していても、 実際のターゲットが許可されたすべてのルート外にあるパスは引き続き拒否されます。
• エラー処理: ファイルの欠落、解析エラー、循環インクルード、無効なパス形式、長さ超過に対して明確なエラーを表示します