一、Gateway 核心概述
Gateway 是 OpenClaw 的核心调度中枢，统一负责消息路由、会话管理、多渠道对接与接口转发，相当于整个智能体集群的总入口。
它采用单端口复用架构，Web 可视化面板、HTTP 接口、WebSocket 长连接共用同一个端口，默认端口 18789，仅需开放单端口即可满足全部功能需求。
基础启停指令
bash
运行
# 前台启动（调试常用，输出完整日志）
openclaw gateway run
启动后浏览器访问可视化管理面板：
plaintext
http://127.0.0.1:18789/
二、配置文件基础说明
1. 文件路径与格式
主配置文件固定路径：
plaintext
~/.openclaw/openclaw.json
文件采用 JSON5 格式，原生支持代码注释、末尾逗号，编写和修改比标准 JSON 更便捷。无自定义配置时，程序会自动加载内置默认参数运行。
2. 配置文件管理指令
bash
运行
# 查看当前完整运行配置
openclaw config
# 调用默认编辑器打开配置文件
openclaw configure
3. 基础配置模板
json5
{
// 网关核心配置
"gateway": {
"port": 18789,
"bind": "127.0.0.1"
},
// 第三方聊天渠道配置
"channels": {
"telegram": {
"botToken": "你的渠道密钥"
}
},
// 全局默认模型配置
"models": {
"default": "openai:gpt-4o"
}
}
三、核心配置项详解
3.1 端口配置
默认端口 18789，若该端口被其他服务占用，可手动修改：
json5
{
"gateway": {
"port": 8080
}
}
修改端口后必须重启网关，新配置方可生效。
3.2 监听地址（Bind）
用于控制网关监听的网络范围，区分本地访问与外网 / 局域网访问：
表格
| 配置值 | 作用说明 | 适用场景 |
|---|---|---|
127.0.0.1（默认） | 仅本机设备可访问 | 本地单机使用，安全性最高 |
0.0.0.0 | 监听全部网卡，局域网 / 公网均可访问 | 多设备联动、远程部署场景 |
示例（允许全网访问）：
json5
{
"gateway": {
"bind": "0.0.0.0"
}
}
⚠️ 安全强制规则：设置为
0.0.0.0对外暴露时，必须配套开启身份认证，否则网关直接启动失败，提示refusing to bind without auth。
3.3 身份认证配置（外网必开）
对外暴露网关时，提供两种主流认证方式，二选一即可。
方式 1：Token 令牌认证（推荐）
安全性更高，适合接口、多设备接入场景：
json5
{
"gateway": {
"bind": "0.0.0.0",
"auth": {
"token": "自定义高强度密钥"
}
}
}
快速生成随机安全令牌：
bash
运行
openssl rand -hex 32
方式 2：密码认证
适合网页面板登录，操作简单：
json5
{
"gateway": {
"bind": "0.0.0.0",
"auth": {
"password": "自定义登录密码"
}
}
}
3.4 热重载策略配置
控制配置修改后的生效逻辑，无需频繁手动重启服务：
表格
| 模式 | 规则说明 |
|---|---|
off | 关闭自动重载，所有修改均需手动重启 |
hot | 安全类配置即时热生效，不中断现有连接 |
restart | 任意配置修改，都自动完整重启网关 |
hybrid（默认） | 智能区分配置类型，兼顾稳定性与便捷性 |
标准配置（默认混合模式）：
json5
{
"gateway": {
"reload": {
"mode": "hybrid"
}
}
}
热重载生效范围
- 热更新（无需重启）：模型密钥、渠道令牌、智能体人设、工具权限等常规配置；
- 强制重启：监听端口、绑定地址、认证信息、插件增删等底层配置。
四、远程访问方案
默认仅本机访问，如需手机、其他电脑、外网服务器连接，推荐以下两种方案。
方案一：Tailscale 虚拟局域网（首选，安全简单）
依托虚拟组网技术实现远程访问，无需修改网关绑定地址、无需开放公网端口，全程加密。
- 网关主机、远端设备均安装 Tailscale 并登录同一账号；
- 获取网关主机的 Tailscale 虚拟 IP；
- 远端浏览器访问：
plaintext
http://100.x.x.x:18789/
方案二：SSH 端口隧道（适合有服务器权限场景）
将远程服务器网关端口映射到本地，本地直接访问。
bash
运行
# 建立端口转发隧道
ssh -N -L 18789:127.0.0.1:18789 用户名@服务器公网IP
参数释义：
-N：仅做端口转发，不登录远程终端；-L 本地端口:远程地址:远程端口：端口映射规则。
连接成功后，本地访问 http://127.0.0.1:18789/ 即可。
补充：隧道断开后需重连，可搭配
autossh实现断线自动重连。
五、可视化仪表板
网关内置 Web 管理面板，集成运维全功能：
访问地址
- 本地：
http://127.0.0.1:18789/ - 远程：通过 Tailscale / SSH 隧道对应地址访问
核心功能
- 渠道监控：查看各聊天通道连接状态、网络延迟；
- 会话管理：浏览、操作全部交互会话；
- 配置查阅：在线查看网关当前运行参数；
- 日志实时查看：快速定位运行异常。
六、网关服务全量管理指令
6.1 状态查看
bash
运行
# 查看基础运行状态
openclaw gateway status
# 深度体检：检测渠道、模型、磁盘、端口等全组件
openclaw gateway status --deep
6.2 启停与重启
bash
运行
# 重启网关
openclaw gateway restart
# 停止网关服务
openclaw gateway stop
6.3 注册系统自启服务
设置开机自动运行、进程崩溃自动重启，适配服务器长期值守：
bash
运行
openclaw gateway install
系统适配规则：Linux 使用 systemd、macOS 使用 launchd、Windows 使用系统计划任务。
6.4 全局环境诊断
故障排查优先执行，自动检测版本、配置、端口、依赖问题并给出修复建议：
bash
运行
openclaw doctor
七、常见故障排查
故障 1：端口占用 EADDRINUSE
报错：Error: listen EADDRINUSE: address already in use :::18789
原因：默认端口被其他程序占用。
bash
运行
# macOS / Linux 查找占用进程
lsof -i :18789
# Windows 查找占用进程
netstat -ano | findstr 18789
解决方式：
- 终止占用端口的进程；
- 或修改网关监听端口。
故障 2：访问鉴权失败 401 Unauthorized
报错：authentication failed
原因：Token / 密码与配置文件不一致。
解决方式：
- 打开
openclaw.json核对认证信息； - 重新设置密钥 / 密码，重启网关。
故障 3：禁止外网绑定 refusing to bind without auth
报错：对外绑定 0.0.0.0 未配置认证。
解决方式：
- 补充
auth认证配置（Token / 密码）； - 无需外网访问则将
bind改回127.0.0.1。
故障 4：网关启动失败
按顺序逐级排查：
bash
运行
# 1. 全局环境诊断
openclaw doctor
# 2. 校验配置文件语法
openclaw config
# 3. 前台 verbose 模式启动，查看详细报错日志
openclaw gateway run --verbose
# 4. 核查 Node 版本（要求 22.14+ / 24+）
node --version
故障 5：聊天渠道频繁断开
bash
运行
# 探测所有渠道连通状态
openclaw channels status --probe
# 重新登录异常渠道
openclaw channels login --channel 渠道名
# 问题持续则重启网关
openclaw gateway restart
八、总结
- 网关配置文件为
~/.openclaw/openclaw.json，JSON5 格式支持注释，修改便捷； - 默认端口
18789，单端口承载面板、接口、长连接全部功能； - 对外暴露必须开启认证，遵循安全规范，避免未授权访问；
- 远程访问优先使用 Tailscale，其次选择 SSH 隧道；
- 日常排障优先执行
openclaw doctor，快速定位绝大多数问题； - 混合热重载模式为默认最优方案，兼顾体验与稳定性。