## Gateway 是什么
Gateway 是 OpenClaw 的核心进程，负责管理会话、路由消息和连接聊天渠道。你可以把它理解为智能体的"中枢神经"——所有消息都经过 Gateway 处理和分发。
Gateway 的一个巧妙设计是**单端口复用**：WebSocket 通信、HTTP API 和 Control UI 仪表板全部共享同一个端口，默认是 `18789`。这意味着你只需要开放一个端口，就能同时使用所有功能。
启动 Gateway：
```bash
openclaw gateway run
```
启动后，你可以在浏览器中访问 `http://127.0.0.1:18789/` 打开仪表板，查看渠道状态、会话列表和配置信息。
## 配置文件
Gateway 的配置文件位于：
```
~/.openclaw/openclaw.json
```
这是一个 JSON5 格式的文件，支持注释和尾逗号，编辑起来比标准 JSON 更友好。
如果你没有手动创建这个文件，OpenClaw 会使用默认配置运行。默认情况下，OpenClaw 使用内置的 Pi 二进制文件以 RPC 模式运行 Gateway，无需额外配置即可开始使用。
查看当前配置：
```bash
openclaw config
```
用编辑器打开配置文件：
```bash
openclaw configure
```
一个基本的配置文件结构如下：
```json5
{
// Gateway 配置
"gateway": {
"port": 18789,
"bind": "127.0.0.1"
},
// 渠道配置
"channels": {
"telegram": {
"botToken": "你的Token"
}
},
// 模型配置
"models": {
"default": "openai:gpt-4o"
}
}
```
## 常用配置项
### 端口设置
默认端口是 `18789`，如果与其他服务冲突，可以修改：
```json5
{
"gateway": {
"port": 8080
}
}
```
修改端口后需要重启 Gateway 才能生效。
### 绑定模式
`gateway.bind` 控制 Gateway 监听的网络接口：
| 值 | 含义 | 适用场景 |
|------|------|----------|
| `127.0.0.1`（默认） | 仅本机访问 | 本地开发、安全优先 |
| `0.0.0.0` | 所有网络接口 | 需要局域网或公网访问 |
```json5
{
"gateway": {
"bind": "0.0.0.0" // 允许外部访问
}
}
```
> **安全提醒**：将 bind 设置为 `0.0.0.0` 时，**必须同时配置认证**，否则 Gateway 会拒绝启动并报错 `refusing to bind without auth`。这是一个安全保护机制，防止你的智能体被未授权访问。
### 认证配置
当 Gateway 需要对外暴露时，必须配置认证。支持两种方式：
**Token 认证**（推荐）：
```json5
{
"gateway": {
"bind": "0.0.0.0",
"auth": {
"token": "你的安全Token"
}
}
}
```
**密码认证**：
```json5
{
"gateway": {
"bind": "0.0.0.0",
"auth": {
"password": "你的密码"
}
}
}
```
建议使用长随机字符串作为 Token，比如用 `openssl rand -hex 32` 生成。
### 热重载模式
`gateway.reload.mode` 控制配置变更后的重载行为：
| 模式 | 说明 |
|------|------|
| `off` | 不自动重载，需要手动重启 |
| `hot` | 安全变更立即生效，不中断连接 |
| `restart` | 所有变更都触发完整重启 |
| `hybrid`（默认） | 安全变更热应用，需要重启的变更自动重启 |
```json5
{
"gateway": {
"reload": {
"mode": "hybrid"
}
}
}
```
`hybrid` 模式是最推荐的选择——修改模型配置、渠道 Token 等"安全"变更会立即生效，而修改端口、绑定地址等需要重启的变更会自动触发重启。
## 远程访问
默认情况下，Gateway 只监听 `127.0.0.1`，无法从其他设备访问。如果你需要从手机、其他电脑或远程服务器访问 Gateway，有以下几种方式。
### 方式一：Tailscale / VPN（推荐）
Tailscale 是最简单安全的远程访问方案。它会为你的设备创建一个虚拟局域网，无需修改 Gateway 的绑定配置。
1. 在运行 Gateway 的机器和你的访问设备上都安装 Tailscale
2. 两台设备加入同一个 Tailscale 网络
3. 通过 Tailscale 分配的 IP 访问 Gateway
```
http://100.x.x.x:18789/
```
优点：不需要修改 Gateway 配置，不需要开放公网端口，流量加密。
### 方式二：SSH 隧道
如果你有 SSH 访问权限，可以通过 SSH 隧道将远程 Gateway 端口映射到本地：
```bash
ssh -N -L 18789:127.0.0.1:18789 user@你的服务器IP
```
这条命令会将远程服务器的 `18789` 端口映射到本地的 `18789` 端口。之后在本地浏览器访问 `http://127.0.0.1:18789/` 就能打开远程 Gateway 的仪表板。
参数说明：
- `-N`：不执行远程命令，只做端口转发
- `-L 18789:127.0.0.1:18789`：本地端口:远程地址:远程端口
> **提示**：SSH 隧道断开后需要重新连接。可以配合 `autossh` 实现自动重连。
## 仪表板
Gateway 内置了一个 Web 仪表板（Control UI），提供可视化的管理界面。
### 本地访问
Gateway 启动后，直接在浏览器打开：
```
http://127.0.0.1:18789/
```
### 远程访问
如果 Gateway 运行在远程服务器上，通过上面介绍的 Tailscale 或 SSH 隧道访问即可。
仪表板提供以下功能：
- **渠道状态**：查看各聊天渠道的连接状态和延迟
- **会话管理**：浏览和管理活跃的对话会话
- **配置查看**：查看当前 Gateway 配置
- **日志查看**：实时查看 Gateway 运行日志
## 服务管理命令
OpenClaw 提供了一组命令来管理 Gateway 服务：
### 查看状态
```bash
# 基本状态
openclaw gateway status
# 深度扫描（检查所有组件健康状态）
openclaw gateway status --deep
```
`--deep` 选项会检查渠道连接、模型可用性、磁盘空间等，适合排查问题时使用。
### 重启 Gateway
```bash
openclaw gateway restart
```
修改配置后通常需要重启。如果使用 `hybrid` 热重载模式，部分配置变更会自动生效，无需手动重启。
### 停止 Gateway
```bash
openclaw gateway stop
```
停止后所有渠道连接会断开，智能体不再响应消息。
### 安装为系统服务
如果你希望 Gateway 在系统启动时自动运行：
```bash
openclaw gateway install
```
这会将 Gateway 注册为系统服务（macOS 使用 launchd，Linux 使用 systemd），开机自动启动，崩溃自动重启。
### 诊断检查
遇到问题时，先运行诊断命令：
```bash
openclaw doctor
```
`doctor` 会检查：
- Node.js 版本是否满足要求
- 配置文件是否有语法错误
- 网络连接是否正常
- 依赖是否完整
- Gateway 端口是否可用
## 热重载详解
Gateway 的 `hybrid` 热重载模式（默认）是一个智能机制，它会根据配置变更的类型自动选择最合适的重载方式。
### 安全变更（热应用，不中断连接）
以下配置变更会立即生效，不需要重启：
- 修改模型配置（切换模型、更新 API Key）
- 修改渠道 Token
- 修改智能体人设（SOUL.md、AGENTS.md）
- 修改工具权限
### 需要重启的变更
以下配置变更需要重启 Gateway：
- 修改端口号
- 修改绑定地址
- 修改认证配置
- 安装/卸载插件
在 `hybrid` 模式下，当检测到需要重启的变更时，Gateway 会自动执行优雅重启——先完成正在处理的消息，然后重启服务。
## 常见故障排查
### 端口冲突（EADDRINUSE）
**错误信息**：`Error: listen EADDRINUSE: address already in use :::18789`
**原因**：端口 `18789` 已被其他进程占用。
**解决方法**：
```bash
# 查看占用端口的进程
lsof -i :18789 # macOS/Linux
netstat -ano | findstr 18789 # Windows
# 方法一：停止占用端口的进程
kill
# 方法二：修改 Gateway 端口
openclaw configure
# 将 gateway.port 改为其他端口，如 18790
```
### 认证失败（unauthorized）
**错误信息**：`401 Unauthorized` 或 `authentication failed`
**原因**：访问 Gateway 时提供的 Token 或密码不正确。
**解决方法**：
1. 检查配置文件中的 `gateway.auth.token` 或 `gateway.auth.password`
2. 确认客户端使用的认证信息与配置一致
3. 如果忘记了 Token，可以直接修改配置文件重新设置
```bash
openclaw configure
# 修改 auth.token 的值，然后重启
openclaw gateway restart
```
### 绑定错误（refusing to bind without auth）
**错误信息**：`refusing to bind to 0.0.0.0 without auth`
**原因**：将 `gateway.bind` 设置为 `0.0.0.0`（对外暴露）但没有配置认证。
**解决方法**：
```json5
{
"gateway": {
"bind": "0.0.0.0",
"auth": {
"token": "设置一个安全的Token" // 必须配置认证
}
}
}
```
或者如果不需要外部访问，将 bind 改回 `127.0.0.1`。
### Gateway 无法启动
如果 Gateway 启动失败，按以下步骤排查：
```bash
# 1. 运行诊断
openclaw doctor
# 2. 检查配置文件语法
openclaw config
# 3. 查看详细日志
openclaw gateway run --verbose
# 4. 检查 Node.js 版本（需要 22.14+ 或 24+）
node --version
```
### 渠道连接断开
如果某个渠道突然断开：
```bash
# 检查渠道状态
openclaw channels status --probe
# 重新登录指定渠道
openclaw channels login --channel <渠道名>
# 如果问题持续，重启 Gateway
openclaw gateway restart
```
## 小结
Gateway 是 OpenClaw 的核心，掌握它的配置和管理是进阶使用的基础。记住几个关键点：
- 配置文件在 `~/.openclaw/openclaw.json`，JSON5 格式
- 默认端口 `18789`，单端口复用所有功能
- 对外暴露时必须配置认证
- 远程访问推荐 Tailscale 或 SSH 隧道
- 遇到问题先跑 `openclaw doctor`
#OpenClawGateway #网关配置 #远程访问 #服务管理 #龙虾技能库