如何配置你的 OpenClaw Gateway

手動改設定檔總是讓人頭痛，特別是當你漏掉一個逗號或打錯一個參數，導致整個服務直接掛掉的時候。那種在黑盒子裡摸索報錯訊息、反覆重啟的過程，真的會讓開發效率大打折扣。

OpenClaw 採用了嚴格的驗證機制，雖然這意味著你不能隨便亂填參數，但這也保證了你的 Gateway 只要能跑起來，配置就一定是正確的。

需要準備的東西

• 已安裝 OpenClaw
• 存取 ~/.openclaw/ 目錄的權限

快速開始

OpenClaw 預設會讀取 ~/.openclaw/openclaw.json。這是一個 JSON5 格式的檔案，代表你可以直接在裡面寫註解或是保留結尾的逗號。

如果你想在 5 分鐘內搞定，最快的方法是執行互動式指令：

openclaw onboard

或者，你也可以手動建立一個最小化的配置檔案來啟動 Gateway：

~/.openclaw/openclaw.json

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

編輯配置的四種方式

你可以根據習慣選擇適合的操作方式：

1. 互動式引導：執行 openclaw onboard 進行完整設定，或使用 openclaw configure 開啟配置精靈。
2. CLI 一行指令：
   • 讀取：openclaw config get agents.defaults.workspace
   • 設定：openclaw config set agents.defaults.heartbeat.every "2h"
   • 刪除：openclaw config unset tools.web.search.apiKey
3. Control UI：打開瀏覽器訪問 http://127.0.0.1:18789。你可以直接在 Config 分頁透過表單修改，或使用 Raw JSON 編輯器。
4. 直接編輯檔案：手動修改 ~/.openclaw/openclaw.json。Gateway 會自動監控檔案變動並即時套用（hot reload）。

疑難排解

OpenClaw 的驗證非常嚴格。如果檔案中包含未知的 key、錯誤的類型或無效的值，Gateway 會拒絕啟動。

當驗證失敗導致無法啟動時：

• 執行 openclaw doctor 查看具體的錯誤原因。
• 執行 openclaw doctor --fix（或加上 --yes）讓系統自動嘗試修復。
• 此時只有診斷指令（如 openclaw logs, openclaw health, openclaw status）可以運作。

想了解更多細節？可以詢問我們的 AI Setup Assistant。

下一步

• Configuration Reference：查看所有可用的參數欄位
• Configuration Examples：直接複製常用的配置範本

每次開發 Bot 最煩人的就是處理各種瑣碎配置，像是要怎麼同時接上 WhatsApp 和 Telegram，或是當模型 API 抽風時該怎麼自動切換。如果你也曾被這些重複的基礎建設搞到心累，這篇指南會幫你快速搞定這些常見任務。

需要準備的東西

在開始之前，請確保你已經準備好以下資訊（視你的需求而定）：

• 各通訊平台的存取憑證（如 Telegram botToken 或 WhatsApp 帳號資訊）
• LLM 供應商的 API Key（如 Anthropic 或 OpenAI）
• 如果需要執行代碼，請先安裝 Docker 並執行 scripts/sandbox-setup.sh

快速開始

如果你想在 5 分鐘內讓 Bot 跑起來，這是最短路徑：

1. 設定 Channel：在 channels.telegram 貼上你的 botToken。
2. 選擇模型：在 agents.defaults.model 指定 primary 模型。
3. 開放存取：將 dmPolicy 設定為 pairing。

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "你的_BOT_TOKEN",
      dmPolicy: "pairing"
    }
  }
}

串接通訊軟體 (WhatsApp, Telegram, Discord 等)

每個 Channel 在 channels.<provider> 下都有專屬的配置區塊。你可以根據需求參考各平台的詳細說明：

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Google Chat — channels.googlechat
• Mattermost — channels.mattermost
• MS Teams — channels.msteams

所有 Channel 都使用相同的 DM 政策模式：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // 可選：pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 僅用於 allowlist 或 open
    },
  },
}

選擇與配置模型

你可以設定主模型以及當主模型失效時的備援方案：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models 定義了模型清單，也是 /model 指令的白名單。
• 模型引用格式為 provider/model（例如 anthropic/claude-opus-4-6）。
• 關於在對話中切換模型，請參考 Models CLI；關於自動備援機制，請參考 Model Failover。
• 如果你要使用自定義或自託管的供應商，請查看 Custom providers。

控制誰可以傳訊息給 Bot

私訊（DM）存取權限是透過各個 Channel 的 dmPolicy 來控制的：

• "pairing" (預設)：陌生傳訊者會收到一次性的配對碼，需經你核准。
• "allowlist"：只有在 allowFrom 清單中的傳訊者（或已配對的存取清單）可以存取。
• "open"：允許所有傳入的私訊（需搭配 allowFrom: ["*"]）。
• "disabled"：忽略所有私訊。

如果是群組聊天，請使用 groupPolicy 加上 groupAllowFrom 或特定 Channel 的白名單。詳細細節可以參考 完整參考文件。

設定群組聊天提到（Mention）過濾

在群組中，訊息預設為**必須提到（Mention）**才會觸發。你可以針對不同 Agent 設定過濾模式：

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadata mentions：原生 @-mentions（例如 WhatsApp 的點選提到、Telegram 的 @bot 等）。
• Text patterns：在 mentionPatterns 中使用 Regex 正規表達式。
• 更多細節請見 完整參考文件。

配置 Session 與重置機制

Session 決定了對話的連續性與隔離程度：

{
  session: {
    dmScope: "per-channel-peer",  // 推薦多用戶環境使用
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope 選項包含：main (共享) | per-peer | per-channel-peer | per-account-channel-peer。
• 關於 Scope 範圍、身份連結與傳送政策，請參考 Session Management。

啟用沙箱環境 (Sandboxing)

讓你的 Agent 在隔離的 Docker 容器中執行 Session，確保安全：

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

請記得先建置 Image：scripts/sandbox-setup.sh。詳細教學請參考 Sandboxing。

設定心跳檢查 (Heartbeat)

如果你需要 Bot 定期檢查狀態或回報：

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

• every：時間間隔字串（如 30m, 2h）。設定為 0m 即可停用。
• target：last | whatsapp | telegram | discord | none。

配置 Cron Jobs

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

功能概覽與 CLI 範例請見 Cron jobs。

設定 Webhooks (Hooks)

在 Gateway 上啟用 HTTP Webhook 端點：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

關於對應選項與 Gmail 整合，請見 完整參考文件。

配置多 Agent 路由

運行多個互相隔離的 Agent，並擁有獨立的工作區與 Session：

{
  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" } },
  ],
}

詳細綁定規則請見 Multi-Agent。

使用 $include 拆分配置文件

當配置變得太長時，可以用 $include 來保持組織整潔：

~/.openclaw/openclaw.json

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

• 單一檔案：直接替換該物件。
• 檔案陣列：按順序進行深度合併（後面的會覆蓋前面的）。
• 同級 Key：合併會在 include 之後執行，因此同級的 Key 會覆蓋 include 進來的數值。
• 路徑：相對於當前文件的相對路徑。

疑難排解

在使用上述配置時，可能會遇到以下問題：

• $include 檔案找不到：請確認相對路徑是否正確，路徑是相對於發起 include 的那個檔案。
• JSON 解析錯誤：如果你使用了 $include，請確保被包含的檔案也是合法的 JSON5 格式。
• 循環引用 (Circular Includes)：系統支援最多 10 層巢狀 include，超過此限制或出現循環引用會報錯。

如果你遇到更複雜的配置問題，可以詢問 AI Setup Assistant 來獲得即時幫助。

下一步

• Session Management：深入了解對話生命週期
• Models CLI：學習如何在聊天中切換模型
• Sandboxing：建置安全的執行環境
• Multi-Agent：進階路由與多 Agent 配置

每次改完設定都要手動重啟服務，真的很煩人。特別是當你只是想微調一下模型參數或更新 API key，卻得中斷目前的連線並等待 Gateway 重新啟動，這會打斷你的開發節奏。

為了讓開發流程更順暢，Gateway 內建了自動重載功能。它會持續監控你的設定檔，並在偵測到變動時即時更新，讓你把精力放在建構應用上，而不是反覆執行重啟指令。

需要準備的東西

• ~/.openclaw/openclaw.json 設定檔
• 運行中的 Gateway 實例

快速開始

Gateway 會自動監控 ~/.openclaw/openclaw.json 並套用變更，大多數設定都不需要手動重啟。

你可以在設定檔中調整重載模式與延遲時間：

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

重載模式說明

模式	行為
hybrid (預設)	立即套用安全的變更。遇到關鍵變更時會自動重啟。
hot	僅套用安全變更。需要重啟時會記錄警告訊息，由你手動處理。
restart	只要設定檔有任何變動，無論是否安全都會直接重啟 Gateway。
off	停用檔案監控。變更要在下次手動重啟後才會生效。

哪些變更可以熱套用？

大部分的欄位都能在不中斷服務的情況下完成更新。如果你使用 hybrid 模式，那些必須重啟才能生效的變更會由系統自動幫你處理。

類別	欄位	需要重啟？
Channels	channels.*, web (WhatsApp) — 所有內建與擴充 Channel	否
Agent & models	agent, agents, models, routing	否
Automation	hooks, cron, agent.heartbeat	否
Sessions & messages	session, messages	否
Tools & media	tools, browser, skills, audio, talk	否
UI & misc	ui, logging, identity, bindings	否
Gateway server	gateway.* (port, bind, auth, tailscale, TLS, HTTP)	是
Infrastructure	discovery, canvasHost, plugins	是

[!NOTE] gateway.reload 與 gateway.remote 是例外情況 — 修改這兩個欄位不會觸發自動重啟。

如果你在設定過程遇到任何問題，可以隨時諮詢 AI Setup Assistant 獲取即時協助。

下一步

• Gateway Configuration
• Managing Agents
• WhatsApp Channel Setup
• CLI Reference

你是否遇過這種情況：想要自動化調整 Gateway 設定，卻發現還得寫腳本去讀寫實體檔案？手動改設定檔不只慢，還容易出錯，特別是當你需要根據不同環境動態調整參數時。

透過 Config RPC，你可以直接透過 API 進行更新，不需要手動觸碰設定檔。

需要準備的東西

• 正在運行的 Gateway 實例
• openclaw CLI 工具
• 既有的 Config Hash（可透過 config.get 取得）

快速開始

更新設定最快的方式是透過 config.apply 或 config.patch。這兩個方法都會在驗證並寫入設定後，自動重啟 Gateway。

1. 全量替換 (config.apply)

如果你想直接覆蓋掉目前的設定，請使用 config.apply。

[!WARNING] config.apply 會替換掉整個設定。如果你只想更新部分欄位，請改用 config.patch；若只想修改單一 Key，請使用 openclaw config set。

參數說明：

• raw (string) — 整個設定的 JSON5 字串
• baseHash (optional) — 從 config.get 取得的 Hash（若設定已存在則為必填）
• sessionKey (optional) — 重啟後用於喚醒通知的 Session Key
• note (optional) — 給重啟監控器的備註
• restartDelayMs (optional) — 重啟前的延遲毫秒數（預設為 2000）

# 先取得目前的 payload.hash
openclaw gateway call config.get --params '{}'

# 執行全量替換
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'

2. 局部更新 (config.patch)

如果你只想修改特定欄位，config.patch 會將你的異動合併到現有的設定中。它的合併邏輯如下：

• 物件 (Objects) 會遞迴合併
• 設定為 null 會刪除該 Key
• 陣列 (Arrays) 會直接替換

參數說明：

• raw (string) — 包含要修改欄位的 JSON5 字串
• baseHash (required) — 從 config.get 取得的 Hash
• sessionKey, note, restartDelayMs — 與 config.apply 相同

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

疑難排解

更新後設定不如預期？

請記住 config.apply 是「全量覆蓋」。如果你在呼叫時漏掉了某些既有配置，它們將會消失。如果你不確定目前的完整設定，建議先執行 config.get 備份，或是優先選擇 config.patch 進行局部更新。

Hash 不匹配

所有的更新操作都要求提供 baseHash。這是為了確保你在修改時，設定沒有被其他程序同時更動。如果 Hash 錯誤，請重新執行 config.get 獲取最新的 Hash。

---

如果你在設定過程中遇到任何疑問，可以詢問我們的 AI Setup Assistant 獲取即時協助。

下一步

• Config 概覽
• Gateway CLI 參考

每次在處理 API key 或是敏感的 token 時，最煩的就是要把這些資訊藏好。你可能在不同專案間切換，結果發現環境變數沒掛上去，或是 .env 檔案噴得到處都是，讓開發體驗變得很混亂。

OpenClaw 考慮到了這一點，提供了一套靈活的機制來處理這些 Environment variables，讓你的設定檔既安全又乾淨。

需要準備的東西

在開始配置之前，請確保你已經準備好：

• OpenClaw 的主設定檔
• 你的 API keys（例如 OpenRouter 或 Groq）
• 了解如何在你操作的系統中設置基礎環境變數

快速開始

OpenClaw 讀取環境變數的優先順序很直覺。它會先讀取來自父行程（parent process）的變數，接著依序尋找：

1. 當前工作目錄（CWD）下的 .env 檔案
2. 全域備援路徑 ~/.openclaw/.env

要注意的是，這兩個檔案都不會覆蓋已經存在的環境變數。

如果你想直接在設定中定義變數，可以像這樣寫在 config 裡：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

自動匯入 Shell 環境

如果你不想手動搬運變數，可以開啟這個功能。當 OpenClaw 發現預期的 key 沒有被設置時，它會執行你的 login shell 並只匯入那些缺失的 key：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

你也可以透過環境變數 OPENCLAW_LOAD_SHELL_ENV=1 來啟用它。

在設定值中使用變數替換

這是最推薦的作法。你可以在設定檔的任何字串中使用 ${VAR_NAME} 來引用環境變數：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

請記住以下規則：

• 僅匹配大寫名稱：[A-Z_][A-Z0-9_]*
• 如果變數缺失或為空，在載入時會直接拋出錯誤
• 使用 $${VAR} 可以轉義，輸出原始的字串內容
• 此功能在 $include 的檔案中同樣有效
• 支援行內替換，例如："${BASE}/v1" 會被解析為 "https://api.example.com/v1"

關於完整的優先權與來源說明，請參考 Environment 頁面。

疑難排解

變數沒有生效？

• 檢查你的變數名稱是否為全大寫。OpenClaw 嚴格遵守 [A-Z_][A-Z0-9_]* 的匹配規則。
• 確認變數是否在父行程中已經被定義，因為 .env 檔案不會覆蓋現有的環境變數。

啟動時噴錯？

• 如果你在設定檔中使用了 ${VAR_NAME} 但環境中找不到該變數，OpenClaw 為了保證系統安全會拒絕啟動。請檢查你的 .env 檔案或系統環境變數是否正確設置。

---

如果配置過程遇到困難，可以隨時詢問 AI Setup Assistant。

下一步

• Configuration Reference：完整的欄位參考手冊
• Configuration Examples：看看別人怎麼配置
• Doctor：診斷你的配置環境