OpenClaw 部署常见问题排查手册！我踩过的坑你别踩了
OpenClaw 部署常见问题排查手册！我踩过的坑你别踩了

大家好，我是正在实战各种 AI 项目的程序员晚枫。

😫 开篇：部署踩坑是常态，关键是快速解决

"晚枫，部署 OpenClaw 遇到 XXX 问题，怎么办？"

这半年我部署了 20+ 次 OpenClaw，踩了无数坑。今天把常见问题和解决方案整理出来，帮你节省 10 小时排查时间。

📋 问题分类速查

分类问题数量排查难度
网络问题5 个⭐⭐
Docker 问题5 个⭐⭐⭐
数据库问题4 个⭐⭐⭐
Nginx 问题4 个⭐⭐
性能问题3 个⭐⭐⭐⭐
安全问题3 个⭐⭐⭐

🌐 网络问题

问题 1：SSH 连不上服务器

症状：

1
2
3
ssh root@服务器 IP
# 卡住，无响应
# 或 Connection refused

排查步骤：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 检查网络连通性
ping 服务器 IP

# 2. 检查端口是否开放
telnet 服务器 IP 22
# 或
nc -zv 服务器 IP 22

# 3. 检查安全组
# 云平台控制台 → 安全组 → 确认 22 端口开放

# 4. 检查 SSH 服务
# 如果能通过控制台 VNC 登录：
systemctl status sshd

解决方案：

1
2
3
4
5
6
7
8
9
10
11
# 安全组没开放 → 云平台控制台添加规则

# SSH 服务没启动
systemctl start sshd
systemctl enable sshd

# SSH 端口改了 → 用指定端口连接
ssh -p 2222 root@服务器 IP

# 防火墙阻止
sudo ufw allow 22/tcp

问题 2：外网无法访问服务

症状：

1
2
浏览器访问 http://服务器 IP:8000
显示"无法访问此网站"或"连接超时"

排查步骤：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. 检查服务是否运行
netstat -tlnp | grep 8000
# 或
ss -tlnp | grep 8000

# 2. 检查安全组
# 云平台控制台 → 安全组 → 确认 8000 端口开放

# 3. 检查防火墙
sudo ufw status

# 4. 本地测试
curl http://127.0.0.1:8000

解决方案：

1
2
3
4
5
6
7
8
9
10
# 安全组没开放 → 添加 8000 端口规则

# 防火墙阻止
sudo ufw allow 8000/tcp

# 服务没启动
docker-compose up -d

# 服务绑定错了 IP
# 检查 .env 文件，确保 OPENCLAW_HOST=0.0.0.0

问题 3：DNS 解析失败

症状：

1
2
ping your-domain.com
# ping: cannot resolve your-domain.com

排查步骤：

1
2
3
4
5
6
7
8
# 1. 检查域名是否备案（国内服务器必须）

# 2. 检查 DNS 解析
nslookup your-domain.com
dig your-domain.com

# 3. 检查 DNS 服务器
cat /etc/resolv.conf

解决方案：

1
2
3
4
5
6
7
8
9
10
# 域名未解析 → 去域名服务商添加 A 记录
# A 记录：your-domain.com → 服务器 IP

# DNS 服务器问题 → 改用公共 DNS
# 阿里 DNS：223.5.5.5
# 腾讯 DNS：119.29.29.29
# Google DNS：8.8.8.8

# 本地 hosts 测试
echo "服务器 IP your-domain.com" >> /etc/hosts

问题 4：HTTPS 证书无效

症状：

1
2
浏览器显示"连接不是私密连接"
或"证书已过期"

排查步骤：

1
2
3
4
5
6
7
8
# 1. 检查证书是否有效
sudo certbot certificates

# 2. 检查证书路径
ls -la /etc/letsencrypt/live/your-domain.com/

# 3. 检查 Nginx 配置
nginx -t

解决方案：

1
2
3
4
5
6
7
8
9
# 证书过期 → 续期
sudo certbot renew

# 证书路径错了 → 修正 Nginx 配置
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

# 重启 Nginx
sudo systemctl restart nginx

问题 5：WebSocket 连接失败

症状：

1
2
前端显示"WebSocket 连接失败"
或实时功能不工作

排查步骤：

1
2
3
# 1. 检查 Nginx WebSocket 配置
# 2. 检查后端 WebSocket 服务
# 3. 浏览器控制台查看错误

解决方案：

1
2
3
4
5
6
7
8
# Nginx 添加 WebSocket 支持
location /ws {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

🐳 Docker 问题

问题 1：Docker 服务无法启动

症状：

1
2
systemctl start docker
# Job for docker.service failed

排查步骤：

1
2
3
4
5
6
7
8
# 1. 查看日志
journalctl -u docker

# 2. 检查配置
dockerd --validate

# 3. 检查存储驱动
docker info | grep "Storage Driver"

解决方案：

1
2
3
4
5
6
7
8
9
10
11
# 配置文件错误
sudo rm /etc/docker/daemon.json
sudo systemctl restart docker

# 存储空间不足
df -h
# 清理空间后重启

# 重装 Docker
sudo apt remove docker docker-engine docker.io
sudo apt install docker.io

问题 2：容器启动后立即退出

症状：

1
2
docker-compose ps
# 显示 Exit 1 或 Exit 0

排查步骤：

1
2
3
4
5
# 查看日志
docker-compose logs app

# 查看容器详情
docker inspect 容器 ID

解决方案：

1
2
3
4
5
6
# 应用错误 → 查看日志修复代码

# 配置错误 → 检查 .env 文件

# 端口冲突 → 修改端口
# .env 中修改 OPENCLAW_PORT=8001

问题 3：镜像拉取失败

症状：

1
2
3
docker pull postgres:14
# Error: pull access denied
# 或 timeout

排查步骤：

1
2
3
4
5
6
7
8
# 1. 检查网络
ping registry.hub.docker.com

# 2. 检查 Docker Hub 状态
# https://www.dockerstatus.com/

# 3. 检查代理
echo $HTTP_PROXY

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 网络问题 → 配置镜像加速器
# /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://registry.docker-cn.com"
  ]
}
sudo systemctl restart docker

# 代理问题 → 配置代理
export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

问题 4：容器间无法通信

症状：

1
2
应用容器无法连接数据库容器
显示"Connection refused"

排查步骤：

1
2
3
4
5
6
# 1. 检查是否在同一网络
docker network ls
docker inspect 容器 ID | grep NetworkMode

# 2. 测试连通性
docker exec app-container ping db-container

解决方案：

1
2
3
4
5
# 不在同一网络 → 用 docker-compose 自动创建网络

# 服务名解析失败 → 用服务名代替 IP
# DATABASE_URL=postgresql://user:pass@postgres:5432/db
# 不是 DATABASE_URL=postgresql://user:pass@127.0.0.1:5432/db

问题 5：磁盘空间不足

症状：

1
2
docker-compose up
# Error: no space left on device

排查步骤：

1
2
3
4
5
# 检查磁盘空间
df -h

# 检查 Docker 占用
docker system df

解决方案：

1
2
3
4
5
6
7
8
9
10
11
# 清理未使用的镜像
docker image prune -a

# 清理停止的容器
docker container prune

# 清理构建缓存
docker builder prune

# 清理日志
sudo journalctl --vacuum-size=100M

🗄️ 数据库问题

问题 1：数据库连接失败

症状：

1
2
应用启动失败
显示"could not connect to server"

排查步骤：

1
2
3
4
5
6
7
8
# 1. 检查数据库是否运行
docker-compose ps postgres

# 2. 检查连接字符串
cat .env | grep DATABASE_URL

# 3. 测试连接
docker-compose exec postgres psql -U openclaw -d openclaw

解决方案：

1
2
3
4
5
6
7
8
# 数据库没启动
docker-compose up -d postgres

# 连接字符串错误 → 修正 .env

# 密码错误 → 重置密码
docker-compose exec postgres psql -U postgres
ALTER USER openclaw WITH PASSWORD 'new_password';

问题 2：数据库迁移失败

症状：

1
2
应用启动时报错
显示"relation xxx does not exist"

排查步骤：

1
2
# 检查迁移状态
docker-compose exec app python manage.py showmigrations

解决方案：

1
2
3
4
5
# 执行迁移
docker-compose exec app python manage.py migrate

# 如果迁移卡住
docker-compose exec app python manage.py migrate --fake-initial

问题 3：数据库性能慢

症状：

1
2
接口响应慢
数据库 CPU 高

排查步骤：

1
2
3
4
5
6
7
8
9
# 1. 检查慢查询
docker-compose exec postgres psql -U openclaw -d openclaw
# 执行：
SELECT * FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10;

# 2. 检查连接数
docker-compose exec postgres psql -U openclaw -d openclaw
# 执行：
SELECT count(*) FROM pg_stat_activity;

解决方案：

1
2
3
4
5
6
7
8
# 添加索引
CREATE INDEX idx_xxx ON table_xxx(column_xxx);

# 优化查询
# 避免 SELECT *，只查需要的字段

# 连接池配置
# 调整 DATABASE_URL 中的连接池参数

问题 4：数据丢失

症状：

1
重启容器后数据没了

排查步骤：

1
2
3
# 检查数据卷
docker volume ls
docker inspect 容器 ID | grep Mounts

解决方案：

1
2
3
4
5
6
7
8
# 没用数据卷 → 重新部署，用持久化卷

# 数据卷挂载错了 → 修正 docker-compose.yml
volumes:
  - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

⚡ 性能问题

问题 1：CPU 使用率高

症状：

1
2
服务器 CPU 持续 90%+
接口响应慢

排查步骤：

1
2
3
4
5
6
# 查看进程
top
htop

# 查看 Docker 容器
docker stats

解决方案：

1
2
3
4
5
6
# 应用问题 → 优化代码，加缓存

# 扩容 → 增加服务器或容器副本
kubectl scale deployment openclaw-app --replicas=5

# 限流 → 配置 Nginx 限流

问题 2：内存泄漏

症状：

1
2
内存使用持续增长
最终 OOM 崩溃

排查步骤：

1
2
3
4
5
6
# 查看内存使用
free -h
docker stats

# 查看应用日志
docker-compose logs app | grep -i "memory\|leak"

解决方案：

1
2
3
4
5
6
7
8
9
10
11
# 重启容器释放内存
docker-compose restart app

# 配置内存限制
# docker-compose.yml 中添加
deploy:
  resources:
    limits:
      memory: 2G

# 修复代码中的内存泄漏

问题 3：磁盘 IO 瓶颈

症状：

1
2
数据库操作慢
磁盘 IO 等待高

排查步骤：

1
2
3
# 查看磁盘 IO
iostat -x 1
iotop

解决方案：

1
2
3
4
5
6
7
# 机械硬盘 → 换 SSD

# 优化数据库
# 添加索引，优化查询

# 分离数据盘
# 数据库用独立磁盘

🔧 运维工具推荐

监控工具

1
2
3
✓ Prometheus + Grafana（指标监控）
✓ ELK Stack（日志监控）
✓ Pingdom（可用性监控）

备份工具

1
2
3
✓ pg_dump（PostgreSQL 备份）
✓ rsync（文件备份）
✓ Restic（增量备份）

调试工具

1
2
3
✓ k9s（K8s 管理）
✓ Portainer（Docker 管理）
✓ Wireshark（网络抓包）

💬 金句总结

踩坑不可怕，可怕的是不记录。

问题排查手册，是运维的宝贵财富。

📚 相关阅读

🔗 联系方式

平台账号/链接
微信扫码加好友
微博@程序员晚枫
知乎@程序员晚枫
抖音@程序员晚枫
小红书@程序员晚枫
B 站Python 自动化办公社区

主营业务：AI 编程培训、企业内训、技术咨询

常见问题一网打尽，部署不踩坑！

🎓 AI 编程实战课程

想系统学习 AI 编程？程序员晚枫的 AI 编程实战课 帮你从零上手！