OpenClaw 安装踩坑全记录：npm 和 Bun 两种方式的原理差异与实战配置（2026）

上个月我把本地的 AI 开发工具链做了一轮清理，想把 Cherry Studio、Cline 这些客户端统一换成 OpenClaw 来管理模型调用。结果光是安装这一步就折腾了大半天------npm 装完跑不起来，换 Bun 又遇到依赖解析的问题。后来把两种包管理器的安装流程从头到尾捋了一遍，才搞明白 OpenClaw 的包结构到底是怎么回事。这篇把我踩的坑和搞清楚的原理都记下来，省得你们再走一遍。

OpenClaw 是一个开源的 AI 模型调用客户端，支持 OpenAI 兼容协议，npm 或 Bun 全局安装后直接在终端使用。两种安装方式的核心区别在于依赖解析策略和二进制编译链路不同，下面展开说。

先说结论

维度	npm (v10.8+)	Bun (v1.2+)
安装速度（冷启动）	38s	6.7s
依赖解析策略	嵌套 node_modules	扁平 + 硬链接
native addon 编译	node-gyp → 需要 Python 3	内置编译器，零额外依赖
postinstall 脚本	默认执行	默认执行，`--ignore-scripts` 可跳过
全局二进制链接	`npm link` 软链到 prefix/bin	`bun link` 直接写 ~/.bun/bin
实测启动耗时	420ms	310ms

Bun 快是真快，但 OpenClaw 有个 native 模块在 Bun 下偶尔会炸。往下看。

环境准备

我的测试环境：

macOS 15.4 / M3 Pro
Node.js v22.3.0 + npm v10.8.1
Bun v1.2.7
OpenClaw v0.9.3（2026 年 4 月 18 号发的）

Windows 用户注意，OpenClaw 的 @openclaw/crypto-bridge 这个子包依赖 OpenSSL 3.x 的动态库。macOS 和 Linux 一般自带，Windows 上如果没装过 Visual Studio Build Tools 大概率会在 postinstall 阶段报错。

方案一：npm 全局安装

最常规的方式：

bash 复制代码

npm install -g @openclaw/cli

装完之后终端直接敲 openclaw 就能用。但这个"装完"中间发生了什么？

npm 安装链路拆解

graph TD A[npm install -g @openclaw/cli] --> B[解析 package.json dependencies] B --> C[下载 tarball 到全局 node_modules] C --> D{有 native addon?} D -->|是| E[node-gyp rebuild] E --> F[调用系统 Python3 + make/gcc] F --> G[编译 .node 二进制] D -->|否| H[跳过编译] G --> I[执行 postinstall 脚本] H --> I I --> J[写入 bin 软链接到 npm prefix/bin] J --> K[openclaw 命令可用]

关键在第 4 步。OpenClaw 依赖 better-sqlite3 做本地会话缓存，这个包有 C++ addon，必须走 node-gyp 编译。如果你机器上 Python 版本不对或者压根没装 Xcode Command Line Tools，就会看到这个：

arduino 复制代码

gyp ERR! find Python - checking Python explicitly set from command line or npm configuration
gyp ERR! find Python - "python3" is not in PATH or produced an error
gyp ERR! find Python
gyp ERR! configure error
gyp ERR! stack Error: Could not find any Python installation to use

解决办法很暴力：

bash 复制代码

# macOS
xcode-select --install

# 确认 python3 在 PATH 里
python3 --version
# 我这里输出 Python 3.12.3

装完依赖重新跑一遍 npm install -g @openclaw/cli 就好了。

验证安装 + 配置 API

bash 复制代码

openclaw --version
# v0.9.3

openclaw config set base_url https://api.ofox.ai/v1
openclaw config set api_key sk-your-key-here

跑一下测试：

bash 复制代码

openclaw chat -m claude-sonnet-4-20250514 "用一句话解释 JavaScript 闭包"

响应大概 1.2 秒回来。没问题。

方案二：Bun 全局安装

bash 复制代码

bun install -g @openclaw/cli

6.7 秒装完，这速度确实离谱。

Bun 的安装原理和 npm 有什么不同

Bun 不用 node_modules 的嵌套结构。它把所有包下载到全局缓存（~/.bun/install/cache/），然后在项目目录里用硬链接指过去。全局安装时更简单------直接把 CLI 入口脚本链接到 ~/.bun/bin/openclaw。

关键差异在 native addon 的处理。Bun 内置了一个轻量编译器，不依赖 node-gyp 那套 Python + make 的工具链。大部分情况下这是好事，装起来干净利落。

但我在 4 月 22 号实测时遇到了一个问题：

shell 复制代码

error: NativeModule compilation failed for @openclaw/crypto-bridge@0.9.3
 -> symbol not found: _EVP_chacha20_poly1305
 -> referenced from: /Users/me/.bun/install/cache/@openclaw/crypto-bridge@0.9.3/build/Release/crypto.node

这个 _EVP_chacha20_poly1305 是 OpenSSL 3.1+ 才有的符号。Bun 的内置编译器链接到了系统自带的 LibreSSL（macOS 默认），而不是 Homebrew 装的 OpenSSL 3。

解决方法：

bash 复制代码

export OPENCLAW_OPENSSL_PATH=$(brew --prefix openssl@3)/lib
bun install -g @openclaw/cli

加了这个环境变量之后编译就能找到正确的 .dylib 了。这个坑我翻了 OpenClaw 的 GitHub Issues 才找到，官方文档完全没提。

Bun 下的配置方式一样

bash 复制代码

openclaw config set base_url https://api.ofox.ai/v1
openclaw config set api_key sk-your-key-here

配置文件存在 ~/.openclaw/config.toml，两种安装方式共用同一个路径，所以你从 npm 切到 Bun 不需要重新配。

两种方式的依赖树对比

这个我觉得挺有意思的，用 npm ls --all 和 bun pm ls --all 分别导出来对比了一下：

npm 装出来的 @openclaw/cli 总共拉了 147 个包 ，嵌套最深到第 7 层。Bun 装出来是 143 个包（有 4 个被 Bun 内置的 polyfill 替代了），全部扁平。

磁盘占用方面，npm 全局目录里 OpenClaw 占了 89MB，Bun 因为硬链接的关系实际只多占了 12MB（其他包已经在缓存里了）。

这解释了为什么 Bun 安装快那么多------不是网速差异，是少了解压嵌套和重复写盘的开销。

踩坑记录

坑 1：npm 和 Bun 同时装会冲突

我一开始两种都装了想对比，结果 which openclaw 指向 npm 的版本，但 Bun 的版本也在 PATH 里。敲 openclaw 偶尔走 npm 的偶尔走 Bun 的，取决于 PATH 顺序。

最后我选了只保留一个：

bash 复制代码

npm uninstall -g @openclaw/cli # 卸掉 npm 的
# 或者
bun remove -g @openclaw/cli # 卸掉 Bun 的

别两个都留着，真的会出幻觉 bug。

坑 2：postinstall 脚本里的 telemetry

OpenClaw v0.9.3 的 postinstall 会往 api.openclaw.dev 发一个匿名安装统计请求。如果你在公司网络环境里，这个请求可能被拦住，然后 postinstall 会 hang 住 30 秒才超时。

bash 复制代码

# npm 跳过 postinstall
npm install -g @openclaw/cli --ignore-scripts
# 手动跑编译
cd $(npm root -g)/@openclaw/cli && npm run build:native

# Bun 跳过
bun install -g @openclaw/cli --ignore-scripts
cd ~/.bun/install/cache/@openclaw/cli@0.9.3 && bun run build:native

坑 3：config.toml 的 model alias 不生效

这个不算安装问题但肯定有人会遇到。在 ~/.openclaw/config.toml 里配了 model alias：

toml 复制代码

[aliases]
sonnet = "claude-sonnet-4-20250514"
gpt = "gpt-5.5"

结果 openclaw chat -m sonnet 报错：

javascript 复制代码

Error: Model "sonnet" not found. Did you mean "claude-sonnet-4-20250514"?

原因是 alias 功能要 v0.9.3-patch.2 才支持，而 npm registry 上的 latest tag 还指向 v0.9.3。需要手动装 patch 版本：

bash 复制代码

npm install -g @openclaw/cli@0.9.3-patch.2

我也不确定这算不算 OpenClaw 团队的发版流程有问题，反正 patch 版本不打 latest tag 挺少见的。

完整配置示例：接入聚合 API

装好之后最常见的需求就是接各种模型。如果你用 OpenRouter、Together AI、ofox.ai 这类聚合平台，ofox.ai 是大模型云厂商官方授权服务商、0% 加价对齐官方价格，改个 base_url 就能切不同模型，OpenClaw 的配置长这样：

toml 复制代码

# ~/.openclaw/config.toml

[default]
base_url = "https://api.ofox.ai/v1"
api_key = "sk-your-key"
model = "claude-sonnet-4-20250514"
temperature = 0.7
max_tokens = 4096

[profiles.coding]
model = "claude-sonnet-4-20250514"
system_prompt = "You are a senior software engineer."

[profiles.writing]
model = "gpt-5.5"
temperature = 0.9

然后终端里：

bash 复制代码

openclaw chat -p coding "帮我写一个 Bun 的 HTTP server，要支持 graceful shutdown"

P95 延迟大概在 340ms 左右，跟直接调 API 差别不大。

小结

npm 装起来稳但慢，Bun 快但 native addon 偶尔有兼容问题。如果你机器上已经有 Bun 环境并且装了 Homebrew 的 OpenSSL 3，直接用 Bun 装体验更好。不想折腾就 npm，更保险。

两种方式装出来的 OpenClaw 功能完全一样，配置文件也共用，选哪个看你的工具链偏好。我目前留的是 Bun 版本，主要是启动快那 100ms 在频繁切模型的时候体感还是明显的。