設定

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

プライマリモデルと任意のフォールバックを設定します:

{  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 の許可リストとして機能します。provider/* エントリは、動的なモデル検出を引き続き使用しながら、/model、/models、モデルピッカーを選択したプロバイダーに絞り込みます。
• 既存のモデルを削除せずに許可リストエントリを追加するには、openclaw config set agents.defaults.models '<json>' --strict-json --merge を使用します。エントリを削除する通常の置き換えは、--replace を渡さない限り拒否されます。
• モデル参照は provider/model 形式を使用します（例: anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx はトランスクリプト/ツール画像の縮小を制御します（デフォルト 1200）。値を小さくすると、スクリーンショットの多い実行で通常は vision トークン使用量を削減できます。
• チャット内でモデルを切り替えるには Models CLI を、認証ローテーションとフォールバック動作については Model Failover を参照してください。
• カスタム/セルフホストのプロバイダーについては、リファレンスの カスタムプロバイダー を参照してください。

DM アクセスは dmPolicy によってチャネルごとに制御されます:

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

グループには、groupPolicy + groupAllowFrom またはチャネル固有の許可リストを使用します。

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

グループメッセージはデフォルトでメンションを必須とします。エージェントごとにトリガーパターンを設定し、従来の自動最終返信を意図的に使いたい場合を除き、表示されるルーム返信はデフォルトのメッセージツールパスのままにしてください:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  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.list[].skills で上書きします:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

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

古くなっているように見えるチャネルを Gateway がどれくらい積極的に再起動するかを制御します:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• ヘルス監視による再起動をグローバルに無効化するには、gateway.channelHealthCheckMinutes: 0 を設定します。
• channelStaleEventThresholdMinutes はチェック間隔以上にする必要があります。
• グローバル監視を無効化せずに、1 つのチャネルまたはアカウントの自動再起動を無効化するには、channels.<provider>.healthMonitor.enabled または channels.<provider>.accounts.<id>.healthMonitor.enabled を使用します。
• 運用デバッグについては ヘルスチェック を、すべてのフィールドについては 完全なリファレンス を参照してください。

負荷が高いホストや低性能のホストで、ローカルクライアントが認証前 WebSocket ハンドシェイクを完了するための 時間を増やします:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• デフォルトは 15000 ミリ秒です。
• 一回限りのサービスまたはシェルの上書きでは、引き続き OPENCLAW_HANDSHAKE_TIMEOUT_MS が優先されます。
• まずは起動時またはイベントループの停止を修正することを優先してください。このノブは、正常だがウォームアップ中に遅いホスト向けです。

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

{  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: スレッドに紐づいたセッションルーティングのグローバルデフォルト（Discord は /focus、/unfocus、/agents、/session idle、/session max-age をサポートします）。
• スコープ、ID リンク、送信ポリシーについては セッション管理 を参照してください。
• すべてのフィールドについては 完全なリファレンス を参照してください。

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

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

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

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

リレー経由プッシュは openclaw.json で構成します。

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 のままにします。リレー経由送信は、リレー経由で登録された公式配布ビルドにのみ適用されます。
• 登録トラフィックと送信トラフィックが同じリレーデプロイに到達するよう、公式/TestFlight iOS ビルドに組み込まれたリレーのベース URL と一致している必要があります。

エンドツーエンドの流れ:

1. 同じリレーのベース URL でコンパイルされた公式/TestFlight 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 は一時的な環境変数オーバーライドとして引き続き機能します。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true は local loopback 専用の開発用エスケープハッチのままです。HTTP リレー URL を設定に永続化しないでください。

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

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

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

{  cron: {    enabled: true,    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: 完了した分離実行セッションを sessions.json から削除します（デフォルトは 24h。無効にするには false を設定）。
• runLog: cron/runs/<jobId>.jsonl をサイズと保持行数で削除します。
• 機能概要と 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,      },    ],  },}

セキュリティに関する注意:

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

すべてのマッピングオプションと 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"],  },}

• 単一ファイル: それを含むオブジェクトを置き換えます
• ファイルの配列: 順番にディープマージされます（後のものが優先）
• 兄弟キー: include の後にマージされます（include された値をオーバーライド）
• ネストした include: 最大 10 階層までサポートされます
• 相対パス: include しているファイルからの相対で解決されます
• OpenClaw 所有の書き込み: 書き込みが、plugins: { $include: "./plugins.json5" } のような単一ファイル include に裏付けられた 1 つのトップレベルセクションだけを変更する場合、OpenClaw はその include されたファイルを更新し、openclaw.json はそのままにします
• サポートされない書き込みスルー: ルート include、include 配列、兄弟オーバーライドを持つ include は、OpenClaw 所有の書き込みで設定をフラット化する代わりにフェイルクローズします
• 閉じ込め: $include パスは openclaw.json を保持するディレクトリ配下に解決される必要があります。マシンやユーザー間でツリーを共有するには、include が参照できる追加ディレクトリのパスリスト（POSIX では :、Windows では ;）を OPENCLAW_INCLUDE_ROOTS に設定します。シンボリックリンクは解決されて再チェックされるため、字句上は設定ディレクトリ内にあるパスでも、実際のターゲットがすべての許可済みルートの外に出る場合は拒否されます。
• エラー処理: 欠落ファイル、解析エラー、循環 include に対して明確なエラーを出します