1. 问题概述与核心影响最近在折腾OpenClaw的时候不少朋友都踩到了同一个坑打开Web管理面板页面是加载出来了但左上角一直转圈或者直接弹出一个醒目的“Gateway Not Connected”错误。这个错误直接切断了前端界面和后端AI智能体之间的“对话通道”导致你无法发送指令、接收流式回复也无法实时监控任务执行状态整个系统相当于“半瘫”了。简单来说就是你的操作台和后台“大脑”失联了。这个问题的根源几乎百分之百出在OpenClaw Gateway这个核心组件上。它不是主API服务器通常跑在3000或8080端口而是一个独立的WebSocket服务默认运行在18789端口。你可以把它想象成一个专门的、高速的“对讲机频道”。你的浏览器Web UI、命令行工具或者任何第三方客户端都需要通过这个WebSocket连接才能和OpenClaw的后台服务进行实时、双向的通信。当这个“对讲机”频道因为各种原因无法接通时“Gateway Not Connected”的错误就出现了。这个问题在从旧版本升级、更换服务器环境、或者调整了网络配置后尤其高发。别慌它虽然烦人但排查和修复的路径非常清晰。接下来我会结合自己多次部署和排障的经验带你从原理到实操把这个问题彻底拆解清楚。2. 网关服务深度解析它为何如此关键要解决问题首先得理解问题背后的组件。很多文档把OpenClaw Gateway一笔带过但这恰恰是理解整个错误的关键。2.1 网关的双重角色与通信协议OpenClaw的架构设计采用了前后端分离和实时/非实时操作解耦的思路。这带来了更高的灵活性和性能但也增加了部署的复杂度。HTTP API服务通常端口3000/8080这是系统的“后勤部”和“档案室”。它基于传统的HTTP/HTTPS协议主要是RESTful风格处理所有非实时的、请求-响应式的操作。比如管理AI技能Skills和角色Personas的增删改查。进行系统配置的修改和读取。处理用户认证和权限管理。这些操作就像你去行政部门提交一份表格然后等待批复是一次性的交互。WebSocket Gateway服务默认端口18789这是系统的“作战指挥中心”和“实时广播站”。它基于WebSocket协议专门处理需要持续连接和双向实时数据流的场景对话交互你发送一条指令给ClaudeAI开始思考并流式地一个字一个字地返回回答。这个持续的数据流必须通过WebSocket推送。任务状态监控当一个长期任务如处理文档、执行工作流运行时后台会持续向前端发送进度百分比、当前步骤、成功/失败状态等消息。实时日志流在调试或监控时前端需要实时看到后端服务的运行日志。WebSocket连接一旦建立就会保持打开状态允许服务器在任何时刻主动向客户端推送数据这是HTTP轮询无法比拟的高效方式。所以当你看到“Gateway Not Connected”时意味着你的“指挥中心”失联了。虽然你还能访问“后勤部”API可能正常但无法进行任何实质性的“作战指挥”对话与监控。2.2 默认端口与安全考量网关默认使用18789端口这是一个相对不常见的高位端口一定程度上避免了与常见服务如80、443、22、3306的冲突。但在安全策略严格的云服务器或企业内网中所有非标准端口默认都是关闭的这就是问题最常爆发的地方。注意在生产环境中强烈不建议将18789端口直接暴露在公网。最佳实践是通过反向代理如Nginx, Caddy将WebSocket流量通过标准的443HTTPS端口转发并配置SSL证书和访问控制。我们会在后续的反向代理配置部分详细说明。3. 错误根源全排查从高发到罕见根据社区反馈和我个人的排障记录“Gateway Not Connected”的错误可以归结为四大类原因按发生概率从高到低排列如下。3.1 端口被阻断最常见的“拦路虎”这是新手和老手都最容易栽跟头的地方。你的网关进程可能运行得好好的但外部的请求根本到不了它门口。防火墙是分层的你需要像剥洋葱一样一层一层检查。云服务商安全组/防火墙第一道门这是虚拟服务器外部的第一层网络访问控制。AWS的Security Groups、阿里云的安全组、Google Cloud的Firewall Rules、Oracle Cloud的Security Lists都属于此类。新建的VPS实例默认通常只开放22SSH、80HTTP、443HTTPS等少数端口。18789端口默认是关闭的。排查命令这没有通用命令必须登录云服务商的控制台进行可视化检查。操作心得很多云厂商如Oracle Cloud除了安全组在子网层面还有“网络安全列表”Network Security List相当于两层防火墙需要同时配置非常容易遗漏。操作系统防火墙第二道门这是服务器操作系统自身的防火墙如Ubuntu/Debian系的ufwCentOS/RHEL系的firewalld或者底层的iptables。排查命令# 查看ufw状态和规则 sudo ufw status verbose # 查看firewalld开放端口 sudo firewall-cmd --list-ports # 查看iptables规则更底层 sudo iptables -L -n | grep 18789实操要点如果使用DockerDocker自身会操作iptables创建规则有时会和ufw冲突导致ufw规则不生效。这是一个经典坑点。Docker网络隔离第三道门如果你使用Docker Compose部署OpenClaw的服务运行在独立的Docker网络内部。虽然容器映射了宿主机的18789端口但Docker的网络驱动和配置也可能导致问题。排查命令检查docker-compose.yml中网关服务的端口映射配置是否准确。# 在docker-compose.yml中应有类似配置 services: openclaw: # ... 其他配置 ports: - 3000:3000 # HTTP API端口 - 18789:18789 # WebSocket Gateway端口左边是宿主机端口右边是容器内端口注意事项确保映射的宿主机端口18789没有被其他进程占用。可以使用sudo netstat -tlnp | grep 18789检查。3.2 网关令牌不匹配升级与配置的“暗礁”从OpenClaw 3.22版本开始项目规范了环境变量命名将旧的CLAWDBOT_GATEWAY_TOKEN或MOLTBOT_GATEWAY_TOKEN统一改为OPENCLAW_GATEWAY_TOKEN。如果你在升级时没有同步更新环境配置文件.env或者在不同地方服务端.env文件、客户端配置、浏览器缓存使用了不同的令牌连接就会因认证失败而被拒绝。错误表现网关进程日志中可能会出现“Invalid gateway token”或“Authentication failed”之类的错误。前端连接会瞬间失败。核心原理这个令牌相当于WebSocket连接的“接头暗号”。客户端浏览器在发起连接时会通过URL参数或请求头将这个令牌传递给网关服务。网关服务会将其与自身配置的令牌进行比对不一致则立即断开连接。排查重点确保整个系统有且仅有一个有效的OPENCLAW_GATEWAY_TOKEN定义并且所有需要连接网关的地方都使用它。3.3 网关进程未运行服务本身的“宕机”有时候问题更直接网关服务根本就没跑起来。可能的原因包括Docker容器崩溃退出查看状态为Exited。容器因内存不足OOM被系统杀死。在docker-compose.yml中网关服务没有被正确定义或启用一些非常古老的部署方式可能将网关作为独立服务。服务器重启后Docker服务或容器没有设置自动重启。在非Docker部署中进程可能因为错误或信号而终止。3.4 反向代理配置错误进阶部署的“陷阱”为了使用域名和HTTPS我们通常会在OpenClaw前面套一个Nginx或Caddy作为反向代理。如果代理配置不正确无法正确处理WebSocket协议的“升级”Upgrade请求那么所有通过代理的WebSocket连接都会失败而直接访问IP:18789端口却可能成功。关键机制WebSocket连接始于一个普通的HTTP请求但包含特殊的Upgrade: websocket和Connection: Upgrade头部。反向代理必须识别这些头部并将该连接从HTTP协议“升级”为持久的WebSocket协议而不是简单地转发HTTP请求体。典型错误在Nginx配置中如果针对/ws路径或你的网关路径的location块里缺少proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;这两行关键指令连接就会失败。4. 系统性诊断流程五步定位法当错误出现时不要盲目尝试。按照以下顺序执行检查可以高效定位问题根源。请在你的服务器上依次执行这些命令。4.1 第一步检查网关进程状态首先确认网关服务是否在运行。# 进入你的OpenClaw项目目录包含docker-compose.yml的目录 cd /path/to/your/openclaw # 查看所有相关容器的状态 docker compose ps # 或者如果你使用旧的docker-compose命令 # docker-compose ps观察输出。你应该能看到一个名为openclaw或类似的服务状态为Up。如果状态是Exited、Restarting或根本不在列表中那么问题就是服务未运行。记下容器名称用于下一步查看日志。4.2 第二步本地连通性测试在服务器内部测试是否能访问到网关服务。这排除了网络防火墙问题直接检验服务本身。# 测试本地回环地址的连接和健康端点 curl -v http://localhost:18789/health预期成功响应你会快速得到一个JSON响应{status:ok}并且HTTP状态码为200。可能的结果与含义curl: (7) Failed to connect to localhost port 18789: Connection refused含义端口上没有任何服务在监听。几乎可以确定是网关进程没有运行原因3.3。返回第一步检查容器状态。长时间无响应后超时。含义服务进程可能正在运行但已“卡死”hung无法处理请求。需要检查日志和系统资源如内存、CPU。返回其他HTTP错误码如502, 503。含义服务内部错误。需要查看网关日志。4.3 第三步外部网络连通性测试从你的本地开发机而不是服务器本身测试通过服务器公网IP能否访问到网关端口。这一步用于诊断防火墙问题。# 将 YOUR_SERVER_IP 替换为你服务器的实际公网IP地址 curl -v http://YOUR_SERVER_IP:18789/health关键对比如果第二步成功但第三步失败连接被拒绝或超时那么问题几乎肯定是防火墙或安全组规则阻止了18789端口的入站访问原因3.1。如果两步都失败则问题更可能出在服务本身原因3.3或3.2。安全提示测试完成后如果确认是防火墙问题在添加放行规则时建议将源IPSource CIDR设置为你的办公网络IP或使用VPN的IP而不是0.0.0.0/0全网开放以降低安全风险。调试完毕后再根据实际情况调整。4.4 第四步审查网关日志日志是发现真相的最终途径。查看网关容器的日志输出寻找错误信息。# 查看网关服务的最新日志如果网关是独立服务 docker compose logs --tail 100 gateway # 如果网关和主服务在同一个容器中更常见则查看主容器日志并过滤 docker compose logs --tail 100 openclaw | grep -i -E (gateway|ws|websocket|18789|token)需要关注的日志线索Gateway server started on port 18789- 服务启动成功。Invalid gateway token-令牌不匹配原因3.2。address already in use-端口冲突18789端口被其他程序占用。大量的内存错误或崩溃信息 - 可能是资源不足导致进程崩溃。没有任何关于网关启动的日志 - 可能配置错误网关未启动。4.5 第五步验证环境变量与令牌检查并确保令牌配置正确且唯一。# 在你的项目根目录下检查.env文件 cat .env | grep -i gateway_token正确的状态应该只有一行且变量名为OPENCLAW_GATEWAY_TOKEN后面跟着一个长字符串通常是32位十六进制数。错误的状态及处理有多行GATEWAY_TOKEN相关的定义 - 删除旧的行CLAWDBOT_GATEWAY_TOKEN,MOLTBOT_GATEWAY_TOKEN只保留OPENCLAW_GATEWAY_TOKEN。OPENCLAW_GATEWAY_TOKEN的值为空或明显不对 - 需要生成一个新的令牌。找不到.env文件 - 检查是否在正确目录或从示例文件复制如cp .env.example .env。5. 针对性修复方案与实操命令根据上述诊断结果执行对应的修复操作。5.1 修复方案A开放被阻断的端口如果诊断确认是防火墙问题第三步失败第二步成功你需要逐层开放端口。1. 操作系统防火墙以ufw为例# 允许18789端口的TCP流量 sudo ufw allow 18789/tcp # 重新加载ufw规则使其生效 sudo ufw reload # 再次检查状态确认规则已添加 sudo ufw status numbered2. 云平台安全组以AWS EC2为例由于各云平台控制台界面不同无法提供统一命令。通用操作流程如下登录云控制台找到你的虚拟机实例。找到关联的安全组Security Group。编辑入站规则Inbound Rules。添加一条新规则类型自定义TCP(Custom TCP)端口范围18789源Source为了调试可以先设置为0.0.0.0/0任何IP。生产环境务必后期修改为特定IP或范围。保存规则。3. 处理Docker与UFW的冲突常见于Ubuntu如果开了UFW但Docker容器端口依然无法从外部访问可能是Docker绕过了UFW规则。解决方案是修改Docker的默认网络配置。# 编辑Docker的daemon.json配置文件 sudo nano /etc/docker/daemon.json在文件中添加或修改以下内容如果文件已存在请合并iptables和userland-proxy配置{ iptables: false, userland-proxy: false }保存退出后重启Docker服务。sudo systemctl restart docker # 注意重启Docker会短暂停止所有容器。你需要重新启动你的OpenClaw栈。 cd /path/to/your/openclaw docker compose down docker compose up -d此配置让Docker不再自动管理iptables规则由UFW全权负责从而避免规则冲突。5.2 修复方案B校正网关令牌如果诊断发现令牌问题日志中有无效令牌错误或.env文件配置混乱按以下步骤修复。1. 统一并更新令牌# 进入项目目录 cd /path/to/your/openclaw # 备份当前的.env文件好习惯 cp .env .env.backup.$(date %Y%m%d) # 使用文本编辑器如nano打开.env文件 nano .env在编辑器中确保只保留一个网关令牌定义OPENCLAW_GATEWAY_TOKEN你的令牌字符串。删除或注释掉行首加#任何其他的CLAWDBOT_GATEWAY_TOKEN或MOLTBOT_GATEWAY_TOKEN行。如果你需要生成一个新的强随机令牌可以运行openssl rand -hex 32将输出的64位十六进制字符串复制作为OPENCLAW_GATEWAY_TOKEN的值。2. 重启服务并清除客户端缓存# 应用新的环境变量并重启服务 docker compose down docker compose up -d关键一步重启服务后必须清除浏览器缓存。因为旧的令牌可能被缓存在浏览器的WebSocket连接逻辑中。最简单的方法是使用浏览器的无痕/隐私模式重新打开OpenClaw管理地址。如果无痕模式正常而普通模式不正常就证实了是缓存问题。3. 更新所有客户端配置如果你除了Web UI还通过其他方式连接如自定义脚本、移动端App请务必在这些客户端的配置中也更新为新的OPENCLAW_GATEWAY_TOKEN值。5.3 修复方案C重启网关服务如果服务未运行或异常第一步或第二步检查失败尝试重启。# 进入项目目录 cd /path/to/your/openclaw # 先停止服务 docker compose down # 重新拉起服务-d参数表示后台运行 docker compose up -d # 等待几秒后查看服务状态和日志确认网关正常启动 docker compose ps docker compose logs --tail 20 openclaw如果重启后问题依旧请结合第四步的日志输出深入分析根本原因如内存不足、配置错误等。5.4 修复方案D修正反向代理配置如果你使用了Nginx、Caddy等反向代理并且直接访问IP:18789端口正常但通过域名访问出错那么问题出在代理配置上。Nginx 正确配置示例假设你的OpenClaw API运行在localhost:3000网关运行在localhost:18789你希望通过https://claw.yourdomain.com访问。server { listen 443 ssl http2; server_name claw.yourdomain.com; # SSL证书配置略 ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; # 代理主API的HTTP请求 location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 关键代理WebSocket网关连接 # 注意这里的路径 /ws 需要和OpenClaw前端配置的WebSocket路径匹配 location /ws { proxy_pass http://localhost:18789; proxy_http_version 1.1; # 必须使用HTTP/1.1 proxy_set_header Upgrade $http_upgrade; # 必须声明升级协议 proxy_set_header Connection upgrade; # 必须升级连接 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 86400s; # WebSocket连接可能很长设置超时 proxy_send_timeout 86400s; } }配置要点proxy_http_version 1.1;WebSocket需要HTTP/1.1协议。proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;这两行是灵魂它们告诉Nginx将客户端请求升级为WebSocket协议。proxy_read_timeout设置为一个非常大的值防止长时间空闲的连接被意外断开。Caddy 配置示例Caddy的配置简单得多因为它能自动检测并升级WebSocket连接。claw.yourdomain.com { # 反向代理到主API和网关 # Caddy会自动处理WebSocket升级无需特殊配置 reverse_proxy /ws localhost:18789 reverse_proxy localhost:3000 }配置修改后重载或重启反向代理服务。# Nginx 测试并重载配置 sudo nginx -t # 测试配置语法 sudo systemctl reload nginx # 平滑重载 # Caddy 重载配置 sudo systemctl reload caddy6. 高级排查与预防措施完成上述修复后大部分问题应该得以解决。如果问题依然存在或者你想更深入地排查和预防可以尝试以下方法。6.1 使用浏览器开发者工具进行网络诊断这是前端连接问题最直接的诊断窗口。在浏览器中打开OpenClaw管理页面出现错误的页面。按F12打开开发者工具。切换到“网络” (Network)标签页。刷新页面。在筛选器中选择“WS”(WebSocket)。你应该能看到一个以ws://或wss://开头的连接地址中包含你的服务器IP/域名和端口或/ws路径。点击这个WebSocket连接查看“标头”(Headers)和“响应”(Response)。状态码101 Switching Protocols成功连接已升级为WebSocket。200 OK失败。服务器返回了普通HTTP响应说明WebSocket升级未发生。通常是反向代理配置错误。403 Forbidden/401 Unauthorized认证失败很可能是令牌错误。404 Not Found路径错误网关服务路径不匹配。请求头检查请求头中是否包含Upgrade: websocket和Connection: Upgrade。6.2 预防措施与最佳实践使用Docker Compose配置明确映射端口确保你的docker-compose.yml文件清晰定义了端口映射并考虑设置容器重启策略。services: openclaw: image: your-openclaw-image restart: unless-stopped # 容器意外退出时自动重启 ports: - 3000:3000 - 18789:18789 # 明确映射网关端口 env_file: - .env # ... 其他配置为服务配置健康检查在Docker Compose中配置健康检查让Docker能监控服务状态。services: openclaw: # ... 其他配置 healthcheck: test: [CMD, curl, -f, http://localhost:3000/health] # 检查API健康 interval: 30s timeout: 10s retries: 3 start_period: 40s使用反向代理并启用HTTPS永远不要将18789管理端口直接暴露在公网。始终通过Nginx/Caddy等反向代理并通过标准HTTPS端口443访问。这不仅能统一入口、简化防火墙规则还能提供加密传输更安全。规范环境变量管理将OPENCLAW_GATEWAY_TOKEN等敏感信息存储在.env文件中并确保该文件在.gitignore中避免泄露。在团队协作中使用.env.example文件模板来同步配置项名称。升级前备份与检查在进行OpenClaw版本升级前务必备份当前的docker-compose.yml和.env文件。查阅新版本的发布说明Release Notes重点关注破坏性变更Breaking Changes比如环境变量重命名从CLAWDBOT_*改为OPENCLAW_*就是典型的例子。在测试环境先行验证升级流程。遇到“Gateway Not Connected”错误本质上是一个连接性问题。按照先内后外、先进程后网络、先简单后复杂的原则进行排查首先确认服务本身是否活着docker compose ps,curl localhost然后检查服务器内部防火墙再检查云平台安全组最后检查反向代理和客户端配置。这套组合拳下来绝大多数网关连接问题都能迎刃而解。
