文档 / 排错指南
OpenClaw 排错指南
按部署阶段分组的常见问题，包含命令、配置差异与验证方式。
安装与环境
安装前
安装脚本下载失败（网络/代理）
现象: curl 或 npm 下载失败/超时。
原因: 网络受限或未设置代理。
解决方案
命令
curl -I https://openclaw.bot/install.sh export https_proxy=http://127.0.0.1:7890 export http_proxy=http://127.0.0.1:7890
配置差异
+ https_proxy=http://127.0.0.1:7890 + http_proxy=http://127.0.0.1:7890
为什么有效: 通过代理转发请求，确保安装脚本和依赖可访问。
验证方式: 重新执行安装命令，能正常下载。
截图: /images/troubleshooting/zh/network.png
Docker 服务未运行
现象: Docker 命令报错或容器启动即退出。
原因: Docker 服务未启动或未启用。
解决方案
命令
sudo systemctl status docker sudo systemctl enable --now docker
配置差异
- restart: "no" + restart: unless-stopped
为什么有效: 确保 Docker 服务可用，并让容器重启后自动拉起。
验证方式: 重启后 docker ps 仍有容器运行。
截图: /images/troubleshooting/zh/docker-start.png
数据目录权限不足
现象: 写入时报 Permission denied 或 EACCES。
原因: 数据目录归属不正确或挂载路径不一致。
解决方案
命令
sudo chown -R $USER:$USER ~/.openclaw ls -la ~/.openclaw
配置差异
- ./openclaw-data:/root/.openclaw + ~/.openclaw:/root/.openclaw
为什么有效: 使用用户目录持久化，避免权限问题。
验证方式: 重启后能正常写入数据。
截图: /images/troubleshooting/zh/permission.png
初始化与启动
安装中
onboarding 卡住或通道无响应
现象: 向导卡住或通道消息不回复。
原因: API Key 无效或网络被拦截。
解决方案
命令
openclaw config get | head -n 20 openclaw gateway restart
配置差异
+ ANTHROPIC_API_KEY=sk-REPLACE_ME
为什么有效: 确保模型提供商鉴权信息正确。
验证方式: openclaw health 返回 OK，通道能回复。
截图: /images/troubleshooting/zh/config.png
Control UI 端口冲突
现象: SSH 隧道/Control UI 报 EADDRINUSE。
原因: 18789 端口被占用。
解决方案
命令
sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 18789
配置差异
- "18789:18789" + "18790:18789"
为什么有效: 把宿主机端口映射改为新端口避免冲突。
验证方式: 新端口可以正常打开 UI。
截图: /images/troubleshooting/zh/port-in-use.png
改了配置没生效
现象: 修改配置后行为没有变化。
原因: 编辑了错误的配置文件或未重启网关。
解决方案
命令
openclaw config get openclaw gateway restart
配置差异
+ OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
为什么有效: 强制网关读取正确的配置路径。
验证方式: 重启后配置值与修改一致。
截图: /images/troubleshooting/zh/config.png
运行稳定性
运行后
重启后数据丢失
现象: 重启后设置丢失或历史为空。
原因: 未挂载持久化目录。
解决方案
命令
ls -la ~/.openclaw docker compose ps
配置差异
- volumes: - - ./openclaw-data:/root/.openclaw + volumes: + - ~/.openclaw:/root/.openclaw
为什么有效: 把状态写到宿主机，重启后仍可读取。
验证方式: 重启后设置与历史仍存在。
截图: /images/troubleshooting/zh/data.png
内存不足 / OOM
现象: 高负载下进程被杀。
原因: VPS 配置不足。
解决方案
命令
free -m journalctl -k | grep -i oom
配置差异
- plan: entry + plan: standard
为什么有效: 升级内存或配置能避免 OOM。
验证方式: 高峰期不再出现 OOM。
截图: /images/troubleshooting/zh/memory.png