一句话结论
先看日志最后 20 行，再检查端口占用和 .env，多数情况几分钟能定位。
适用场景
- OpenClaw 启动后命令行直接退出
- 面板打不开，端口连不上
- Docker 容器一启动就 exit
常见现象
- 终端报 Error: listen EADDRINUSE
- 提示 Cannot find module 或 .env not found
- Docker logs 一片红，最后 exit code 1
原因解释
- 端口被占用：常见 3000、8080、5173、8000
- .env 缺少必需变量：API_KEY、BASE_URL、TELEGRAM_TOKEN 等
- 权限不足：日志目录不可写或 Docker 没挂卷
- 依赖没装齐：Node 版本太低或 pnpm 没装
解决步骤
- 看日志最后一段，定位 Error / Cannot / EADDR 这类关键字
- 如果是端口占用，换端口或杀掉占用进程
- 如果是 .env 报错，对照官方示例补齐变量再重启
- 如果是权限报错，给 logs/ data/ 目录加可写权限
- 重启网关，看到 listening on 端口字样就算正常
可复制命令
lsof -i :8080
kill -9 <PID>
docker logs -f openclaw-gateway --tail 200
仍然不行怎么办
- 把日志和脱敏后的 .env 发到排错入口
- 或者重置数据目录、重新跑一次安装脚本
小白先准备什么
- 确认 OpenClaw 版本和安装方式（Docker 还是源码）
- 确认 .env 文件里至少有 API_KEY、BASE_URL、PORT 三个变量
- 确认本机端口没被其他服务占用（常见 3000、8080）
- 准备好终端工具，能看到完整日志输出
验收标准
- 终端输出 listening on <端口号>，没有红色报错
- 浏览器访问 http://localhost:<端口号> 能看到面板
- 面板里能正常新建 Agent 并发送测试消息
- Docker 用户：docker ps 显示容器状态为 Up
可复制排查提示词
把下面这段和你的报错日志一起发给 AI，让它帮你定位问题：
我的 OpenClaw Gateway 启动失败，以下是最后 30 行日志：
```
<粘贴你的日志>
```
我的环境：
- 操作系统：<Mac/Linux/Windows>
- 安装方式：<Docker/源码>
- Node 版本：<node -v 的输出>
请帮我：
1. 定位具体报错原因
2. 给出修复命令
3. 告诉我修复后怎么验证成功
常见误区
- 误区：看到报错就重装 → 应该先看日志最后 20 行，90% 的问题是配置问题
- 误区：.env 里的值加了引号或空格 → API Key 和 URL 不要加引号，不要有多余空格
- 误区：端口被占就换一个随机端口 → 换完记得同步改 .env 和面板访问地址
- 误区：Docker 启动失败就删容器重建 → 先 docker logs 看原因，可能只是挂载目录权限问题
还卡着？
可以把截图、日志、需求单或当前页面链接发到 zhemuy@gmail.com。