---
title: "配置 Gateway"
description: "配置 OpenClaw Gateway：gateway.mode、strict schema、reload mode、Config RPC、health、doctor、安全重啟和排障順序。"
verifiedAt: "2026-05-06"
---

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

> [!NOTE]
> **這一章用 14 分鐘換什麼**：你會知道 `gateway.mode=local` 為什麼重要，`hybrid` reload 代表什麼，`openclaw doctor` 和 `openclaw health` 分別看什麼，以及什麼時候該 safe restart。

## 1. Gateway 配置管的是控制面

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

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

```mermaid
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
```

> [!IMPORTANT]
> **Gateway 配置不是普通偏好設定**：埠、繫結地址、auth、TLS 和 proxy 一旦改錯，影響的是整個控制面，不只是某個 Agent 行為。

## 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`。

> [!WARNING]
> **`--allow-unconfigured` 不是生產開關**：它適合臨時 bootstrap 或開發，不會替你寫入或修復配置檔案。

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

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

| 入口 | 適合場景 | 風險 |
|------|------|------|
| `openclaw onboard` / `openclaw configure` | 第一次配置和常規調整 | 最低 |
| Control UI Config tab | 看欄位說明、表單化調整 | 中低 |
| `openclaw config get/set/unset` | 單點修改 | 中 |
| 直接編輯 JSON5 | 已經能讀懂 schema 錯誤 | 高 |

常用 CLI：

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

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

```bash
openclaw config validate
openclaw doctor
```

## 4. strict schema 怎麼用

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

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

| 層級 | 命令 | 作用 |
|------|------|------|
| 契約 | `openclaw config schema` | 檢視機器可讀配置契約 |
| 校驗 | `openclaw config validate` | 檢查當前配置是否能透過 schema |
| 修復 | `openclaw doctor` / `openclaw doctor --fix` | 定位並嘗試有限修復 |

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

> [!TIP]
> **schema 錯誤不是噪音**：它告訴你 Gateway 拒絕以半壞狀態啟動。把錯誤裡的 path 找出來，只改那個欄位。

## 5. 熱載入和重啟邊界

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

| 類別 | 例子 | 處理方式 |
|------|------|------|
| 業務執行配置 | channels、agents、models、hooks、cron、heartbeat、session、tools、skills、logging | 通常熱載入 |
| Gateway server | port、bind、auth、TLS、HTTP 入口 | 通常需要重啟 |
| 基礎設施 | discovery、canvasHost、plugins | 通常需要重啟 |
| reload / remote 自身 | `gateway.reload`、`gateway.remote` | 特殊例外 |

reload mode：

| 模式 | 行為 |
|------|------|
| `hybrid` | 預設；安全變更熱應用，關鍵變更自動重啟 |
| `hot` | 只熱應用，遇到需要重啟的欄位只記錄 warning |
| `restart` | 任何配置變化都重啟 |
| `off` | 不監聽檔案變化，下次手動重啟生效 |

> [!CAUTION]
> **儲存檔案不是驗收**：改完以後要看 `openclaw gateway status`、`openclaw health`、logs，確認當前 runtime 真的是你想要的狀態。

## 6. Config RPC 不要整份覆蓋

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

推薦思路：

```text
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 分別看什麼

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

| 命令 | 適合看什麼 |
|------|------|
| `openclaw status` | 本地摘要：Gateway reachability、mode、channel auth age、sessions 和近期活動 |
| `openclaw status --all` | 完整本地診斷，安全可貼上用於排障 |
| `openclaw status --deep` | 請求執行中的 Gateway 做 live health probe |
| `openclaw health` | 透過 WS 請求 Gateway health snapshot |
| `openclaw health --verbose` | 強制 live probe，並列印 Gateway 連線詳情 |
| `openclaw health --json` | 機器可讀健康輸出 |
| `openclaw doctor` | 修復和遷移工具，處理 stale config/state、服務、auth、workspace、plugins 等問題 |

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

> [!TIP]
> **看狀態不要只跑一個命令**：`status` 看摘要，`health` 看 live Gateway，`doctor` 看可修復問題；三者結論不一致時，先相信能指出具體 path 或服務項的輸出。

## 8. 重啟不要只會 `kill`

前臺執行：

```bash
openclaw gateway
```

安全重啟：

```bash
openclaw gateway restart --safe
```

普通重啟：

```bash
openclaw gateway restart
```

強制重啟：

```bash
openclaw gateway restart --force
```

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

> [!WARNING]
> **不要把 inline password 寫進命令歷史**：需要密碼時優先用 password file、環境變數或 SecretRef-backed 配置，不要在命令列明文傳敏感值。

## 9. Gateway 拒絕啟動時怎麼排

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

```mermaid
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？

> [!IMPORTANT]
> **過關標準**：你能用一句話說清 —— “Gateway 配置的目標不是把欄位填滿，而是讓控制面能被 schema 驗證、能安全 reload、能透過 health 和 doctor 解釋當前狀態。”

## 12. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/agents" title="Agent 配置" description="Gateway 穩定後，繼續看 workspace、skills、模型、session 和多 Agent 路由。" />
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/configuration" title="理解配置結構" description="如果還沒分清 openclaw.json 的基礎結構，先回到入門組。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/security-remote" title="遠端與安全" description="繼續核對 bind、auth、TLS、trusted proxy 和遠端訪問邊界。" />
</Cards>

## 13. 官方資料

- [Configuration](https://docs.openclaw.ai/gateway/configuration)
- [Health checks](https://docs.openclaw.ai/gateway/health)
- [Doctor](https://docs.openclaw.ai/gateway/doctor)
- [Gateway CLI](https://docs.openclaw.ai/cli/gateway)
