openclaw部署后出现502 bad gateway，说明nginx已接收请求但上游后端未正常响应；需依次排查后端进程存活状态、nginx proxy_pass配置准确性、端口占用与防火墙拦截、http协议兼容性及超时设置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw部署完成后访问页面显示502 Bad Gateway，说明Nginx已成功接收请求，但无法从上游服务（如Python后端或Node.js进程）获得有效HTTP响应——这通常不是网络不通，而是上游服务未启动、崩溃、端口冲突或协议不匹配。
确认OpenClaw后端进程是否存活
登录服务器，执行：
ps aux | grep -i "openclaw\|uvicorn\|fastapi"
若输出中没有包含 uvicorn、gunicorn 或 python main.py 的活跃进程，说明后端根本没跑起来。此时不要急着改Nginx配置，先解决服务本身。
进入OpenClaw项目根目录，手动启动后端：
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
观察终端是否打印 Uvicorn running on http://127.0.0.1:8000 并持续等待请求。如果立即退出并报错 ModuleNotFoundError 或 RuntimeError，说明依赖未装全或配置文件缺失——【必须先修复此错误，否则Nginx永远收不到响应】
检查Nginx upstream是否指向正确地址和端口
打开Nginx站点配置文件，常见路径为 /etc/nginx/conf.d/openclaw.conf 或 /etc/nginx/sites-enabled/openclaw：
定位 location / { ... } 块内的 proxy_pass 指令，确认其值为：
proxy_pass http://127.0.0.1:8000;
⚠️ 注意：不能写成 proxy_pass http://localhost:8000; ——某些容器或SELinux环境下 localhost 解析可能失败；也不能漏掉末尾的分号；更不能写成 proxy_pass http://127.0.0.1:8000（缺斜杠），Nginx会将其视为域名而非路径重写。
验证配置语法：
sudo nginx -t
若提示 successful，执行重载：
sudo nginx -s reload
本次更新实现飞书插件 npm 独立分发，新增 Ollama 本地模型配置及 openclaw 命令别名。引入 SQLite 持久化队列，支持断点续传。全面集成飞书、钉钉、企业微信及 QQ 官方渠道，优化阿里云百炼模型选择。修复多 Agent 路由、定时任务校验及配对授权等关键问题，提升系统稳定性与兼容性。
排查端口占用与防火墙拦截
方法一：检测8000端口是否被占
lsof -i :8000 或 netstat -tuln | grep :8000
若发现其他进程（如另一个uvicorn实例、java或node）正监听该端口，用 kill -9 [PID] 强制终止，再重启OpenClaw后端。
方法二：绕过Nginx直连后端测试
curl -v http://127.0.0.1:8000/health
如果返回 200 OK 和 JSON {"status":"healthy"}，证明后端工作正常，问题锁定在Nginx代理层；如果超时或连接拒绝，说明后端未监听或绑定地址不对（例如代码里写了 host='0.0.0.0' 才能被Nginx访问）。
方法三：检查防火墙是否放行本地回环通信
sudo iptables -L -n | grep 8000
若规则中出现 DROP 或 REJECT 且目标为 127.0.0.1:8000，则需插入 ACCEPT 规则：
sudo iptables -I INPUT -s 127.0.0.1 -d 127.0.0.1 -p tcp --dport 8000 -j ACCEPT
验证Nginx与后端的协议兼容性
第一步：确认OpenClaw后端启用的是HTTP/1.1 —— 若代码中强制启用了HTTP/2（如 uvicorn --http http2），而Nginx未开启 http_v2 模块或未配置 ssl_protocols，就会导致502。
第二步：检查Nginx error.log 中是否有类似 upstream prematurely closed connection while reading response header from upstream 的报错：
sudo tail -30 /var/log/nginx/error.log
第三步：临时在Nginx配置中添加调试头，确认请求确实抵达后端：
在 location 块内加入：
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
然后重启后端，在其日志中查看是否收到带这些Header的请求。没收到=请求根本没发出去；收到但无响应=后端处理卡死或超时。
第四步：调高超时阈值，避免因后端初始化慢触发502：
在 upstream 或 location 块中加入：
proxy_connect_timeout 60;
proxy_send_timeout 120;
proxy_read_timeout 120;
