502错误表明api网关无法从clawdbot后端获取有效响应，需依次排查：一、服务进程状态；二、反向代理配置；三、网络与防火墙；四、资源限制；五、负载均衡健康检查。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您调用Clawdbot API时收到502 Bad Gateway错误，说明API网关（如Nginx、Cloudflare或负载均衡器）在尝试将请求转发至后端服务时未能获得有效响应。以下是针对服务器端的系统性排查步骤：
一、检查后端服务进程状态
502错误常源于上游服务未运行或已崩溃，需确认Clawdbot核心服务是否处于活跃监听状态。
1、执行systemctl status clawdbot-server查看服务单元运行状态。
2、若显示inactive (dead)，运行sudo systemctl start clawdbot-server启动服务。
3、使用sudo journalctl -u clawdbot-server -n 50 --no-pager检查最近50行日志中是否存在panic、段错误或端口绑定失败记录。
4、验证服务是否实际监听预期端口：运行ss -tuln | grep :8080（假设服务配置为8080端口），确认输出包含LISTEN状态及对应PID。
二、验证反向代理与上游连接配置
Nginx或Traefik等反向代理若无法正确解析上游地址或超时设置过短，将直接返回502。需逐项核对代理层配置。
1、检查Nginx配置中upstream块定义的服务器地址是否与Clawdbot服务实际监听IP和端口完全一致。
2、确认proxy_pass指令指向的upstream名称拼写无误，且未被注释或置于错误上下文（如location外）。
3、在Nginx配置的location块内添加proxy_next_upstream error timeout http_502;以启用故障转移机制。
4、临时增大超时参数：proxy_connect_timeout 60s;、proxy_send_timeout 120s;、proxy_read_timeout 120s;，避免因后端处理延迟触发502。
三、检测网络连通性与防火墙策略
即使服务进程运行正常，网络路径中的拦截或路由异常也会导致代理无法建立TCP连接，从而返回502。
1、从Nginx所在服务器执行telnet 127.0.0.1 8080（或对应上游IP端口），确认能建立TCP连接并收到欢迎响应。
2、若连接失败，检查本地防火墙：sudo ufw status verbose，确认入站规则允许Nginx监听端口，出站规则允许其访问Clawdbot端口。
3、若Clawdbot部署于Docker容器，运行docker ps -f name=clawdbot确认容器状态为Up，并使用docker exec -it clawdbot-container curl -v http://localhost:8080/health验证容器内服务可访问。
4、在宿主机执行sudo tcpdump -i any port 8080 -c 5，观察是否有SYN包到达及ACK响应，判断阻断发生在网络层还是应用层。
四、审查Clawdbot服务资源限制
当Clawdbot进程因内存耗尽被OOM Killer终止，或因文件描述符不足拒绝新连接，反向代理将收不到响应而报502。
1、检查系统级内存压力：free -h与cat /proc/meminfo | grep -i "oom\|commit"，确认CommitLimit未被突破且OOMKillCount为0。
2、查看Clawdbot进程资源使用：ps aux --sort=-%mem | head -10，定位高内存占用实例；执行cat /proc/$(pgrep -f clawdbot)/limits | grep "Max open files"确认文件描述符上限不低于65536。
3、若使用systemd托管服务，编辑/etc/systemd/system/clawdbot-server.service，在[Service]段添加LimitNOFILE=65536与MemoryLimit=2G（按实际需求调整）。
4、重启服务前执行sudo systemctl daemon-reload，再运行sudo systemctl restart clawdbot-server使资源配置生效。
五、分析上游健康检查与负载均衡状态
若Clawdbot部署于多实例集群且由负载均衡器（如HAProxy、AWS ALB）分发流量，单个节点健康检查失败会导致其被临时摘除，所有流量转向异常节点进而持续返回502。
1、登录负载均衡管理控制台，查看各Clawdbot后端实例的健康状态标记，确认是否全部显示为InService或Healthy。
2、检查健康检查配置路径（如/health）、协议（HTTP/HTTPS）、端口及期望HTTP状态码（应为200而非502）是否与Clawdbot实际暴露的健康端点一致。
3、在任一后端服务器上手动请求健康接口：curl -I http://localhost:8080/health，确认返回HTTP/1.1 200 OK且响应时间低于健康检查超时阈值（通常≤15秒）。
4、若使用Consul或Etcd做服务发现，运行curl http://localhost:8500/v1/health/service/clawdbot?passing验证通过健康检查的服务实例列表是否为空。
