OpenClaw 教程 · 小白

OpenClaw 安装与首次启动指引

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

  • OpenClaw
  • 安装
更新于 2026-08-13

一句话结论

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

适用场景

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

常见现象

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

原因解释

  • 普通安装使用的 Node 版本不受支持；截至 2026-08-13，官方推荐 Node 26，并支持 Node 22.22.3+、24.15+ 或 25.9+
  • onboarding 尚未完成，模型凭据、Gateway 或渠道配置未建立
  • 本地默认端口 18789 被占用，或 Docker 没按官方 setup 完成 onboarding 与挂载

解决步骤

  1. 普通安装先确认受支持的 Node 版本，再用官方安装器或 `npm install -g openclaw@latest`；小白默认 stable/latest，不为追新切 beta 或 main，pnpm 只在源码构建时需要
  2. 运行 `openclaw onboard --install-daemon`，按引导配置模型凭据、Gateway 和必要权限
  3. 运行 `openclaw doctor` 与 `openclaw gateway status`，修完所有阻断项
  4. 运行 `openclaw dashboard` 打开 Control UI，本地默认地址是 http://127.0.0.1:18789/
  5. 先用默认 Agent 完成一次最小对话，再按官方文档接入 channel；不要一上来暴露公网或安装大量第三方 skills

可复制命令

# 普通安装：Node 26 推荐；22.22.3+、24.15+、25.9+ 也在当前支持范围
node -v
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor
openclaw gateway status
openclaw dashboard
# Docker 是可选路径：在官方仓库根目录运行 setup，它会完成 onboarding 与 Compose 启动
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh
docker compose ps openclaw-gateway
docker compose logs -f openclaw-gateway --tail 100

仍然不行怎么办

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

小白先准备什么

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

验收标准

  • `openclaw --version`、`openclaw doctor` 和 `openclaw gateway status` 都能正常运行
  • `openclaw dashboard` 能打开本地 Control UI，并完成一条最小对话
  • Gateway 重启后状态恢复，日志没有持续崩溃或重启
  • 接入渠道前已设置访问边界，未把凭据、Control UI 或 Gateway 无保护暴露到公网

可复制命令

# 普通安装验收
node -v
openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

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

# Docker 用户只在官方仓库 setup 完成后执行
docker compose ps openclaw-gateway
docker compose logs -f openclaw-gateway --tail 100

常见误区和不适合场景

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

参考来源

相关问题

还卡着？

仅把删除凭证、客户数据和环境变量值后的必要截图、日志片段、需求说明或当前页面链接发到 zhemuy@gmail.com。