設定

每個頻道在 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 或 --model 覆寫。
• agents.defaults.modelPolicy.allow 是用於覆寫與模型選擇器的明確允許清單。它接受精確參照與 provider/* 萬用字元；省略它或使用 [] 即可允許任何模型。
• 模型參照使用 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.entries.*.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.entries.*.skills，即可繼承預設值。
• 設定 agents.entries.*.skills: []，即可不使用 Skills。
• 請參閱 Skills、Skills 設定，以及 設定參考資料。

停用或啟用頻道或帳號的自動健康狀態重新啟動：

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled，控制單一頻道或帳號的自動重新啟動。
• 如需作業除錯資訊，請參閱健康狀態檢查；如需所有欄位，請參閱完整參考資料。

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

{  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：DM 類型的心跳偵測目標可使用 allow（預設值）或 block
• 如需完整指南，請參閱心跳偵測。

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention：從 SQLite 工作階段資料列中清除已完成且隔離的執行工作階段（預設值為 24h；設為 false 即可停用）。
• 執行記錄會自動保留每項工作最新的 2000 筆終端資料列；遺失的資料列仍保有其 24 小時清理期限。
• 如需功能概覽與命令列介面範例，請參閱排程工作。

在閘道上啟用 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 層
• 同層金鑰：在 include 後合併（覆寫包含的值）
• 相對路徑：相對於包含它的檔案進行解析
• 路徑格式：include 路徑不得包含 Null 位元組，且在解析前後都必須嚴格少於 4096 個字元
• OpenClaw 所擁有的寫入：當一次寫入只變更一個由單一檔案 include（例如 plugins: { $include: "./plugins.json5" }）支援的頂層區段時， OpenClaw 會更新該包含檔案，並保持 openclaw.json 不變
• 不支援的透傳寫入：對於根層 include、include 陣列及具有同層覆寫的 include， OpenClaw 所擁有的寫入會採取失敗關閉，而不會 攤平設定
• 限制範圍：$include 路徑必須解析至存放 openclaw.json 的目錄之下。若要跨機器或使用者共用目錄樹，請將 OPENCLAW_INCLUDE_ROOTS 設為額外目錄的路徑清單（POSIX 上使用 :，Windows 上使用 ;）， include 可參照這些目錄。符號連結會解析並 重新檢查，因此，即使某個路徑從字面上位於設定目錄中，但其 實際目標超出所有允許的根目錄，仍會遭到拒絕。
• 錯誤處理：針對檔案遺失、剖析錯誤、循環 include、無效路徑格式及長度過長提供清楚的錯誤訊息