跳转到内容
最近更新

文档 / 排错指南

OpenClaw 排错指南：网关、Telegram 与浏览器中继问题

集中处理 OpenClaw 安装、网关令牌、Telegram 通道、浏览器中继、Docker 与运行时故障。

安装与环境

安装前

安装脚本下载失败（网络/代理）

展开

现象: 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

为什么有效: 通过代理转发请求，确保安装脚本和依赖可访问。

验证方式: 重新执行安装命令，能正常下载。

截图:

安装脚本下载失败（网络/代理） screenshot

Docker 服务未运行

展开

现象: Docker 命令报错或容器启动即退出。

原因: Docker 服务未启动或未启用。

解决方案

命令

sudo systemctl status docker
sudo systemctl enable --now docker

配置差异

- restart: "no"
+ restart: unless-stopped

为什么有效: 确保 Docker 服务可用，并让容器重启后自动拉起。

验证方式: 重启后 docker ps 仍有容器运行。

截图:

Docker 服务未运行 screenshot

数据目录权限不足

展开

现象: 写入时报 Permission denied 或 EACCES。

原因: 数据目录归属不正确或挂载路径不一致。

解决方案

命令

sudo chown -R $USER:$USER ~/.openclaw
ls -la ~/.openclaw

配置差异

- ./openclaw-data:/root/.openclaw
+ ~/.openclaw:/root/.openclaw

为什么有效: 使用用户目录持久化，避免权限问题。

验证方式: 重启后能正常写入数据。

截图:

数据目录权限不足 screenshot

初始化与启动

安装中

onboarding 卡住或通道无响应

展开

现象: 向导卡住或通道消息不回复。

原因: API Key 无效或网络被拦截。

解决方案

命令

openclaw config get | head -n 20
openclaw gateway restart

配置差异

+ ANTHROPIC_API_KEY=sk-REPLACE_ME

为什么有效: 确保模型提供商鉴权信息正确。

验证方式: openclaw health 返回 OK，通道能回复。

截图:

onboarding 卡住或通道无响应 screenshot

Control UI 端口冲突

展开

现象: SSH 隧道/Control UI 报 EADDRINUSE。

原因: 18789 端口被占用。

解决方案

命令

sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 18789

配置差异

- "18789:18789"
+ "18790:18789"

为什么有效: 把宿主机端口映射改为新端口避免冲突。

验证方式: 新端口可以正常打开 UI。

截图:

Control UI 端口冲突 screenshot

改了配置没生效

展开

现象: 修改配置后行为没有变化。

原因: 编辑了错误的配置文件或未重启网关。

解决方案

命令

openclaw config get
openclaw gateway restart

配置差异

+ OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json

为什么有效: 强制网关读取正确的配置路径。

验证方式: 重启后配置值与修改一致。

截图:

改了配置没生效 screenshot

通道与访问控制

首次安装成功之后

Telegram 机器人能启动但不回复

展开

现象: Telegram 里 /start 正常，但发送普通消息没有响应。

原因: Bot Token 填错、网关没有重启，或服务器无法访问 Telegram 接口。

解决方案

命令

openclaw config get channels.telegram.botToken
openclaw gateway restart
curl -I https://api.telegram.org

配置差异

- channels.telegram.enabled: false
+ channels.telegram.enabled: true
+ channels.telegram.botToken: "YOUR_TELEGRAM_BOT_TOKEN"

为什么有效: 这一步可以同时确认 Telegram 通道已启用、Bot Token 已写入，以及网关已经加载新配置并具备基础网络访问能力。

验证方式: 重新在 Telegram 里执行 /start，并确认发送普通文本消息后能收到回复。

截图:

Telegram 机器人能启动但不回复 screenshot

Gateway token 无效、缺失或被拒绝

展开

现象: 调用网关时出现 unauthorized、forbidden 或 token missing 之类的报错。

原因: 运行时 token 没有设置、设置不一致，或者代理和客户端拿到的是旧值。

解决方案

命令

openclaw config get gateway.token
openclaw gateway restart
printenv | grep -i OPENCLAW

配置差异

- gateway.token: ""
+ gateway.token: "REPLACE_WITH_A_STRONG_SECRET"

为什么有效: 确保运行时配置、客户端请求和代理层使用的是同一个 gateway token，能避免鉴权失败和旧配置残留。

验证方式: 确认 health 检查和需要鉴权的网关调用仅在正确 token 存在时才成功。

截图:

Gateway token 无效、缺失或被拒绝 screenshot

Browser relay 无法连接或请求经常超时

展开

现象: 需要浏览器能力的流程无法启动，或 browser relay 相关步骤频繁超时。

原因: browser relay 未启用、目标服务不可达，或宿主机无法解析 relay 地址。

解决方案

命令

openclaw config get browserRelay
curl -I http://127.0.0.1:3000 || true
openclaw gateway restart

配置差异

- browserRelay.enabled: false
+ browserRelay.enabled: true
+ browserRelay.baseUrl: "http://127.0.0.1:3000"

为什么有效: browser relay 依赖一个可访问的中继服务和一致的运行时配置。重启网关可以强制重新加载 browser relay 设置。

验证方式: 运行一个依赖浏览器能力的技能或工作流，确认不再出现 relay timeout 类错误。

截图:

Browser relay 无法连接或请求经常超时 screenshot

运行稳定性

运行后

重启后数据丢失

展开

现象: 重启后设置丢失或历史为空。

原因: 未挂载持久化目录。

解决方案

命令

ls -la ~/.openclaw
docker compose ps

配置差异

- volumes:
-   - ./openclaw-data:/root/.openclaw
+ volumes:
+   - ~/.openclaw:/root/.openclaw

为什么有效: 把状态写到宿主机，重启后仍可读取。

验证方式: 重启后设置与历史仍存在。

截图:

重启后数据丢失 screenshot

内存不足 / OOM

展开

现象: 高负载下进程被杀。

原因: VPS 配置不足。

解决方案

命令

free -m
journalctl -k | grep -i oom

配置差异

- plan: entry
+ plan: standard

为什么有效: 升级内存或配置能避免 OOM。

验证方式: 高峰期不再出现 OOM。

截图:

内存不足 / OOM screenshot

继续查看