設定

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

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

{  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 的允許清單；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）；較低的值通常可減少大量使用螢幕截圖之執行作業的視覺權杖用量。
• 請參閱模型命令列介面，了解如何在聊天中切換模型；並參閱模型容錯移轉，了解驗證輪替與備援行為。
• 如需自訂／自行託管的供應商，請參閱參考文件中的自訂供應商。

私訊存取權限透過各頻道的 dmPolicy 控制（預設為 "pairing"）：

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

對於群組，請使用 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.list[].skills 覆寫特定代理程式：

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [

      { id: "writer" }, // 繼承 github、weather

      { id: "docs", skills: ["docs-search"] }, // 取代預設值

      { id: "locked-down", skills: [] }, // 無 Skills

    ],  },}

• 預設省略 agents.defaults.skills，即可不限制 Skills。
• 省略 agents.list[].skills 以繼承預設值。
• 設定 agents.list[].skills: [] 以停用所有 Skills。
• 請參閱 Skills、Skills 設定，以及 設定參考。

控制閘道重新啟動疑似停滯頻道的積極程度：

{  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 毫秒。
• 針對單次服務或 shell 覆寫，OPENCLAW_HANDSHAKE_TIMEOUT_MS 仍具有較高優先順序。
• 請優先修正啟動或事件迴圈停滯問題；此設定適用於運作正常，但在暖機期間速度較慢的主機。

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

{  session: {

    dmScope: "per-channel-peer",  // 建議用於多使用者情境

    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 綁定主題／對話）。
• 如需瞭解範圍界定、身分連結和傳送原則，請參閱工作階段管理。
• 如需所有欄位，請參閱完整參考資料。

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

{  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。

自訂中繼服務部署需要刻意採用獨立的 iOS 組建／部署路徑，且其中繼服務 URL 必須與閘道的中繼服務 URL 相符。如果你使用自訂中繼服務組建，請在閘道設定中設定以下內容：

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // 選填。預設值：10000          timeoutMs: 10000,        },      },    },  },}

等效的命令列介面：

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

此設定的作用：

• 讓閘道可透過外部中繼傳送 push.test、喚醒提示及重新連線喚醒。
• 使用由已配對 iOS App 轉送、範圍限於註冊項目的傳送授權。閘道不需要整個部署共用的中繼權杖。
• 將每個由中繼支援的註冊項目綁定至 iOS App 所配對的閘道身分，因此其他閘道無法重複使用已儲存的註冊項目。
• 本機／手動 iOS 組建仍直接使用 APNs。由中繼支援的傳送僅適用於透過中繼註冊的官方發行組建。
• 必須與內建於 iOS 組建中的中繼基礎 URL 相符，確保註冊與傳送流量抵達同一個中繼部署。

端對端流程：

1. 安裝官方 iOS App。
2. 選用：只有在使用刻意分離的自訂中繼組建時，才在閘道上設定 gateway.push.apns.relay.baseUrl。
3. 將 iOS App 與閘道配對，並讓節點與操作員工作階段都建立連線。
4. iOS App 取得閘道身分，使用 App Attest 與 App 收據向中繼註冊，接著將由中繼支援的 push.apns.register 承載資料發布至已配對的閘道。
5. 閘道儲存中繼控制代碼與傳送授權，接著將其用於 push.test、喚醒提示及重新連線喚醒。

操作注意事項：

• 如果你將 iOS App 切換至其他閘道，請重新連線 App，使其可發布綁定至該閘道的新中繼註冊項目。
• 如果你發布指向不同中繼部署的新 iOS 組建，App 會重新整理其快取的中繼註冊項目，而不會重複使用舊的中繼來源。

相容性注意事項：

• OPENCLAW_APNS_RELAY_BASE_URL 與 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作為暫時的環境變數覆寫值。
• 自訂閘道中繼 URL 必須與內建於 iOS 組建中的中繼基礎 URL 相符；公開的 App Store 發行管道會拒絕自訂 iOS 中繼 URL 覆寫值。
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是僅限回送位址的開發逃生機制；請勿將 HTTP 中繼 URL 永久儲存在設定中。

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

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

• every：持續時間字串（30m、2h）。設為 0m 可停用。預設值：30m。
• target：last | none | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
• directPolicy：針對私訊類型的心跳偵測目標，設為 allow（預設值）或 block
• 完整指南請參閱心跳偵測。

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // 預設值；排程分派 + 隔離的排程代理程式回合執行    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention：從 SQLite 工作階段資料列中清除已完成的隔離執行工作階段（預設為 24h；設為 false 可停用）。
• runLog：依工作清除保留的排程執行歷程資料列。歷程儲存在 SQLite 中；保留 maxBytes（預設為 2_000_000）以相容較舊的檔案型執行記錄，keepLines 預設為 2000。
• 如需功能概覽與命令列介面範例，請參閱排程工作。

在閘道上啟用 HTTP 網路鉤子端點：

{  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／網路鉤子承載內容視為不受信任的輸入。
• 使用專用的 hooks.token；不要重複使用有效的閘道驗證密鑰（gateway.auth.token／OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password／OPENCLAW_GATEWAY_PASSWORD）。
• Hook 驗證僅支援標頭（Authorization: Bearer ... 或 x-openclaw-token）；查詢字串權杖會遭拒絕。
• hooks.path 不可為 /；請將網路鉤子輸入流量保留在 /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"],  },}

• 單一檔案：取代其所在的物件
• 檔案陣列：依序深度合併（後者優先），最多可巢狀 10 層
• 同層金鑰：在引入後合併（覆寫引入的值）
• 相對路徑：相對於執行引入的檔案解析
• 路徑格式：引入路徑不得包含 Null 位元組，且解析前後都必須嚴格少於 4096 個字元
• OpenClaw 所執行的寫入：當寫入只變更一個由單一檔案引入支援的頂層區段時，例如 plugins: { $include: "./plugins.json5" }，OpenClaw 會更新該引入檔案，並保持 openclaw.json 不變
• 不支援的穿透寫入：對於根層引入、引入陣列，以及具有同層覆寫的引入，OpenClaw 所執行的寫入會採取失敗關閉，而不會將設定扁平化
• 範圍限制：$include 路徑必須解析至存放 openclaw.json 的目錄之下。若要在不同機器或使用者之間共用目錄樹，請將 OPENCLAW_INCLUDE_ROOTS 設為引入可參照之其他目錄的路徑清單（POSIX 使用 :，Windows 使用 ;）。系統會解析並重新檢查符號連結，因此即使路徑在字面上位於設定目錄內，只要其實際目標逸出所有允許的根目錄，仍會遭拒絕。
• 錯誤處理：針對檔案遺失、剖析錯誤、循環引入、無效路徑格式及長度過長提供清楚的錯誤訊息