OpenClaw Series

这篇文章属于 OpenClaw 系列教程

如果你还没安装、还没接 API，或者想把 OpenClaw 调成长期助手，可以直接进入专题导航页继续往下看；如果你更喜欢视频实操，也可以去 YouTube 频道。

去 YouTube 看演示 查看 OpenClaw 专题

本文按 2026 年 3 月 26 日可查到的 OpenClaw 官方 FAQ、Control UI 和 Troubleshooting 文档整理。重点不是罗列名词，而是把新手第一次安装后最容易绊住的坑，用更容易理解的方式讲清楚。

先说结论：新手最容易卡住的，不是“安装命令”，而是安装后的验证

很多人以为自己卡在“安装 OpenClaw”。

其实真正最常见的情况是：

  • 命令已经装上了
  • 但 Gateway 没正常跑起来
  • 或者 UI 连不上
  • 或者 token / 配置 / 端口 / profile 没对上

所以这篇文章你可以直接当“第一次安装后的排错清单”来看。

坑 1：Node.js 版本不对，结果一开始就不稳定

这是最基础、但也是最容易忽略的坑。

按我在 2026 年 3 月 26 日查到的官方安装文档思路，当前推荐环境已经是 Node 24，而 Node 22.16+ 仍然兼容。

所以如果你本机：

  • Node 太旧
  • 系统里装了多个 Node 版本
  • 终端实际用到的不是你以为那个版本

后面就很容易出现各种莫名其妙的问题。

先执行：

1
2
node -v
npm -v

如果版本不对，先把 Node 整理干净，再继续。

坑 2：装完就急着点 UI，但 Gateway 根本没正常启动

很多人装完第一反应就是“为什么网页打不开”。

但官方 Control UI 文档写得很清楚，浏览器界面本质上是由 Gateway 提供的。也就是说，如果 Gateway 没起来，UI 自然打不开。

建议先做这几步：

1
2
3
openclaw status
openclaw gateway status
openclaw doctor

你至少要先确认：

  • 服务是否加载
  • Runtime 是否 running
  • RPC probe 是否正常

不要还没确认状态，就先怀疑“是不是网页坏了”。

坑 3：看到 Runtime: running 就以为一切正常

这也是新手很容易误判的一点。

官方 FAQ 和 Troubleshooting 都提到过一种情况：

  • Runtime: running
  • 但 RPC probe: failed

这意味着“进程可能在”，但并不代表它真的可用。

所以你不能只盯着 running 两个字，要一起看：

  • Runtime
  • RPC probe
  • logs

最稳的排查组合是：

1
2
openclaw gateway status
openclaw logs --follow

坑 4：端口被占用了，却没意识到是“另一个实例已经在跑”

官方 FAQ 里明确提到，默认 WebSocket 监听地址通常是：

1
ws://127.0.0.1:18789

如果这个端口已经被别的 OpenClaw 实例占住，或者你自己之前已经起过一个实例，就会出现：

  • another gateway instance is already listening
  • EADDRINUSE

这时候不是“重装”就能解决，而是要先：

  1. 停掉已有实例
  2. 释放端口
  3. 或者改端口再启动

如果你还没搞清楚当前机器到底起了几个实例，先别重复启动。

坑 5：配置了非本地绑定，却没加认证

这个坑在打算远程访问时特别常见。

官方 Troubleshooting 提到，如果你把 Gateway 绑到非 loopback 地址，但没有配置 token 或 password，OpenClaw 会拒绝绑定。

你会看到类似：

  • refusing to bind gateway without auth

意思很简单：

  • 本地回环地址更宽松
  • 非本地地址必须先把认证想清楚

所以如果你准备：

  • 局域网访问
  • Tailnet 访问
  • 远程设备接入

就不要只顾着改 bind，还要先把认证配置好。

坑 6：Control UI 提示 unauthorized，就以为是账号坏了

这类报错很多新手第一反应是：

  • token 失效了
  • 服务端坏了
  • 自己装错了

但官方 Control UI 和 Troubleshooting 文档都指出，常见原因其实是：

  • token / password 填错
  • auth mode 不匹配
  • 浏览器里缓存了旧的配对信息
  • UI 连到了错误的 URL / 端口

所以你遇到 unauthorized 时，优先检查这 4 件事：

  1. 当前连的是不是对的地址
  2. token 有没有复制错
  3. Gateway 的 auth mode 和 UI 连接方式是否一致
  4. 浏览器是不是还在拿旧状态重连

坑 7：远程打开控制台时，没意识到“第一次设备接入需要配对”

这是官方文档里一个非常容易被忽略，但对新手又特别关键的点。

Control UI 页面明确提到：

  • 本地 127.0.0.1 连接通常会自动通过
  • 远程连接则可能需要显式配对批准

如果你看到：

1
disconnected (1008): pairing required

不要慌，这通常不是“坏了”，而是设备还没批准。

按官方思路，先执行：

1
2
openclaw devices list
openclaw devices approve <requestId>

尤其是你换浏览器、清缓存、换一台设备连接时，更容易踩到这个坑。

坑 8：本地能开，远程一开就连不上，结果是 HTTP / 安全上下文问题

Control UI 官方文档还提到一个新手非常容易忽略的点：

如果你是通过普通 HTTP 打开远程 UI，浏览器可能因为非安全上下文，限制相关能力，最后导致控制台连接异常。

简单理解就是：

  • 本地 127.0.0.1 更省心
  • 远程访问最好走更正规的方式

所以如果你只是第一次测试，最稳的方式还是：

1
http://127.0.0.1:18789/

先把本机跑通，再去折腾远程访问、Tailnet 或 HTTPS。

坑 9：明明改了配置，但服务用的不是你刚改的那份

官方 FAQ 里专门提到过一个典型情况：

  • Config (cli) 和 Config (service) 显示不同

这类问题很容易让人抓狂，因为你会觉得：

  • “我明明改了”
  • “怎么运行时还是旧配置”

常见原因通常是：

  • 你改的是当前 shell 下的配置
  • 但服务实际跑的是另一套 profile 或环境

所以你每次改完配置后，都要确认：

  • 你是在哪个 profile 下改的
  • 服务是用哪个 profile 安装和运行的

如果两边不一致，就会出现“我改了但没生效”的错觉。

坑 10：一上来就想接很多 API、很多功能，结果根本不知道哪一步出错

这是我最想提醒新手的一点。

很多人第一次装好 OpenClaw，就想一次性完成：

  • 安装
  • Gateway
  • UI
  • 多厂商 API
  • Docker
  • 远程访问
  • 助理配置

这样一旦出错，你根本不知道是哪一层出了问题。

最稳的顺序其实应该是：

  1. 先装好基础环境
  2. 先让 OpenClaw 正常跑起来
  3. 先接一家 API
  4. 先完成最小可用
  5. 再去做 Docker、远程访问、助理化配置

先把问题拆小，成功率会高很多。

我最建议你照着做的排错顺序

如果你是第一次安装后出问题，按这个顺序查：

  1. 先看 node -v 和 npm -v
  2. 再看 openclaw status
  3. 再看 openclaw gateway status
  4. 再跑 openclaw doctor
  5. 最后看 openclaw logs --follow

也就是说，优先级永远是：

  • 环境
  • 服务
  • 端口
  • 认证
  • 日志

不要一上来只盯着 UI。

总结

OpenClaw 新手第一次安装后最容易踩的坑，其实都集中在这几类：

  • 环境版本不对
  • Gateway 没真正跑通
  • 端口冲突
  • 认证和配对没理顺
  • 配置和 profile 不一致

只要你记住一个原则就够了：

先把“最小可用”跑通，再去做更复杂的配置。

这样你会少绕很多弯路。

OpenClaw 系列文章推荐