我是如何手动安装 OpenClaw，并顺手踩完一堆坑的

夜航猩
0 阅读5分钟

一开始我以为是 1Panel 不够听话。 后来发现，不是它不听话，是我和 OpenClaw、OpenResty、WebSocket、HTTPS、Pairing 之间需要先互相认识一下。

前言

最近想把 OpenClaw 部署到自己的服务器上，并通过域名来访问。 一开始图省事，直接用了 1Panel 自带的 OpenClaw 安装方式。

结果嘛，过程非常丰富，知识点非常密集，心情也非常立体。

比如我先后见过这些提示：

  • 空白页
  • 502 Bad Gateway
  • origin not allowed
  • control ui requires device identity
  • gateway token mismatch
  • pairing required

可以说，OpenClaw 把“你真的理解这套链路了吗”这件事，考得明明白白。

最终我放弃了 1Panel 内置安装，改成了 手动安装 OpenClaw + 1Panel OpenResty 反向代理，成功跑通。

这篇文章就把整个过程整理一下，给后面的人少踩几个坑。

一、为什么放弃 1Panel 内置安装

最开始我是直接在 1Panel 里安装 OpenClaw。

表面上看：

  • 应用是启动的
  • 域名也配了
  • HTTPS 证书也配了
  • 反向代理也配了

但访问的时候，页面不是空白，就是各种奇怪报错。

典型问题

1. 页面白屏

明明站点能打开，但就是一片空白。

最后发现原因不是“前端坏了”，而是：

  • 页面端口和网关端口不是一回事
  • Host 头不对时，OpenClaw 返回内容异常
  • 反代路径、协议、Host 校验都可能影响结果

2. WebSocket 连不上

页面打开后，点击连接提示断开。

后面发现这不是单纯的 WebSocket 问题，而是：

  • 网关端口没搞清
  • token 不对
  • origin 不允许
  • 浏览器不是安全上下文
  • 设备还没完成 pairing

3. 配置越来越绕

最头疼的不是某一个错误，而是：

1Panel 自带安装把页面、网关、反代、token、设备授权这些东西拧在一起了。

修一个地方，看起来像好了，结果下一个坑正在前面挥手。

于是我决定：

与其继续在“自动安装出来的半透明状态”里猜，不如直接手动装，自己把链路看明白。

二、最终方案：手动安装 OpenClaw

我的最终方案是：

  • OpenClaw 手动安装
  • OpenClaw 本机监听 18788
  • 1Panel 的 OpenResty 负责 HTTPS 反向代理
  • 域名统一访问
  • 浏览器通过 WSS 连接

这样结构非常清晰：

浏览器
  -> https://claw.xxx.com
  -> OpenResty
  -> http://127.0.0.1:18788
  -> OpenClaw

三、安装环境

我的环境大致如下：

  • Ubuntu
  • 1Panel
  • OpenResty（通过 1Panel 管理）
  • 域名已解析
  • 已有 HTTPS 证书

四、安装前先清理旧环境

如果你之前已经折腾过 1Panel 自带的 OpenClaw，建议先清理旧东西。

不然很容易出现：

  • 旧配置残留
  • 旧 token 干扰
  • 旧设备身份缓存
  • 旧反代规则仍在生效

建议清理内容

1. 删除 1Panel 里旧的 OpenClaw 应用

直接删掉，别留恋。

2. 删除旧的网站反代配置

包括之前给 OpenClaw 配的反代站点。

3. 清浏览器缓存

最好直接用无痕模式重新访问，防止旧 token / pairing 信息干扰。

4. 备份或清理旧配置目录

如果你之前装过，可以看看：

~/.openclaw

想彻底一点的话：

mv ~/.openclaw ~/.openclaw.bak.$(date +%F-%H%M%S)

五、正式安装 OpenClaw

1. 执行安装脚本

一开始我直接执行：

curl -fsSL https://openclaw.ai/install.sh | bash

我遇到的第一个坑

早些时候我碰到过：

curl: option --retry-connrefused: is unknown

这通常说明系统里的 curl 版本或者实现有问题。

不过后面我重新执行后，安装脚本是正常工作的。

2. 安装过程中的几个关键选项

安装过程中会有一些交互式选项，我这里记录一下我是怎么选的。

Gateway bind

我选的是：

LAN (0.0.0.0)

原因很简单：

  • 后面要通过域名访问
  • 需要让 OpenResty 能访问到网关
  • 不只是本机调试

Gateway port

我最终使用的是：

18788

Gateway auth

选：

Token

Tailscale exposure

选：

Off

因为我这里不是走 Tailscale 暴露。

Gateway token 提供方式

选：

Generate/store plaintext token

原因：

  • 简单
  • 先跑通再说
  • SecretRef 对我当前场景属于“把简单事情搞复杂”

Search provider

先选：

Skip for now

先把服务跑起来，搜索能力后面再配。

Hooks

先全部跳过：

Skip for now

这些都不是基础安装必需项。

Bash shell completion

这个只是命令补全，我随意选都行。 不会影响功能是否正常。

六、安装成功验证

安装完成后，我先确认版本：

openclaw --version

我这里正常输出了版本号，说明安装成功。

然后继续看服务状态。

1. 查看网关状态

openclaw gateway status

这里我看到了几个非常关键的信息：

  • Dashboard 地址
  • Gateway 端口
  • Gateway service 正在运行
  • 但一开始还提示权限或配对相关问题

2. 查看整体状态

openclaw status --deep

这一步主要看：

  • Gateway 是否正常
  • 服务是否托管
  • 有没有明显错误
  • 有没有 token / pairing / origin 相关问题

七、首次访问时遇到的几个经典问题

接下来是最精彩的部分，也就是“为什么它就是不让我一次成功”。

问题 1：origin not allowed

页面里直接报：

origin not allowed
(open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

原因

当前浏览器访问的来源（origin）没有被 OpenClaw 允许。

比如我访问的是：

http://服务器IP:18788

那这个 origin 就得被放到配置里。

解决方式

修改 ~/.openclaw/openclaw.json，加入：

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": [
        "https://claw.xxx.xx"
      ]
    }
  }
}

如果你临时还想允许 IP 访问，也可以一起加。

问题 2：control ui requires device identity (use HTTPS or localhost secure context)

这个报错一开始非常像“是不是我 token 错了”，结果不是。

真正原因

浏览器当前不是安全上下文。

也就是：

  • 远程访问
  • 但走的是 HTTP
  • 浏览器不认这种环境适合做设备身份校验

解决方式

这一步别挣扎，直接上：

  • 域名
  • HTTPS
  • OpenResty 反向代理

一句话总结：

OpenClaw 不是针对“公网 HTTP 裸奔调试”优化的，它更喜欢你讲点安全礼仪。

问题 3：pairing required

这个提示第一次看到时，我还以为又炸了。

结果不是，这是正常安全流程。

原因

新的浏览器设备首次连接 Control UI 时，需要网关批准。

解决方式

先查看待批准设备：

openclaw devices list

然后批准最近一次请求：

openclaw devices approve --latest

做完后，刷新页面再连接，就通了。

这一刻，真的会有一种“原来你不是坏了，你只是有原则”的感动。

问题 4：502 Bad Gateway

这个通常不是 OpenClaw 配置错了，而是：

OpenResty 反代的后端挂了。

也就是：

OpenResty -> 127.0.0.1:18788

后面的 OpenClaw 服务没起来，OpenResty 自然只能回你一个 502。

排查方式

openclaw gateway status
curl -I http://127.0.0.1:18788
ss -lntp | grep 18788

解决方式

直接重新拉起网关，或者确认它是否被 daemon / systemd 正常托管。

八、1Panel OpenResty 反代配置

这次手动安装后，OpenClaw 的页面和网关都走 18788，所以反代就简单很多。

我最终可用的 location 配置如下：

location / {
    proxy_pass http://127.0.0.1:18788;
    proxy_http_version 1.1;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Port 443;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_buffering off;
}

说明

这份配置的关键点有：

  • proxy_pass 指向本机 18788
  • 保留升级头，兼容 WebSocket
  • 通过 HTTPS 反代后，浏览器可使用 wss:// 连接

最终浏览器访问：

https://claw.xxx.xx

页面里的 WebSocket URL 填：

wss://claw.xxx.xx

九、token 怎么看

查看当前网关 token：

openclaw config get gateway.auth.token

拿到后填到页面的“网关令牌”里即可。

如果你想顺手看 Dashboard 地址，也可以执行：

openclaw dashboard --no-open

十、最终跑通后的结构

我的最终可用结构如下：

  • OpenClaw 手动安装在 Ubuntu 上
  • Gateway 监听在 18788
  • 1Panel OpenResty 反代到 127.0.0.1:18788
  • 域名走 HTTPS
  • 浏览器通过 wss://域名 建立连接
  • 新设备首次访问时，通过 openclaw devices approve --latest 完成 pairing

一句话概括就是：

服务本身不难装，真正难的是把“页面、反代、HTTPS、设备认证、WebSocket”这几个环节全串起来。

十一、我最后总结出的正确安装顺序

如果你想少走弯路，我建议按这个顺序来：

第一步：手动安装 OpenClaw

curl -fsSL https://openclaw.ai/install.sh | bash

第二步：完成安装向导

  • Gateway bind：LAN (0.0.0.0)
  • Gateway port：18788
  • Gateway auth：Token
  • Tailscale：Off
  • Token 提供方式：Generate/store plaintext token
  • Search provider：Skip for now
  • Hooks：Skip for now

第三步：验证安装

openclaw --version
openclaw gateway status
openclaw status --deep

第四步：配置 allowedOrigins

把你的 HTTPS 域名加入：

"gateway": {
  "controlUi": {
    "allowedOrigins": [
      "https://claw.xxx.xx"
    ]
  }
}

第五步：配置 OpenResty 反代

把 HTTPS 域名代理到 127.0.0.1:18788。

第六步：浏览器访问域名

页面里填：

  • WebSocket URL：wss://你的域名
  • 网关令牌：openclaw config get gateway.auth.token 的输出

第七步：如果提示 pairing required

openclaw devices list
openclaw devices approve --latest

到这里基本就稳了。

十二、几个常用排查命令

以后如果有问题，我建议优先用这几个命令：

openclaw gateway status
openclaw status --deep
openclaw devices list
openclaw devices approve --latest
openclaw logs --follow
openclaw config get gateway.auth.token

如果页面突然 502，再补：

curl -I http://127.0.0.1:18788
ss -lntp | grep 18788

结语

这次安装 OpenClaw，最大的感受不是“它真难装”，而是：

它对安全边界、身份校验、连接方式这些事情比较认真。

认真是好事，只是第一次碰的时候，确实容易让人有一种：

“你到底是坏了，还是在教育我？”

好在最终还是跑通了。

如果你也准备：

  • Ubuntu 手动安装 OpenClaw
  • 用 1Panel 的 OpenResty 做反代
  • 通过 HTTPS 域名访问

那这条路是可行的，而且比 1Panel 内置安装清晰很多。

愿你少踩坑，少见 502，少被 pairing 吓一跳。

如果真的又看到 502，也别慌。 十有八九只是网关又想休息了。

avatar
文章
阅读
粉丝