OpenClaw 設定指南：快速配置 Gateway 與 Web 搜尋功能

每次拿到新工具，最煩的就是要翻遍文件找設定檔在哪，或是改了一個參數結果整個服務就莫名掛掉。OpenClaw 的設定系統其實很直覺，這篇幫你整理了幾個常見的坑和進階玩法，讓你少走彎路。

如果你在設定過程中遇到任何卡關，這份指南會告訴你如何正確配置你的環境。

設定檔是什麼格式？在哪裡？

OpenClaw 會讀取一個選用的 JSON5 設定檔，路徑由 $OPENCLAW_CONFIG_PATH 決定（預設為 ~/.openclaw/openclaw.json）。

如果找不到這個檔案，它會使用相對安全的預設值（包含預設的 workspace 路徑 ~/.openclaw/workspace）。

---

我設定了 gateway.bind: "lan"（或 "tailnet"）後，為什麼連不上或顯示未授權？

非 loopback 的綁定（bind）強制需要驗證。你需要設定 gateway.auth.mode 和 gateway.auth.token（或是使用環境變數 OPENCLAW_GATEWAY_TOKEN）。

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me"
    }
  }
}

---

為什麼現在連 localhost 都要 token？

設定精靈（wizard）預設會產生一個 Gateway token（即使是在 loopback 環境），所以 本地的 WS 客戶端必須通過驗證。這樣可以防止其他本地程序隨意呼叫你的 Gateway。

如果你真的想要開放 loopback，請從設定檔中移除 gateway.auth。

---

修改設定後需要重啟嗎？

Gateway 會監控設定檔並支援熱重載（hot-reload）：

• gateway.reload.mode: "hybrid"（預設）：自動套用安全的變更，遇到關鍵變更則重啟。
• 同時也支援 hot、restart 和 off 模式。

---

如何啟用網頁搜尋（和網頁抓取）？

web_fetch 不需要 API key 就能運作。但 web_search 需要 Brave Search API key。

建議做法： 執行 openclaw configure --section web 將 key 儲存在 tools.web.search.apiKey 中。

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE",
        maxResults: 5
      },
      fetch: { enabled: true }
    }
  }
}

---

config.apply 抹除了我的設定，該如何救回並避免這種情況？

config.apply 會替換掉整個設定檔。如果你只傳送了部分物件，其他所有內容都會被移除。

救回方法：

• 從備份還原。
• 如果沒有備份，請重新執行 openclaw doctor 並重新設定。

避免方法：

• 小變更請使用 openclaw config set。
• 互動式編輯請使用 openclaw configure。

---

如何在不同裝置上執行中央 Gateway 和專門的 worker？

常見的模式是 一個 Gateway 搭配多個 nodes 和 agents：

• Gateway (中央): 負責管理 channel、路由和 session。
• Nodes (裝置): 像是 Mac、iOS 或 Android 裝置作為外圍設備連接，並提供本地工具。
• Agents (workers): 獨立的腦袋或 workspace，負責特定角色。
• Sub-agents: 從主 agent 產生出來處理背景工作。
• TUI: 連接到 Gateway 並切換不同的 agent 或 session。

---

OpenClaw 的瀏覽器可以無頭（headless）執行嗎？

可以，這是一個設定選項：

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } }
    }
  }
}

預設值是 false（有頭模式）。在某些網站上，無頭模式比較容易觸發反爬蟲檢查。

---

如何使用 Brave 進行瀏覽器控制？

將 browser.executablePath 設定為你的 Brave 執行檔路徑（或任何 Chromium 系瀏覽器），然後重啟 Gateway 即可。

下一步

• 安裝指南
• CLI 命令參考

如果你在設定過程中遇到問題，可以詢問 AI Setup Assistant 獲取即時幫助。