上个月我把本地的 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 全局安装
最常规的方式：
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，就会看到这个：
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
解决办法很暴力：
# macOS
xcode-select --install
# 确认 python3 在 PATH 里
python3 --version
# 我这里输出 Python 3.12.3
装完依赖重新跑一遍 npm install -g @openclaw/cli 就好了。
验证安装 + 配置 API
openclaw --version
# v0.9.3
openclaw config set base_url https://api.ofox.ai/v1
openclaw config set api_key sk-your-key-here
跑一下测试：
openclaw chat -m claude-sonnet-4-20250514 "用一句话解释 JavaScript 闭包"
响应大概 1.2 秒回来。没问题。
方案二：Bun 全局安装
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 号实测时遇到了一个问题：
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。
解决方法：
export OPENCLAW_OPENSSL_PATH=$(brew --prefix openssl@3)/lib
bun install -g @openclaw/cli
加了这个环境变量之后编译就能找到正确的 .dylib 了。这个坑我翻了 OpenClaw 的 GitHub Issues 才找到，官方文档完全没提。
Bun 下的配置方式一样
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 顺序。
最后我选了只保留一个：
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 秒才超时。
# 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：
[aliases]
sonnet = "claude-sonnet-4-20250514"
gpt = "gpt-5.5"
结果 openclaw chat -m sonnet 报错：
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 版本：
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 的配置长这样：
# ~/.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
然后终端里：
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 在频繁切模型的时候体感还是明显的。
