第5章 - 故障排除

嗨，朋友！最后一章我们来聊聊故障排除。遇到问题不要慌，大多数问题都有简单的解决方案。这一章我把常见问题和解决方法都整理好了，遇到问题来这里查就行。

🩺 第一步：运行诊断

不管遇到什么问题，先运行 OpenClaw 的内置诊断工具：

openclaw doctor

openclaw doctor 会自动检查：

Node.js 版本
Gateway 状态
配置文件有效性
API Key 可用性
DM 策略安全性
已知的常见问题

提示

大多数问题 openclaw doctor 都能发现并给出修复建议。养成遇到问题先跑 doctor 的习惯！

🔧 常见问题与解决方案

问题1：Gateway 无法启动

症状：运行 openclaw gateway 后报错或无响应。

检查步骤：

# 检查端口是否被占用
ss -tlnp | grep 18789

# 如果端口被占用，找到占用的进程
lsof -i :18789

# 杀掉占用端口的进程
kill -9 <PID>

# 检查 Node.js 版本
node --version
# 必须是 v22+

# 检查配置文件语法
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 如果报错，说明 JSON 格式有误

常见原因：

端口 18789 被其他进程占用
Node.js 版本低于 22
openclaw.json 配置文件 JSON 语法错误
已有一个 Gateway 实例在运行

问题2：Gateway 启动后自动停止

症状：Gateway 启动几秒后就退出了。

# 查看详细错误日志
openclaw gateway --verbose

# 或查看 systemd 日志
journalctl --user -u openclaw-gateway --no-pager -n 50

常见原因：

API Key 无效或过期
网络无法连接到 AI 模型 API
内存不足

解决方案：

# 检查 API Key
grep -i "key\|token" ~/.openclaw/openclaw.json

# 测试网络连接
curl -I https://api.anthropic.com/
curl -I https://api.openai.com/

# 检查内存
free -h

问题3：SSH 断开后 Gateway 停止

症状：SSH 连接断开后，Gateway 就不运行了。

解决方案：

# 核心命令：启用 linger
sudo loginctl enable-linger $(whoami)

# 确认 systemd 服务已启用
systemctl --user enable openclaw-gateway

# 验证
loginctl show-user $(whoami) | grep Linger
# 应该显示：Linger=yes

重点

这是 Linux 上最常见的问题！enable-linger 是让 systemd 用户服务在注销后继续运行的关键。

问题4：聊天渠道无法连接

症状：配置了 Telegram/Discord 等渠道，但 Bot 没有响应。

检查步骤：

# 查看渠道连接日志
journalctl --user -u openclaw-gateway --no-pager | grep -i "telegram\|discord\|channel"

# 检查配置文件中的 Token 是否正确
cat ~/.openclaw/openclaw.json | grep -A5 "channels"

常见原因：

Bot Token 不正确或已过期
渠道配置中 enabled 不是 true
网络问题，无法连接到聊天平台 API
Telegram Bot 需要先发送 /start

解决方案：

# 重新生成 Token（Telegram）
# 在 Telegram 中找 @BotFather，发送 /token 获取新 Token

# 重新配置
nano ~/.openclaw/openclaw.json

# 重启 Gateway
systemctl --user restart openclaw-gateway

问题5：浏览器工具不工作

症状：AI 说无法打开浏览器或浏览器报错。

这在无桌面环境的 Linux 服务器上很常见。

# 安装 Chromium 和必要依赖
sudo apt install -y chromium-browser

# 如果是无桌面环境，安装额外依赖
sudo apt install -y \
  libgbm1 \
  libnss3 \
  libatk-bridge2.0-0 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  libpango-1.0-0 \
  libcairo2 \
  libasound2 \
  libxshmfence1 \
  libglu1-mesa

参考

浏览器在 Linux 上的详细排障指南：Browser Linux Troubleshooting

问题6：内存不足

症状：系统变慢、进程被 OOM Killer 杀死。

# 查看内存使用
free -h

# 查看 OpenClaw 进程的内存占用
ps aux | grep openclaw

# 查看是否被 OOM 杀死
dmesg | grep -i "oom\|killed"

解决方案：

# 添加 swap 空间（如果没有）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

问题7：Gateway Lock 冲突

症状：提示 Gateway 已经在运行或锁文件冲突。

# 检查是否有残留进程
ps aux | grep openclaw

# 如果有残留进程，杀掉
pkill -f "openclaw gateway"

# 清理锁文件（如果确认没有其他实例在运行）
rm -f ~/.openclaw/gateway.lock

# 重新启动
systemctl --user restart openclaw-gateway

📊 日志分析

查看不同级别的日志

# 所有日志
journalctl --user -u openclaw-gateway --no-pager

# 只看错误
journalctl --user -u openclaw-gateway --priority=err --no-pager

# 最近 1 小时的日志
journalctl --user -u openclaw-gateway --since "1 hour ago" --no-pager

# 实时跟踪
journalctl --user -u openclaw-gateway -f

日志关键词

关键词	含义
`error`	错误，需要关注
`warn`	警告，可能有问题
`connected`	渠道连接成功
`disconnected`	渠道断开连接
`timeout`	超时，通常是网络问题
`auth`	认证相关
`rate limit`	API 请求频率限制

🔄 重置和恢复

重置配置

# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 重新运行引导向导
openclaw onboard

完全重装

# 停止服务
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway

# 卸载
npm uninstall -g openclaw

# 备份数据（可选）
cp -r ~/.openclaw ~/openclaw-backup

# 清理
rm -rf ~/.openclaw

# 重新安装
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

📞 获取帮助

如果以上方法都无法解决你的问题：

官方文档：docs.openclaw.ai
Discord 社区：discord.gg/clawd
GitHub Issues：github.com/openclaw/openclaw/issues
故障排除指南：Troubleshooting

在求助时，请提供以下信息：

# 生成诊断信息
echo "=== OpenClaw 版本 ===" && openclaw --version
echo "=== Node.js 版本 ===" && node --version
echo "=== 系统信息 ===" && cat /etc/os-release | head -3
echo "=== Doctor 输出 ===" && openclaw doctor
echo "=== 最近错误日志 ===" && journalctl --user -u openclaw-gateway --priority=err --no-pager -n 20

📋 故障排除速查表

问题	快速解决
Gateway 无法启动	检查端口占用、Node 版本、配置语法
SSH 断开后停止	`sudo loginctl enable-linger $(whoami)`
渠道无响应	检查 Token、重启 Gateway
浏览器不工作	安装 chromium 和依赖
内存不足	添加 swap 空间
锁文件冲突	杀掉残留进程，清理锁文件
API 报错	检查 Key 和网络连接
更新后异常	运行 `openclaw doctor`

💪 练习题

openclaw doctor 能检查哪些问题？
SSH 断开后 Gateway 停止运行的根本原因是什么？如何解决？
在无桌面环境的 Linux 服务器上使用浏览器工具需要安装什么？

答案提示

Node.js 版本、Gateway 状态、配置有效性、API Key、DM 安全策略等
因为 systemd 用户服务默认在用户注销后停止。解决方法是 sudo loginctl enable-linger $(whoami)
需要安装 chromium-browser 以及 libgbm1、libnss3 等图形相关依赖库

🎉 恭喜你完成了全部教程！

现在你已经掌握了在 Linux 上使用 OpenClaw 的全部知识。从安装配置到日常使用，从安全加固到自动化工作流，你已经是一个 OpenClaw 高手了。

如果这个教程对你有帮助，欢迎分享给更多朋友！

由编程指南提供