設定

各チャネルには、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 の許可リストとして機能します。
• 既存モデルを削除せずに許可リストエントリを追加するには、openclaw config set agents.defaults.models '<json>' --strict-json --merge を使用します。エントリを削除することになる単純な置換は、--replace を渡さない限り拒否されます。
• モデル参照は provider/model 形式を使用します (例: anthropic/claude-opus-4-6)。
• agents.defaults.imageMaxDimensionPx はトランスクリプト/ツール画像の縮小を制御します (デフォルト 1200)。値を下げると、スクリーンショットが多い実行で通常ビジョントークン使用量を削減できます。
• チャット内でのモデル切り替えについてはモデル CLIを、認証ローテーションとフォールバック動作についてはモデルフェイルオーバーを参照してください。
• カスタム/セルフホストプロバイダーについては、リファレンスのカスタムプロバイダーを参照してください。

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

• "pairing" (デフォルト): 不明な送信者に承認用の 1 回限りのペアリングコードを送る
• "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 ミリ秒です。
• 1 回限りのサービスまたはシェル上書きでは、引き続き 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 セッションと operator セッションの両方を接続させます。
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,
      },
    ],
  },
}

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

• すべてのフック/Webhook ペイロード内容を信頼できない入力として扱ってください。
• 専用の hooks.token を使用し、共有 Gateway トークンを再利用しないでください。
• フック認証はヘッダーのみです（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"],
  },
}

• 単一ファイル: 含んでいるオブジェクトを置き換えます
• ファイル配列: 順番に深くマージされます（後のものが優先）
• 兄弟キー: 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 に対する明確なエラー