更新时间：2026-03-10

这篇文章记录一次从零部署 OpenClaw 的真实过程，目标不是“装上 CLI 就算完”，而是把下面几条链路都跑通：

  • OpenClaw CLI 可用
  • Gateway 作为 macOS 后台服务长期运行
  • 能接入 Telegram Bot
  • 能调起 OpenClaw 自带的浏览器自动化
  • 默认模型最终切到 openai-codex

这套过程里最值钱的，不是安装命令本身，而是几个容易卡住的点：

  • 旧版 Node 会干扰安装器判断
  • codex-cli 和 OpenClaw 某些默认参数不兼容
  • Telegram token 文件格式很容易因为多余字符出问题
  • openai-codex 的 OAuth 可能卡在一个很像“地区限制”的 403
  • 这个 403 的真正原因，未必是你真的在不支持地区

一、目标不是“装上”，而是“真正可用”

很多工具安装都容易停在第一步：命令能运行，但实际链路并不通。

我这次的标准更严格一些，至少要满足这几个条件：

  1. openclaw 命令能正常执行
  2. 打开 dashboard 时 Gateway 是活的
  3. Telegram Bot 能收到消息并完成 pairing
  4. OpenClaw 能控制受管浏览器，而不是只会口头回答
  5. 模型配置最终切换到更适合 tool calling 的 openai-codex

如果只完成第 1 步，其实离“可用”还差很远。

二、安装阶段第一个坑：机器里同时有两个 Node

我这台机器上同时存在：

  • 一个较新的 Node 22
  • 一个旧的 Homebrew Node 18

结果就是，OpenClaw 官方安装器优先识别到了旧 Node，导致安装路径和行为不稳定。

这个坑的结论很直接：

  • 如果系统里有多个 Node 版本，不要盲信安装器自动判断
  • 先确认到底要让 OpenClaw 跑在哪个 Node 上
  • 必要时直接用你确认没问题的 Node 去全局安装

我最后采用的是直接用 Node 22 执行：

1
npm install -g openclaw@latest

这比继续纠缠安装脚本的版本判断更省时间。

三、第二个坑：装完后 shell 可能开始报错

安装过程中，OpenClaw 会往 shell 配置里加补全相关内容。

问题在于，如果补全文件当时还没生成，或者生成顺序不对，新的 shell 会直接报错。最常见的表现是：

1
source ... openclaw.zsh: no such file or directory

这个问题不算大，但很烦。修复思路也简单：

  • 不要无条件 source
  • 改成“文件存在才加载”

这属于典型的“安装器半完成状态”，不影响核心功能，但会影响日常使用体验。

四、第三个坑：OpenClaw 接 codex-cli 后，dashboard 会直接报错

我一开始让 OpenClaw 默认走本机的 codex-cli，这样做的好处是：

  • 可以直接复用本地已经可用的 Codex 环境
  • 不需要一开始就重新折腾 OAuth

但很快就撞上了兼容问题。

OpenClaw 在恢复会话时会调用类似这样的命令：

1
codex exec resume ... --color never ...

而我本机这版 codex exec resume 不接受 --color，于是 dashboard 和 Telegram 回复里都会报：

1
unexpected argument '--color' found

这个错误很容易让人误判成：

  • Telegram 配错了
  • Dashboard 挂了
  • Codex 自己坏了

其实都不是。根因是：

  • OpenClaw 默认拼出来的 resumeArgs
  • 和当前这版 codex-cli 的参数能力不一致

修法也很明确：

  • 覆盖 OpenClaw 的 codex-cli.resumeArgs
  • 去掉 --color
  • 只保留当前版本 codex 支持的参数

这个修完之后，至少“会话继续报错”这条线就先恢复了。

五、第四个坑：Telegram Bot token 可能不是“看起来对”就真的对

Telegram 接入时，我遇到一个很典型的问题：

  • token 文件里尾部多了异常字符

这种问题肉眼不一定第一时间能意识到，因为你看上去像是一整串 token，但实际拿去调 Telegram API 就会出问题。

我的结论是：

  • Telegram token 一定要以纯文本、正常换行保存
  • 不要带多余字符
  • 最稳妥的验证方式不是“看起来像对”，而是直接调官方 getMe

验证命令类似：

1
curl "https://api.telegram.org/bot<TOKEN>/getMe"

只有返回 ok: true，才算 token 真的可用。

六、第五个坑：Telegram 能聊天，不代表它会自动调用浏览器工具

我后面又给 OpenClaw 接上了浏览器自动化。

这部分要先说清楚一个边界：

  • OpenClaw 可以控制受管浏览器
  • 不等于它能直接接管你的整个桌面

也就是说，它能做的是：

  • 打开网页
  • 截网页图
  • 点击页面元素
  • 输入内容
  • 抓页面结构

但不是那种“直接操作你眼前整台电脑 GUI”的远控模式。

浏览器自动化本身配通之后，我实际验证了：

  • open
  • snapshot

都能成功执行。

但 Telegram 里一开始还是经常只会回：

  • 我不能打开图形浏览器
  • 我不能截图

这时候最容易误判成：

  • macOS 权限没开
  • 浏览器自动化根本没成功

其实更接近真实的问题是：

  1. 当时默认模型还是 codex-cli
  2. Telegram 会话没有被明确允许使用 browser 工具

所以这里的关键不是再去折腾系统权限，而是：

  • 给 Telegram 直连用户单独放开 browser
  • 给它一个明确的 system prompt，要求网页任务优先调用 browser tool

换句话说，工具装好了，不等于 agent 一定会用。

七、为什么我最后还是从 codex-cli 切到了 openai-codex

这一步是整个部署里最重要的结构性调整。

原因很简单：

  • codex-cli 更适合代码、终端、文件任务
  • 但在 OpenClaw 这套架构里，它不是最适合承接原生 tools 的那条路

如果你的目标是：

  • Telegram 发一句话
  • OpenClaw 真去调用 browser
  • 再把结果返回

那最终还是更适合切到 openai-codex 这种 provider 路线。

我最开始也以为登录一下就完了，结果没那么简单。

八、最难定位的坑：OAuth 看起来成功了，但最后还是 403

切换 openai-codex 时，浏览器会先跳到 OpenAI 登录页。

前两次我在浏览器里都看到了非常像“已经成功”的提示：

1
Authentication successful. Return to your terminal to continue.

但终端最后却失败，报的是：

1
2
code->token failed: 403
unsupported_country_region_territory

这个错误非常迷惑，因为它会让人第一反应觉得：

  • 是地区限制
  • 是账号不支持
  • 是代理不稳定

这些猜测并不完全错，但也不够精确。

真正要分清的是：

  1. 浏览器登录成功
  2. 本地回调成功
  3. 失败发生在 OAuth 的 authorization code -> access token 交换

也就是说，卡住的并不是浏览器那一步，而是 Node.js 进程发出的那一步请求。

九、这次 403 的真正根因：浏览器和 Node.js 不一定走同一条代理链路

这是这次踩坑里最有价值的经验。

我机器上明明已经有代理环境变量，比如：

  • http_proxy
  • https_proxy

而且浏览器登录页也确实能正常打开。

但问题在于：

  • 浏览器能走代理，不代表 Node.js 的 fetch() 就一定按你想象的方式走代理

最后证明有效的修复方法是：

1
NODE_USE_ENV_PROXY=1 openclaw models auth login --provider openai-codex --set-default

加上这行之后，OAuth 第三次终于成功了。

这说明前面的 403，至少在我的场景里，主因不是“真的身处不支持地区”，而更像是：

  • Node.js 发往 OpenAI token endpoint 的请求
  • 没有可靠走到和浏览器同一条翻墙链路

所以这次的结论很明确：

  • 浏览器成功，不等于 OAuth 真正成功
  • 403 的关键点不在网页登录页，而在 token 交换
  • 如果你依赖环境代理，NODE_USE_ENV_PROXY=1 值得优先排查

十、最终状态：哪些东西算真正跑通了

到最后，这套环境的可用状态可以归纳成几条：

  • OpenClaw CLI 可运行
  • Gateway 作为 macOS 后台服务正常运行
  • Telegram Bot 可接入并完成 pairing
  • 受管浏览器可打开页面并获取页面结构
  • 默认模型切换到了 openai-codex

但也要诚实说明边界：

  • 它能操作受管浏览器，不等于能直接远控整台电脑
  • 它能处理网页截图，不等于能主动抓你当前桌面
  • 某些代理行为如果不固化到后台服务环境里，后续重启后仍可能不稳定

十一、如果你也要照着做，我建议优先记住这几条

1. 先确认到底是哪一个 Node 在生效

如果系统里同时有多个 Node，安装器很容易判断错。

2. codex-cli 能跑，不代表和 OpenClaw 默认参数完全兼容

遇到 --color 这种错误，优先去看 OpenClaw 给 CLI backend 拼了什么参数。

3. Telegram token 一定用官方接口验证

不要靠肉眼判断。

4. 浏览器工具能用，不代表 Telegram 会自动调用

工具权限、用户级配置和提示词都可能影响结果。

5. OAuth 的 403 不要只盯“地区”

要把浏览器登录和 Node.js token 交换分开看。

6. 代理变量存在，不代表 Node.js 一定会按预期使用

NODE_USE_ENV_PROXY=1 是这次最关键的修复点。

十二、最后的建议

如果你只是想体验 OpenClaw，装上 CLI 就够了。

但如果你想把它真的接进自己的工作流，比如：

  • Telegram 消息入口
  • 浏览器自动化
  • 长期后台运行
  • OpenAI Codex provider

那就不要把“安装成功”理解成“部署成功”。

真正难的部分，几乎都在安装之后：

  • 参数兼容
  • 代理链路
  • token 文件格式
  • 后台服务环境
  • tool calling 行为

这几块处理好了，OpenClaw 才算从“能启动”进入“能用”。

附：文中提到的公开命令示例

安装：

1
npm install -g openclaw@latest

查看模型状态：

1
openclaw models status --plain

受管浏览器验证：

1
2
openclaw browser open https://example.com --browser-profile webauto
openclaw browser snapshot --browser-profile webauto

Telegram token 验证：

1
curl "https://api.telegram.org/bot<TOKEN>/getMe"

重新执行 OpenAI Codex OAuth：

1
NODE_USE_ENV_PROXY=1 openclaw models auth login --provider openai-codex --set-default

如果后续我要继续整理，我会再拆两篇：

  • 一篇写“纯安装步骤版”
  • 一篇写“故障排查版”