設定

每個頻道在 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 和模型選擇器篩選到指定 provider，同時仍使用動態模型探索。
• 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 新增允許清單項目，而不移除既有模型。除非傳入 --replace，否則會移除項目的純取代會被拒絕。
• 模型參照使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
• agents.defaults.imageMaxDimensionPx 控制 transcript/tool 圖片縮小（預設 1200）；較低的值通常會降低大量截圖執行中的 vision-token 使用量。
• 請參閱模型 CLI了解如何在聊天中切換模型，並參閱模型容錯移轉了解授權輪替與備援行為。
• 自訂/自架 provider 請參閱參考中的自訂 provider。

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

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

對於群組，請使用 groupPolicy + groupAllowFrom 或頻道專屬允許清單。

各頻道詳細資訊請參閱完整參考。

群組訊息預設為需要提及。請為每個 Agent 設定觸發模式，並讓可見的聊天室回覆保持在預設 message-tool 路徑，除非你有意使用舊式自動最終回覆：

{  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 可以要求全域使用 message-tool 傳送；messages.groupChat.visibleReplies 會覆寫群組/頻道的設定。
• 可見回覆模式、各頻道覆寫與自我聊天模式請參閱完整參考。

使用 agents.defaults.skills 作為共用基準，然後用 agents.list[].skills 覆寫特定 Agent：

{  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 handshake：

{  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：用於執行緒繫結工作階段路由的全域預設值（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 命令。

請參閱沙箱以取得完整指南，並參閱完整參考了解所有選項。

relay 支援的推播在 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 透過外部 relay 傳送 push.test、喚醒提示和重新連線喚醒。
• 使用由已配對 iOS App 轉送、以註冊為範圍的傳送授權。Gateway 不需要部署範圍的 relay token。
• 將每個 relay 支援的註冊繫結到 iOS App 配對的 Gateway 身分，因此另一個 Gateway 無法重用已儲存的註冊。
• 讓本機/手動 iOS 建置維持直接 APNs。relay 支援的傳送僅適用於透過 relay 註冊的官方發佈建置。
• 必須符合內建於官方/TestFlight iOS 建置的 relay base URL，讓註冊和傳送流量到達同一個 relay 部署。

端對端流程：

1. 安裝使用相同 relay base URL 編譯的官方/TestFlight iOS 建置。
2. 在 Gateway 上設定 gateway.push.apns.relay.baseUrl。
3. 將 iOS App 配對到 Gateway，並讓 node 與操作員工作階段都連線。
4. iOS App 擷取 Gateway 身分，使用 App Attest 加上 app receipt 向 relay 註冊，然後將 relay 支援的 push.apns.register payload 發佈到已配對的 Gateway。
5. Gateway 儲存 relay handle 和傳送授權，然後將它們用於 push.test、喚醒提示和重新連線喚醒。

操作注意事項：

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

相容性注意事項：

• OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作為暫時的環境覆寫使用。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是僅限 loopback 的開發逃生口；不要在設定中保留 HTTP relay URL。

請參閱 iOS App 了解端對端流程，並參閱驗證與信任流程了解 relay 安全模型。

{  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。
• 請參閱 Cron 工作，了解功能概覽和 CLI 範例。

在 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 payload 內容視為不受信任的輸入。
• 使用專用的 hooks.token；不要重用共用的 Gateway token。
• Hook 驗證僅限標頭（Authorization: Bearer ... 或 x-openclaw-token）；查詢字串 token 會被拒絕。
• hooks.path 不能是 /；請將 Webhook 入口保留在專用子路徑，例如 /hooks。
• 除非進行嚴格限定範圍的偵錯，否則請停用不安全內容繞過旗標（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）。
• 如果啟用 hooks.allowRequestSessionKey，也請設定 hooks.allowedSessionKeyPrefixes，以限制呼叫者選取的工作階段金鑰。
• 對於 hook 驅動的代理，建議使用強大的現代模型層級和嚴格工具政策（例如僅限訊息傳遞，並在可能時加上沙箱）。

請參閱完整參考，了解所有 mapping 選項和 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"],  },}

• 單一檔案：取代所屬物件
• 檔案陣列：依序深度合併（後者優先）
• 同層金鑰：在 includes 之後合併（覆寫 included 值）
• 巢狀 includes：最多支援 10 層深度
• 相對路徑：相對於執行 include 的檔案解析
• OpenClaw 擁有的寫入：當寫入只變更一個最上層區段，且該區段 由單一檔案 include 支援，例如 plugins: { $include: "./plugins.json5" }， OpenClaw 會更新該 included 檔案，並保持 openclaw.json 完整不變
• 不支援的寫入穿透：root includes、include arrays，以及具有 同層覆寫的 includes，對 OpenClaw 擁有的寫入會以失敗關閉處理，而不是 攤平成設定
• 限制範圍：$include 路徑必須解析到保存 openclaw.json 的目錄下。若要在多台機器或多個使用者之間共用樹狀結構，請將 OPENCLAW_INCLUDE_ROOTS 設為額外目錄的路徑清單（POSIX 上為 :，Windows 上為 ;）， includes 可參照這些目錄。符號連結會被解析並重新檢查，因此如果路徑在字面上位於設定目錄中， 但其真實目標逃逸出每個允許的 root，仍會被拒絕。
• 錯誤處理：針對缺少檔案、解析錯誤和循環 includes 提供清楚錯誤