为什么这篇值得先看
搜索“OpenClaw 安装”的用户，大多不是想看概念，而是想把 CLI 跑起来，并确认自己没有在 API Key、PATH、Gateway 或 Dashboard 入口上埋雷。OpenClaw 官方文档现在把安装器、openclaw onboard、openclaw doctor 和 openclaw dashboard 分成多个页面，说明第一步不是单条命令，而是一条连续的初始化链路。
这篇按真实首次部署场景写：你刚拿到一台本机或轻量服务器，准备让 OpenClaw 连接模型、Gateway 和后续渠道。目标不是一次接完 WhatsApp、Telegram、Browser 和 Skills，而是留下一个可以解释、可以复查、不会泄露密钥的最小可运行环境。
先抓住这 3 个关键点
- 安装器负责把 OpenClaw CLI 放到可执行位置；
openclaw onboard才负责把模型、工作区、Gateway、渠道和健康检查串成可运行设置。 - 第一次启动前先决定密钥放在哪里。个人实验可以临时输入，团队或长期环境应优先使用环境变量、SecretRef 或外部密钥管理，不要把 API Key 放进截图和聊天记录。
- 完成安装后先跑
openclaw doctor或只读状态检查，再打开 Dashboard。界面打不开时，不要先猜 UI 问题，先确认本地命令、配置和 Gateway 可达。
安装前先做 5 项确认
- 设备环境：macOS、Linux、WSL 走 shell 安装器；Windows 走 PowerShell 安装器。不要把 Linux 命令直接粘到 PowerShell。
- 权限边界：确认你能写入用户目录、shell rc 文件或官方安装器使用的前缀路径。若公司设备限制全局 npm 安装，先看官方
install-cli.sh前缀安装方式。 - Node 与 Git：官方安装器会尝试处理 Node 和 Git，但受控环境里可能失败。安装前确认你能安装依赖，能访问 GitHub / npm，能重新打开 shell。
- 模型凭据：至少准备一个会用于首轮对话的模型 provider 凭据。没有凭据也能跑部分流程，但无法验证“能否真正回答”。
- 网络与代理：只确认当前 shell 能访问官方安装脚本和依赖源。不要为了一次安装随手修改系统代理、git remote 或全局 npm registry，尤其是团队机器。
实操步骤
- 打开官方安装器页面，确认当前平台对应的脚本和参数。macOS / Linux / WSL 多数情况下用
install.sh；想安装到本地前缀时看install-cli.sh；Windows 用install.ps1。 - 执行安装后重新打开终端，或至少让当前 shell 重新加载 PATH。不要在 “command not found” 状态下继续跑 onboarding。
- 运行
openclaw onboard，优先选择最小可运行路径：模型认证、工作区、Gateway、本地健康检查。先不要同时启用多个渠道和插件。 - 选择密钥输入方式。个人试用可以走交互式输入；非交互式或长期环境应优先让 onboard 读取环境变量或 SecretRef。不要把 API Key 写进 Markdown、shell 历史或公开 issue。
- onboard 完成后运行
openclaw doctor。如果输出里有配置、Gateway、插件或密钥警告，先处理这些基础问题，再打开 Dashboard。 - 最后运行
openclaw dashboard或进入下一篇 Dashboard 教程，确认 Control UI 入口、认证和本地 Gateway 都处于可解释状态。
配置或命令示例
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
openclaw onboard
openclaw doctor
openclaw dashboard如果你希望安装后直接进入 onboarding，官方安装器也提供相关参数；如果你在 CI、服务器或受控设备上执行，请先阅读官方安装器页面里的非交互式参数，而不是复制本地交互式命令。
推荐的首次启动顺序
| 阶段 | 你要确认什么 | 失败时先看哪里 |
|---|---|---|
| 安装器 | CLI 是否可执行，PATH 是否生效 | 官方安装器页面、PATH、Node / Git 权限 |
| onboard | 模型、工作区、Gateway 模式是否写入 | openclaw onboard 输出、密钥引用、Gateway token |
| doctor | 配置是否可读，依赖和服务是否健康 | openclaw doctor、openclaw status --all |
| dashboard | 控制界面能否打开，认证是否通过 | openclaw dashboard --no-open、Gateway token / password |
| pairing | 设备或渠道是否需要批准 | /tutorials/11-openclaw-pairing-guide |
风险边界
- 不要把
OPENCLAW_GATEWAY_TOKEN、模型 API Key 或 provider token 贴进教程笔记、终端截图、公开 issue 和团队聊天。 - 不要在不理解影响的情况下运行 reset、uninstall 或清理凭据目录。首次失败通常先查 PATH、配置、Gateway 和认证，不是先重装。
- 不要把 Control UI 或 Gateway 管理入口直接暴露到公网。后续如果要远程访问，优先阅读 Dashboard、Gateway 安全和 Tailscale / SSH 隧道相关官方说明。
- 不要为了“看起来安装成功”跳过健康检查。
openclaw doctor报出的阻断项，应该在接渠道前处理。
常见坑
- 安装脚本跑完但
openclaw找不到：先重开终端，再看 PATH，而不是重复安装。 - onboard 时为了快一直跳过密钥：后面 Dashboard、channels、Browser 或 Skills 会反复回到同一个问题。
- 把
openclaw doctor --fix当成万能修复：修复前先读输出，确认它要改的是配置规范化、服务定义还是插件状态。 - 一上来同时接 WhatsApp、Telegram、Browser：排错面会扩大到渠道、登录态、allowlist、pairing 和 Gateway，第一次部署不建议这样做。
- 安装器页面和旧教程命令不一致：以官方安装器页面为准，因为脚本域名、Node 版本和参数可能更新。
完成检查
- 终端能正常返回
openclaw命令，不再出现 command not found。 - onboard 已写出基础配置，模型凭据或 SecretRef 位置明确。
openclaw doctor不再报阻断性错误；如果仍有警告，你知道它属于安装、Gateway、密钥、插件还是渠道。openclaw dashboard能给出可打开的 Control UI 地址，或能解释为什么当前环境只能打印链接。- 你已经知道下一步该去看 Dashboard / Control UI、doctor 排错 还是 pairing 教程。
下一步怎么选
- 界面能打开但不知道看哪里：继续读 OpenClaw 首次启动：Dashboard / Control UI。
- 命令能跑但健康检查还有红色项：继续读 OpenClaw 排错清单。
- 准备接 Telegram、WhatsApp 或新设备：先读 OpenClaw pairing 教程，再接具体渠道。
为什么建议把这篇收藏起来
- 以后每次换机器、重装系统、迁移服务器或排查 “为什么新环境跑不起来”，都会回到这条安装链路。
- 安装阶段决定后续排错成本。把 PATH、密钥、onboard、doctor 和 dashboard 的顺序固定下来，比记住某个一次性命令更可靠。