OpenClaw 安装教程：安装、Dashboard 首次启动与 doctor 排错

安装前先做 5 项确认

1. 设备环境：macOS、Linux、WSL 走 shell 安装器；Windows 走 PowerShell 安装器。不要把 Linux 命令直接粘到 PowerShell。
2. 权限边界：确认你能写入用户目录、shell rc 文件或官方安装器使用的前缀路径。若公司设备限制全局 npm 安装，先看官方 install-cli.sh 前缀安装方式。
3. Node 与 Git：官方安装器会尝试处理 Node 和 Git，但受控环境里可能失败。安装前确认你能安装依赖，能访问 GitHub / npm，能重新打开 shell。
4. 模型凭据：至少准备一个会用于首轮对话的模型 provider 凭据。没有凭据也能跑部分流程，但无法验证“能否真正回答”。
5. 网络与代理：只确认当前 shell 能访问官方安装脚本和依赖源。不要为了一次安装随手修改系统代理、git remote 或全局 npm registry，尤其是团队机器。

实操步骤

1. 打开官方安装器页面，确认当前平台对应的脚本和参数。macOS / Linux / WSL 多数情况下用 install.sh；想安装到本地前缀时看 install-cli.sh；Windows 用 install.ps1。
2. 执行安装后重新打开终端，或至少让当前 shell 重新加载 PATH。不要在 “command not found” 状态下继续跑 onboarding。
3. 运行 openclaw onboard，优先选择最小可运行路径：模型认证、工作区、Gateway、本地健康检查。先不要同时启用多个渠道和插件。
4. 选择密钥输入方式。个人试用可以走交互式输入；非交互式或长期环境应优先让 onboard 读取环境变量或 SecretRef。不要把 API Key 写进 Markdown、shell 历史或公开 issue。
5. onboard 完成后运行 openclaw doctor。如果输出里有配置、Gateway、插件或密钥警告，先处理这些基础问题，再打开 Dashboard。
6. 最后运行 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/06-openclaw-telegram-setup/

风险边界

• 不要把 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 首次启动

三个名字怎么分工

名称	你实际会怎么用	首次启动看什么
openclaw dashboard	CLI 命令，打开或打印控制界面 URL	URL 是否生成、是否不泄露 SecretRef token、是否能打开浏览器
Web Dashboard	Gateway 在浏览器里提供的仪表盘入口	Gateway URL、认证方式、unauthorized / 1008 提示
Control UI	浏览器里的管理界面	聊天、渠道、会话、配置、设备配对、Cron、Skills、exec 审批

如果你只记一条：第一次上手从 openclaw dashboard 进入 Control UI；Control UI 报错时，再回到 doctor、status 和 Gateway 健康检查。

实操步骤

1. 先在本机运行 openclaw dashboard。如果你在无头服务器上操作，可以使用 openclaw dashboard --no-open 让它只打印 URL 和安全提示。
2. 打开本地地址。官方文档里本地 Gateway 常见入口是 http://127.0.0.1:18789/ 或 http://localhost:18789/；启用 TLS 时要注意 https:// 和 wss://。
3. 如果页面提示共享密钥认证，把配置的 Gateway token 或 password 填到 Control UI 设置中。SecretRef 管理的 token 不应该出现在终端日志里。
4. 先看 Gateway Access / Overview 类入口，再看渠道、会话、节点、Skills、Cron 和配置。第一次不要急着改配置，先建立“哪里显示状态、哪里发起动作、哪里审批风险操作”的地图。
5. 如果出现 unauthorized、1008、需要配对或 scope 不匹配，先记录提示，再回到 doctor / status / devices 或 pairing 教程排查。

配置或命令示例

openclaw dashboard
openclaw dashboard --no-open
openclaw status
openclaw health --verbose

首次启动 10 分钟检查表

• URL 是否来自当前 Gateway。不要在多个本地端口、远程隧道和旧书签之间来回切。
• 认证方式是否清楚：token、password、Tailscale 身份、trusted proxy，还是设备 token。
• 控制界面是否要求设备配对。新浏览器、清除站点数据、切换浏览器配置文件都可能触发重新配对。
• 是否有未知设备、未知配对请求或异常 scope 升级请求。不要为了“先进去”批准看不懂的请求。
• 是否有渠道或插件仍在旧状态。还没接 Telegram / WhatsApp 时，界面里不应该出现你无法解释的账号状态。
• 是否有 exec 审批、配置变更或高风险动作入口。团队环境下，这些入口需要 owner 和审批策略配合。

看到 1008 / unauthorized 怎么判断

现象	常见含义	先做什么
页面打不开	Gateway 未启动、端口不对、隧道不通	openclaw status、openclaw gateway、确认 18789 端口
unauthorized	共享密钥、password 或设备 token 不匹配	检查 Gateway auth 来源，不要先轮换全部密钥
1008 需要配对	新设备或新浏览器需要批准	openclaw devices list 后按 requestId 批准
scope mismatch	设备被识别，但请求了更宽权限	明确批准新 scope，或撤销后重新配对
SecretRef token 无法注入	当前 shell 解析不到外部 secret	导出所需环境变量，或按官方 SecretRef 路径修复

风险边界

• Control UI 是管理界面，不是公开站点。它涉及聊天、配置、节点、Cron、Skills 和 exec 审批，公网暴露会把管理面变成攻击面。
• gateway.controlUi.allowedOrigins: ["*"] 这类宽松来源策略不适合真实环境。除非是严格受控的本地测试，否则应按官方文档显式配置来源。
• URL 片段里的 token 只适合引导当前会话；不要把带 token 的 URL 发给别人或贴进文档。
• 如果你正在调远程 Gateway，优先使用 Tailscale Serve、SSH 隧道或受控反向代理，不要直接把 loopback 以外的未受保护端口暴露出去。

常见坑

• 把所有问题都归因到 Control UI，结果忽略了 Gateway 根本没起起来。
• 把 openclaw dashboard --no-open 打印的 URL 和旧书签混用，最后连到了另一个环境。
• 看到 unauthorized 就轮换 token，结果真正问题是 scope mismatch 或设备配对没批准。
• 第一次启动就接入多个渠道，界面信息过多，反而不知道哪个报错是主因。
• 只盯着聊天窗口，不看 Gateway Access、devices、channels、sessions 和 exec approvals。

OpenClaw 排错清单

先把问题分到一层

现象	可能层级	第一条检查命令
openclaw 命令找不到	安装 / PATH	重新打开 shell，检查 PATH
onboard 后无法启动	配置 / Gateway mode	openclaw doctor
Dashboard 页面打不开	Gateway / 端口 / 隧道	openclaw status
Control UI unauthorized	Gateway auth / token / password	openclaw dashboard --no-open
1008 需要配对	devices / scope	openclaw devices list
Telegram / WhatsApp 不回应	channel / allowlist / session	openclaw status --deep
Browser 登录流失败	浏览器会话 / 扩展 / 登录态	先看 Browser 专题，再看 logs

实操步骤

1. 先执行只读检查：openclaw doctor、openclaw status。如果你准备把输出贴给别人，先确认没有 token、cookie、账号标识或私密路径。
2. 如果 Gateway 不可达，先不要调渠道。确认 gateway.mode、端口、auth、服务是否运行，以及本地入口 127.0.0.1:18789 是否符合你的环境。
3. 如果 Dashboard / Control UI 打不开或 unauthorized，用 openclaw dashboard --no-open 获取当前命令路径给出的安全 URL 和认证提示，再排查 token、password、SecretRef 或设备 token。
4. 如果看到 1008、需要配对或 scope mismatch，先走 devices / pairing 路径，不要先轮换 Gateway token。
5. Gateway 和界面稳定后，再排查渠道：Telegram 看 bot token、dmPolicy、allowlist 和群聊策略；WhatsApp 看登录态、session、selfChatMode 和发送者是否被允许。
6. 如果问题进入 Browser、Skills、Cron 或插件层，先把基础 Gateway 健康状态截图或日志留好，再进入对应专题页继续排查。

配置或命令示例

openclaw doctor
openclaw doctor --fix
openclaw status
openclaw status --all
openclaw health --verbose
openclaw dashboard

什么时候用修复命令

doctor --fix 适合处理官方已知的可修复状态，例如配置规范化、缺失插件恢复、服务定义提示和部分旧配置迁移。但它不是“把所有首次失败变好”的按钮。运行前建议做三件事：

1. 先跑一次不带 --fix 的 openclaw doctor，读清楚它发现了什么。
2. 备份关键配置和你要复盘的日志。官方 doctor 修复路径会写备份，但你仍然应该知道自己改过什么。
3. 一次只修一层。先修配置，再看 Gateway；Gateway 稳定后，再修 pairing 或渠道。

在 Nix、受控服务器、团队共享环境或 SecretRef 管理 token 的环境里，更要先读官方限制。某些修复路径在不可变配置或无头环境里会被跳过，交互式提示也可能不会出现。

Gateway 不可达的排查顺序

1. 先确认是没启动、端口不对、认证失败，还是网络路径不通。不要把所有 Gateway 问题都归因于模型 Key。
2. 本地开发优先检查 openclaw gateway 或 openclaw gateway run 是否能前台启动。端口冲突时再考虑 --force，不要默认强杀。
3. 看 openclaw status 或 openclaw health --verbose。前者适合本地摘要，后者适合向正在运行的 Gateway 请求健康快照。
4. 如果是远程 Gateway，检查 SSH 隧道、Tailscale、TLS / WSS、allowed origins 和显式凭据。设置了 --url 时，CLI 通常不会自动回退到本地配置或环境凭据。

Dashboard / Control UI 常见失败

• 页面加载失败：Gateway 未运行、端口不是 18789、basePath 不一致，或远程隧道没有建立。
• unauthorized：显式 token、password、设备 token 或 SecretRef 解析失败。先确认当前命令路径能拿到正确凭据。
• 1008 需要配对：新浏览器或新设备连接时，Gateway 可能要求一次性批准。用 openclaw devices list 找 requestId，再审批。
• scope mismatch：设备被识别，但这次请求更高权限。应该明确审批新 scope，或撤销设备后重走配对，而不是盲目重置所有认证。

渠道问题不要提前排查

只有 Gateway 和 Control UI 基本健康后，才值得调 Telegram、WhatsApp、Browser 或 Webhook。否则你看到的“消息没回”“二维码过期”“Browser 卡住”可能只是 Gateway 没连上。

渠道层排查可以这样拆：

• Telegram：bot token 是否有效，sender 是否在 allowlist，群聊是否需要 @mention，Privacy Mode / 管理员权限是否符合预期。
• WhatsApp：session 是否还在，扫码是否完成，selfChatMode 是否符合场景，发送者和群聊规则是否匹配。
• Browser：登录态是否在目标浏览器配置文件里，验证码是否需要人工介入，任务是否依赖已有 session。
• Webhook / hooks：入口 URL、鉴权、重试、幂等和日志要单独看，不要和消息渠道混在一起排。

可共享的最小故障报告

当你需要让别人帮忙看问题，尽量只提供这些高信号信息：

• 你在第几步失败：install、onboard、doctor、gateway、dashboard、pairing、channel。
• openclaw doctor 或 openclaw status --all 的脱敏摘要。
• 你看到的错误类型：unauthorized、1008、scope mismatch、端口占用、token drift、channel logged out。
• 你已经尝试过的一步修复，且每次只改了一项。

不要贴 API Key、Gateway token、cookie、完整聊天记录、联系人标识、Webhook body 或未脱敏日志。官方 Gateway health / diagnostics 文档也强调诊断输出应避免泄露消息文本和秘密值。

常见坑

• 同时改 token、channel、browser、plugin，最后不知道是哪一项真的修好了问题。
• 看见 pairing 失败就重装，结果把原本还能用的 session 一起清掉。
• 忽略 Control UI 里的 auth / devices / sessions，只看终端最后一行错误。
• 把模型 API Key 错误和 Gateway 不可达混为一谈，导致排错方向完全错位。
• 在服务仍有活跃工作时强制重启 Gateway，造成任务、队列或回复投递中断。