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 #网关配置 #远程访问 #服务管理 #龙虾技能库