---
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="/docs/openclaw/official/01-gateway-runtime/agents" title="Agent 配置" description="Gateway 稳定后，继续看 workspace、skills、模型、session 和多 Agent 路由。" />
  <Card href="/docs/openclaw/official/00-getting-started/configuration" title="理解配置结构" description="如果还没分清 openclaw.json 的基础结构，先回到入门组。" />
  <Card href="/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)
