設定

每個頻道在 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

所有頻道都共用相同的私訊政策模式：

{
  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 控制 transcript/tool 圖像縮小（預設 1200）；較低的值通常會降低大量螢幕截圖執行中的視覺 token 用量。
• 請參閱模型 CLI 了解如何在聊天中切換模型，並參閱模型容錯移轉 了解驗證輪替與備援行為。
• 對於自訂/自架供應商，請參閱參考中的自訂供應商。

私訊存取權會透過 dmPolicy 依頻道控制：

• "pairing"（預設）：未知寄件者會收到一次性配對碼以供核准
• "allowlist"：只允許 allowFrom 中的寄件者（或已配對允許儲存區中的寄件者）
• "open"：允許所有傳入私訊（需要 allowFrom: ["*"]）
• "disabled"：忽略所有私訊

對於群組，請使用 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 } },
    },
  },
}

• 中繼資料提及：原生 @-mentions（WhatsApp 點選提及、Telegram @bot 等）
• 文字模式：mentionPatterns 中的安全 regex 模式
• 可見回覆：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
    ],
  },
}

• 省略 agents.defaults.skills，預設即可不限制 skills。
• 省略 agents.list[].skills 以繼承預設值。
• 設定 agents.list[].skills: [] 表示不使用 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 應大於或等於檢查間隔。
• 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled，可在不停用全域監控的情況下，停用單一頻道或帳號的自動重啟。
• 請參閱健康檢查 進行營運偵錯，並參閱完整參考 了解所有欄位。

讓本機用戶端在負載高或低效能主機上，有更多時間完成驗證前 WebSocket 交握：

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• 預設為 15000 毫秒。
• OPENCLAW_HANDSHAKE_TIMEOUT_MS 對一次性服務或 shell 覆寫仍具有優先權。
• 優先修復啟動/事件迴圈停滯；此旋鈕適用於健康但暖機期間較慢的主機。

工作階段控制對話連續性與隔離：

{
  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：thread-bound 工作階段路由的全域預設值（Discord 支援 /focus、/unfocus、/agents、/session idle 與 /session max-age）。
• 請參閱工作階段管理 了解範圍、身分連結與傳送政策。
• 請參閱完整參考 了解所有欄位。

在隔離的沙箱執行階段中執行代理程式工作階段：

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

請先建置映像檔 - 若是從原始碼 checkout，請執行 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 App 轉送、以註冊為範圍的傳送授權。Gateway 不需要部署範圍的中繼權杖。
• 將每個中繼支援的註冊繫結到 iOS App 配對的 Gateway 身分，因此另一個 Gateway 無法重用已儲存的註冊。
• 讓本機/手動 iOS 建置維持直接使用 APNs。中繼支援的傳送僅適用於透過中繼註冊的官方發佈建置。
• 必須與官方/TestFlight iOS 建置內建的中繼基底 URL 相符，讓註冊與傳送流量到達同一個中繼部署。

端對端流程：

1. 安裝以相同中繼基底 URL 編譯的官方/TestFlight iOS 建置。
2. 在 Gateway 上設定 gateway.push.apns.relay.baseUrl。
3. 將 iOS App 配對到 Gateway，並讓 Node 與操作者工作階段都連線。
4. iOS App 會擷取 Gateway 身分，使用 App Attest 加上 App 收據向中繼註冊，然後將中繼支援的 push.apns.register 承載發佈到已配對的 Gateway。
5. Gateway 會儲存中繼控制代碼與傳送授權，然後將它們用於 push.test、喚醒提示，以及重新連線喚醒。

操作注意事項：

• 如果你將 iOS App 切換到不同的 Gateway，請重新連線 App，讓它可以發佈繫結到該 Gateway 的新中繼註冊。
• 如果你發佈指向不同中繼部署的新 iOS 建置，App 會重新整理其快取的中繼註冊，而不是重用舊的中繼來源。

相容性注意事項：

• OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作為暫時的環境覆寫使用。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是僅限 loopback 的開發逃生出口；請勿在設定中持久保存 HTTP 中繼 URL。

如需端對端流程，請參閱 iOS App；如需中繼安全性模型，請參閱驗證與信任流程。

{
  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 擁有的寫入：當寫入只變更由單一檔案 include 支援的單一頂層區段時，例如 plugins: { $include: "./plugins.json5" }，OpenClaw 會更新該 include 檔案，並保持 openclaw.json 不變
• 不支援的穿透寫入：根 include、include 陣列，以及帶有同層覆寫的 include 會對 OpenClaw 擁有的寫入以失敗關閉處理，而不是將設定扁平化
• 限制範圍：$include 路徑必須解析到保存 openclaw.json 的目錄底下。若要在機器或使用者之間共用樹狀目錄，請將 OPENCLAW_INCLUDE_ROOTS 設為路徑清單（POSIX 上為 :，Windows 上為 ;），列出 include 可參照的其他目錄。符號連結會被解析並重新檢查，因此即使某個路徑在字面上位於設定目錄中，但其實際目標逃逸到所有允許根目錄之外，仍會被拒絕。
• 錯誤處理：針對缺少檔案、剖析錯誤與循環 include 提供清楚錯誤