一句话结论
按官方顺序运行 status、gateway status、logs、doctor 和 channel probe；Docker 再查 `openclaw-gateway` 服务日志，根据第一条阻断错误定位。
适用场景
- OpenClaw 启动后命令行直接退出
- 面板打不开，端口连不上
- Docker 容器一启动就 exit
常见现象
- 终端报 Error: listen EADDRINUSE
- 提示 Node 版本不支持、配置无效或模块缺失
- Docker logs 一片红，最后 exit code 1
原因解释
- Gateway 本地默认端口 18789 被占用，或绑定地址与访问方式不匹配
- 普通安装的 `~/.openclaw/openclaw.json`、auth profile 或 onboarding 尚未完成；Docker 安装则可能是 setup 生成的 `.env` / Compose 配置不完整
- 权限不足：OpenClaw 状态目录不可写，或 Docker 挂载、用户和网络设置不匹配
- 运行时不受支持：当前推荐 Node 24.15+，Node 22.22.3+ 仍兼容；pnpm 只在源码构建时需要
解决步骤
- 先记录安装方式和版本，按 `openclaw status` → `openclaw gateway status` → `openclaw logs --follow` → `openclaw doctor` → `openclaw channels status --probe` 排查
- 如果是端口占用，先确认 PID 属于目标服务，再正常停止服务或向进程发送 TERM；必要时换端口
- 普通安装用 `openclaw onboard` / `openclaw configure` 修正配置与凭据；不要把凭据手工散落到不明 `.env`
- Docker 安装从官方仓库目录检查 `./scripts/docker/setup.sh` 生成的配置，并查看 `openclaw-gateway` 服务日志
- 修复后确认 Gateway 显示 `Runtime: running`、`Connectivity probe: ok`，doctor 无阻断项，channel probe 正常，并用 dashboard 做最小对话
可复制命令
openclaw --version
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
# 本地默认 Control UI / Gateway 端口
lsof -i :18789
# 先确认 PID 确实属于目标服务，再请求正常退出
kill <PID>
# 仅用于按官方 Docker setup 安装的仓库目录
docker compose ps openclaw-gateway
docker compose logs -f openclaw-gateway --tail 200
仍然不行怎么办
- 把严格脱敏后的必要日志片段、安装方式、版本和相关配置键名发到排错入口；不要发送 `openclaw.json`、auth profile、整个 `.env` 或任何凭据值
- 需要重装前先备份配置、数据目录和必要日志，并从官方文档确认恢复步骤；不要直接重置数据目录
小白先准备什么
- 确认 OpenClaw 版本和安装方式（官方安装器 / npm / 源码 / Docker）
- 普通安装确认 `openclaw onboard` 已完成；Docker 确认执行过官方 `./scripts/docker/setup.sh`
- 确认本机默认端口 18789 未被其他服务占用，或记录自己明确修改过的端口
- 准备好终端工具，能看到完整日志输出
验收标准
- `openclaw gateway status` 显示 `Runtime: running` 与 `Connectivity probe: ok`，`openclaw doctor` 没有阻断项
- `openclaw dashboard` 能打开 Control UI，本地默认地址是 http://127.0.0.1:18789/
- 默认 Agent 能发送一条最小测试消息并收到回复
- Docker 用户：`docker compose ps openclaw-gateway` 显示服务正常，日志没有持续重启
可复制排查提示词
只截取必要日志片段，并先删除 API Key、Token、Cookie、密码、客户数据和环境变量值，再用下面的模板排查：
我的 OpenClaw Gateway 启动失败。以下内容已删除 API Key、Token、Cookie、密码、客户数据和所有配置值。
必要日志片段：
```
<只粘贴第一条阻断错误及前后相关行，敏感值写成 <REDACTED>>
```
我的环境：
- 操作系统：<macOS/Linux/Windows>
- OpenClaw 版本：<openclaw --version>
- 安装方式：<官方安装器/npm/源码/Docker>
- Node 版本：<普通或源码安装时填写>
- status/gateway status/doctor 摘要：<只写状态和错误名，不粘贴凭据>
- channel probe：<正常/异常/尚未配置>
请帮我：
1. 定位具体报错原因
2. 给出最小修复步骤
3. 告诉我如何用 gateway status、doctor、channel probe 和 dashboard 验收
4. 不要要求我提供任何真实凭证或完整配置文件
常见误区
- 误区：看到报错就重装 → 应该先看报错前后的必要日志，常见原因包括配置、端口、权限和依赖问题
- 误区：所有安装都去改 `.env` → 普通安装以 `openclaw.json`、auth profiles 和 onboarding 为主，Docker setup 才会维护它自己的 `.env`
- 误区：端口被占就换一个随机端口 → 先确认 PID，改端口后同步更新配置和访问地址
- 误区：Docker 启动失败就删容器重建 → 先看 `openclaw-gateway` 日志，保留状态挂载并确认官方恢复步骤
还卡着？
仅把删除凭证、客户数据和环境变量值后的必要截图、日志片段、需求说明或当前页面链接发到 zhemuy@gmail.com。