OpenClaw Gateway 启动失败怎么办

Gateway 启动失败先按安装方式查看状态与日志，再检查版本、配置、端口、权限和 Docker 挂载，不把 .env 当作所有安装方式的通用配置中心。

内容更新 2026-09-05

先看结论

先只读看状态、有限日志和 doctor --json 的 findings，确认原因后再决定是否修配置或重启；渠道探测与模型对话分开验收。

确认现象

  • 终端报 Error: listen EADDRINUSE
  • 提示 Node 版本不支持、配置无效或模块缺失
  • Docker logs 一片红，最后 exit code 1

可能原因

  • Gateway 本地默认端口 18789 被占用，或绑定地址与访问方式不匹配
  • 普通安装的 ~/.openclaw/openclaw.json、auth profile 或 onboarding 尚未完成；Docker 安装则可能是 setup 生成的 .env / Compose 配置不完整
  • 权限不足：OpenClaw 状态目录不可写，或 Docker 挂载、用户和网络设置不匹配
  • 运行时不符合当前 Node 与 SQLite 要求：先对照安装教程和官方运行时说明；pnpm 只在源码构建时需要

按顺序排查

  1. 先记录安装方式和版本，只读执行 openclaw status、openclaw gateway status、openclaw doctor --json；检查 JSON 的 ok 与 findings，不把退出码 0 当作健康结论
  2. 仅在本机查看故障附近的有限日志，优先 openclaw logs --limit 100 --max-bytes 50000；不要把持续跟随日志命令和后续检查粘在同一块，否则后续命令不会执行
  3. 如果是端口占用，先确认 PID 属于目标服务，再正常停止服务或向进程发送 TERM；必要时换端口
  4. 普通安装用 openclaw onboard / openclaw configure 修正配置与凭据；不要把凭据手工散落到不明 .env
  5. Docker 安装从官方仓库目录检查 ./scripts/docker/setup.sh 生成的配置，并查看 openclaw-gateway 服务日志
  6. 修复后先确认 Gateway 运行与连通状态、Doctor 没有阻断项。本机状态通过后，如确需核验已配置渠道，再单独确认渠道探测范围；真实模型对话和外部消息不属于默认检查

命令与示例

# 只读诊断；检查 JSON 的 ok 和 findings，不只看退出码
openclaw --version
openclaw status
openclaw gateway status
openclaw doctor --json
# 有界日志仅在本机查看；分享前删除凭据、客户数据与私有环境信息
openclaw logs --limit 100 --max-bytes 50000
# 本地默认 Control UI / Gateway 端口
lsof -i :18789
# 先确认 PID 确实属于目标服务，再请求正常退出
kill <PID>
# 仅用于按官方 Docker setup 安装的仓库目录
docker compose ps openclaw-gateway
# 有界日志仅在本机查看
docker compose logs --tail 100 openclaw-gateway

仍未解决

  • 把严格脱敏后的必要日志片段、安装方式、版本和相关配置键名发到排错入口；不要发送 openclaw.json、auth profile、整个 .env 或任何凭据值
  • 需要重装前先备份配置、数据目录和必要日志，并从官方文档确认恢复步骤；不要直接重置数据目录

适合谁看

  • OpenClaw 启动后命令行直接退出
  • 面板打不开，端口连不上
  • Docker 容器一启动就 exit

小白先准备什么

  1. 确认 OpenClaw 版本和安装方式（官方安装器 / npm / 源码 / Docker）
  2. 普通安装确认 openclaw onboard 已完成；Docker 确认执行过官方 ./scripts/docker/setup.sh
  3. 确认本机默认端口 18789 未被其他服务占用，或记录自己明确修改过的端口
  4. 准备好终端工具，仅在本机查看故障附近日志，记录错误名和状态，不发送完整日志

验收标准

  • openclaw gateway status 显示运行与连通状态正常，openclaw doctor --json 的 findings 没有阻断项；不要只检查命令是否退出成功
  • openclaw dashboard 能打开 Control UI，本地默认地址是 http://127.0.0.1:18789/
  • 认证、渠道和真实模型调用分别记录是否验证；没有执行的部分标为未验证，不用一条本机状态代替全部验收
  • 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 日志，保留状态挂载并确认官方恢复步骤

Doctor 不一定只读

  • 只读诊断用 openclaw doctor --json 或 --lint；普通 openclaw doctor 可能复制旧配置并迁移状态，--non-interactive 只是不询问，不代表不写入。
  • --fix、--repair、--yes 属于修复，不要当作排查前置；修复可能停止并重启服务，应先备份、确认服务归属与维护窗口。
  • 2026-09-05 核对官方 Doctor 与日志文档，未操作真实 Gateway。
  • Doctor：https://docs.openclaw.ai/cli/doctor
  • 有界日志：https://docs.openclaw.ai/cli/logs