OpenClaw 安装与首次启动指引

优先用官方安装器或 npm 安装并完成 onboarding；Docker 是可选的隔离部署路径，必须走官方 setup，而不是照搬通用 Compose 命令。

内容更新 2026-09-05

先看结论

普通用户先安装最新版并运行 openclaw onboard --install-daemon；验收看 doctor、Gateway 状态和 dashboard，Docker 只按官方 setup 单独走。

操作步骤

  1. 普通安装先确认受支持的 Node 版本，再用官方安装器或 npm install -g openclaw@latest；小白默认 stable/latest，不为追新切 beta 或 main，pnpm 只在源码构建时需要
  2. 确认允许写入本机配置并安装后台服务后，运行 openclaw onboard --install-daemon；凭据由你在本机官方引导中填写，不发送给聊天助手
  3. 运行只读的 openclaw doctor --json 与 openclaw gateway status，查看 findings；发现阻断项先确认修复方案，不直接附加 --fix
  4. 运行 openclaw dashboard 打开 Control UI，本地默认地址是 http://127.0.0.1:18789/
  5. 安装验收先止于状态和本地 UI；确认模型费用与权限后才发送一条虚构测试消息。接 channel 是独立步骤，不要一上来暴露公网或安装大量第三方 skills

命令与示例

# 先确认本机版本与官方运行时要求
node -v

# 以下会安装软件、写配置并安装后台服务，确认后再执行
npm install -g openclaw@latest
openclaw onboard --install-daemon
# 安装完成后：只读诊断。JSON 命令退出成功不等于健康，检查 ok 与 findings
openclaw doctor --json
openclaw gateway status
# 本机打开 UI；不要分享带认证信息的 dashboard 链接
openclaw dashboard
# 可选 Docker 路线，不与普通安装同时执行
# setup 会构建镜像、写配置并启动服务，先审阅官方流程；本地构建至少需要 6 GB RAM
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh
docker compose ps openclaw-gateway
# 原始日志仅在本机查看，分享前严格脱敏
docker compose logs --tail 100 openclaw-gateway

小白先准备什么

  1. 确认本机系统：macOS / Windows / Linux，并选择普通安装或 Docker，先不要两种方式同时跑。
  2. 普通安装准备受支持的 Node；Docker 准备 Docker Engine / Desktop 与 Compose v2。
  3. 准备一个符合所在地、用途和平台条款的模型服务账号与专用 Key。
  4. 确认默认端口 18789 没被占用；VPS 或公网主机先阅读官方网络暴露与安全加固说明。

验收标准

  • 版本可读取，openclaw doctor --json 的 ok 与 findings 无阻断项，Gateway 状态正常；JSON 命令退出成功不等于通过
  • openclaw dashboard 能打开本地 Control UI；模型对话在确认费用后另测，未测就明确记录未验证
  • Gateway 状态正常且没有持续崩溃；首次安装不要求额外重启正在运行的服务来验收
  • 接入渠道前已设置访问边界，未把凭据、Control UI 或 Gateway 无保护暴露到公网

可复制命令

# 普通安装诊断，不调用模型
node -v
openclaw --version
openclaw doctor --json
openclaw gateway status

# macOS/Linux 端口检查：本地默认 18789
lsof -i :18789

# Docker 用户只在官方仓库 setup 完成后执行
docker compose ps openclaw-gateway
# 原始日志仅在本机查看
docker compose logs --tail 100 openclaw-gateway

常见误区和不适合场景

  • 误区：普通安装和 Docker 同时跑 → 可能出现端口、状态目录和服务归属冲突，先选一种
  • 误区：所有安装都手改 .env → 普通安装以 onboarding、openclaw.json 和 auth profiles 为主
  • 误区：用 sudo 运行所有命令 → 权限混乱，后续文件读写会出问题
  • 不适合：只想快速试一下模型效果（直接用 curl 或 Playground 更快）
  • 不适合：准备把 Control UI 或 Gateway 直接暴露公网但还没理解访问控制、反向代理和防火墙

参考来源

适合谁看

  • 刚拿到 OpenClaw，不确定哪种安装方式适合自己
  • 已经装过但首次启动卡在白屏
  • 想为后续的 Gateway、channel、memory 和 skills 准备好基础环境

需要解决的问题

  • 面板打不开 / 一直转圈
  • 命令行报 Node 版本不支持、openclaw 不在 PATH 或 Docker setup 失败
  • 完成安装但找不到登录入口

先理解这些

  • 运行时不符合官方 Node 与 SQLite 要求；2026-09-05 核对时官方推荐 Node 26，支持 22.22.3+、24.15+ 或 25.9+，不支持 Node 23。发行版自带 Node 还要留意其链接的 SQLite，后续以官方安装页为准
  • onboarding 尚未完成，模型凭据、Gateway 或渠道配置未建立
  • 本地默认端口 18789 被占用，或 Docker 没按官方 setup 完成 onboarding 与挂载

遇到困难时

  • 面板始终打不开就先看 OpenClaw Gateway 启动失败怎么办
  • 如果是模型或中转凭据问题，先按所用协议从帮助中心复制对应最小测试，不要假设所有入口都支持 /v1/models