配置 Gateway

這一章繼續看 Gateway 自身怎麼配置。前面“理解配置結構”解決的是新手認知；這一篇解決執行時問題：Gateway 為什麼拒絕猜你的模式、哪些配置能熱載入、程式化改配置為什麼要 patch、啟動失敗先看什麼。

1. Gateway 配置管的是控制面

openclaw.json 既管 Agent，也管 Gateway。Gateway 相關配置尤其敏感，因為它決定：

• WebSocket 監聽在哪個地址和埠。
• Control UI、Canvas、A2UI 是否可訪問。
• 認證、TLS、Tailscale、trusted proxy 怎麼工作。
• reload mode 如何應用配置變化。
• health、diagnostics、logs 怎麼暴露狀態。
• 遠端 CLI 和節點怎麼連線。

flowchart TD
    Config["openclaw.json"]
    Mode["gateway.mode"]
    Network["bind / port / auth / TLS"]
    Reload["reload mode"]
    Control["Control UI / Canvas / A2UI"]
    Health["health / diagnostics"]
    Remote["remote target"]

    Config --> Mode
    Config --> Network
    Config --> Reload
    Config --> Control
    Config --> Health
    Config --> Remote

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Network fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Reload fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

2. gateway.mode=local 是啟動護欄

官方 Gateway CLI 現在有一個關鍵護欄：預設情況下，Gateway 拒絕在 ~/.openclaw/openclaw.json 裡缺少 gateway.mode=local 時啟動。openclaw onboard --mode local 和 openclaw setup 應該寫入這個欄位。

如果配置檔案存在但缺少 gateway.mode，Gateway 會把它看成可疑損壞配置，而不是替你猜成 local。

這解決的是一個真實風險：配置被 clobber（被錯誤覆蓋）後，系統不能帶著半壞狀態繼續啟動。第一次配置用 openclaw onboard --mode local 或 setup；臨時開發啟動才考慮 --allow-unconfigured；發現 gateway.mode 缺失時當作損壞配置修復，不要手動猜；遠端模式要明確配置 gateway.mode 和 gateway.remote。

3. 修改 Gateway 配置的四個入口

優先順序按“新手安全”排序：

常用 CLI：

openclaw config get gateway.mode
openclaw config set gateway.reload.mode hybrid
openclaw config validate

直接編輯適合小範圍、可回復的改動。編輯後立刻跑：

openclaw config validate
openclaw doctor

4. strict schema 怎麼用

OpenClaw 用 schema 校驗完整配置。配置不合法時，Gateway 不應該繼續執行。

你可以把排障命令分成三層：

配置介面、Agent 自動化或指令碼不要靠猜欄位；應該以 config.schema.lookup 和完整 reference 為準。

5. 熱載入和重啟邊界

Gateway 會監聽配置檔案。預設 reload mode 是 hybrid：能熱載入的直接應用，需要重啟的自動重啟。

reload mode：

6. Config RPC 不要整份覆蓋

程式化更新配置時，優先走“查 schema、拿當前配置和 hash、做 patch”的流程。只有真的要替換完整配置時，才用 full apply。

推薦思路：

config.schema.lookup
  ↓
config.get + hash
  ↓
config.patch
  ↓
validate / health / status

為什麼不整份覆蓋？因為 Gateway 配置裡可能有你沒有載入到的 channel、plugin、auth、remote、diagnostics、session 配置。全量覆蓋最容易誤刪其它配置。

官方也對控制面寫 RPC 做了速率限制，避免壞指令碼高頻刷配置。自動化指令碼不要迴圈反覆全量覆蓋 openclaw.json。

7. health、status、doctor 分別看什麼

這些命令經常被混用，實際職責不同：

health 主要判斷 Gateway 當前能不能回答和渠道是否健康；doctor 更像修理工，負責配置遷移、狀態修復、服務審計和修復建議。

8. 重啟不要只會 kill

前臺執行：

openclaw gateway

安全重啟：

openclaw gateway restart --safe

普通重啟：

openclaw gateway restart

強制重啟：

openclaw gateway restart --force

--safe 會讓執行中的 Gateway 先檢查活躍工作、佇列、回覆投遞、embedded runs 和 task runs。如果有阻塞，會報告並等待活躍工作 drain。--force 只在你明確接受立即中斷時使用。

9. Gateway 拒絕啟動時怎麼排

遇到 Gateway 拒絕啟動，不要先刪配置檔案。按這個順序：

flowchart TD
    Fail["Gateway 啟動失敗"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Mode["檢查 gateway.mode"]
    Port["檢查埠 / auth / TLS"]
    Fix["只修一個欄位"]
    Start["重新啟動或 safe restart"]

    Fail --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Mode
    Mode --> Port
    Port --> Fix
    Fix --> Start

    style Fail fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Fix fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Start fill:#dcfce7,stroke:#22c55e,stroke-width:2px

先確認是 schema 錯誤、模式缺失、埠衝突、auth 問題、TLS 問題、外掛問題，還是熱載入邊界。doctor --fix 只適合修復明確可修的常見問題，不能替你決定安全策略。

10. 新手常見坑

• 直接編輯後不驗證：Gateway 可能拒絕啟動，或者熱載入失敗。
• 把 unknown key 當註釋：strict schema 會拒絕未知欄位。
• 用 symlink 管預設配置：OpenClaw 原子寫可能替換路徑。
• 不區分熱載入和重啟欄位：auth、TLS、埠等變化要確認重啟。
• 程式化更新時全量覆蓋：容易丟失其它配置。
• 把 token 寫死在配置裡再提交：應該用 env、SecretRef 或本機憑據管理。
• Gateway 啟動失敗就刪除配置：這會丟掉線索，應該先 doctor 和 validate。
• 用 restart --force 處理所有問題：可能中斷正在執行的任務。

11. 本章自檢

1. 為什麼缺少 gateway.mode=local 時 Gateway 不應該替你猜？
2. health、status、doctor 的職責差異是什麼？
3. 程式化改配置為什麼優先 patch，而不是 full apply？

12. 接下來去哪

13. 官方資料

• Configuration
• Health checks
• Doctor
• Gateway CLI