上個(gè)月我把本地的 AI 開發(fā)工具鏈做了一輪清理，想把 Cherry Studio、Cline 這些客戶端統(tǒng)一換成 OpenClaw 來管理模型調(diào)用。結(jié)果光是安裝這一步就折騰了大半天——npm 裝完跑不起來，換 Bun 又遇到依賴解析的問題。后來把兩種包管理器的安裝流程從頭到尾捋了一遍，才搞明白 OpenClaw 的包結(jié)構(gòu)到底是怎么回事。這篇把我踩的坑和搞清楚的原理都記下來，省得你們再走一遍。

OpenClaw 是一個(gè)開源的 AI 模型調(diào)用客戶端，支持 OpenAI 兼容協(xié)議，npm 或 Bun 全局安裝后直接在終端使用。兩種安裝方式的核心區(qū)別在于依賴解析策略和二進(jìn)制編譯鏈路不同，下面展開說。

先說結(jié)論

Bun 快是真快，但 OpenClaw 有個(gè) native 模塊在 Bun 下偶爾會炸。往下看。

環(huán)境準(zhǔn)備

我的測試環(huán)境：

• 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 號發(fā)的）

Windows 用戶注意，OpenClaw 的 @openclaw/crypto-bridge 這個(gè)子包依賴 OpenSSL 3.x 的動態(tài)庫。macOS 和 Linux 一般自帶，Windows 上如果沒裝過 Visual Studio Build Tools 大概率會在 postinstall 階段報(bào)錯。

方案一：npm 全局安裝

最常規(guī)的方式：

npm install -g @openclaw/cli

裝完之后終端直接敲 openclaw 就能用。但這個(gè)"裝完"中間發(fā)生了什么？

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[調(diào)用系統(tǒng) Python3 + make/gcc]
 F --> G[編譯 .node 二進(jìn)制]
 D -->|否| H[跳過編譯]
 G --> I[執(zhí)行 postinstall 腳本]
 H --> I
 I --> J[寫入 bin 軟鏈接到 npm prefix/bin]
 J --> K[openclaw 命令可用]

關(guān)鍵在第 4 步。OpenClaw 依賴 better-sqlite3 做本地會話緩存，這個(gè)包有 C++ addon，必須走 node-gyp 編譯。如果你機(jī)器上 Python 版本不對或者壓根沒裝 Xcode Command Line Tools，就會看到這個(gè)：

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

# 確認(rèn) python3 在 PATH 里
python3 --version
# 我這里輸出 Python 3.12.3

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

驗(yàn)證安裝 + 配置 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 閉包"

響應(yīng)大概 1.2 秒回來。沒問題。

方案二：Bun 全局安裝

bun install -g @openclaw/cli

6.7 秒裝完，這速度確實(shí)離譜。

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

Bun 不用 node_modules 的嵌套結(jié)構(gòu)。它把所有包下載到全局緩存（~/.bun/install/cache/），然后在項(xiàng)目目錄里用硬鏈接指過去。全局安裝時(shí)更簡單——直接把 CLI 入口腳本鏈接到 ~/.bun/bin/openclaw。

關(guān)鍵差異在 native addon 的處理。Bun 內(nèi)置了一個(gè)輕量編譯器，不依賴 node-gyp 那套 Python + make 的工具鏈。大部分情況下這是好事，裝起來干凈利落。

但我在 4 月 22 號實(shí)測時(shí)遇到了一個(gè)問題：

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

這個(gè) _EVP_chacha20_poly1305 是 OpenSSL 3.1+ 才有的符號。Bun 的內(nèi)置編譯器鏈接到了系統(tǒng)自帶的 LibreSSL（macOS 默認(rèn)），而不是 Homebrew 裝的 OpenSSL 3。

解決方法：

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

加了這個(gè)環(huán)境變量之后編譯就能找到正確的 .dylib 了。這個(gè)坑我翻了 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，兩種安裝方式共用同一個(gè)路徑，所以你從 npm 切到 Bun 不需要重新配。

兩種方式的依賴樹對比

這個(gè)我覺得挺有意思的，用 npm ls --all 和 bun pm ls --all 分別導(dǎo)出來對比了一下：

npm 裝出來的 @openclaw/cli 總共拉了 147 個(gè)包，嵌套最深到第 7 層。Bun 裝出來是 143 個(gè)包（有 4 個(gè)被 Bun 內(nèi)置的 polyfill 替代了），全部扁平。

磁盤占用方面，npm 全局目錄里 OpenClaw 占了 89MB，Bun 因?yàn)橛叉溄拥年P(guān)系實(shí)際只多占了 12MB（其他包已經(jīng)在緩存里了）。

這解釋了為什么 Bun 安裝快那么多——不是網(wǎng)速差異，是少了解壓嵌套和重復(fù)寫盤的開銷。

踩坑記錄

坑 1：npm 和 Bun 同時(shí)裝會沖突

我一開始兩種都裝了想對比，結(jié)果 which openclaw 指向 npm 的版本，但 Bun 的版本也在 PATH 里。敲 openclaw 偶爾走 npm 的偶爾走 Bun 的，取決于 PATH 順序。

最后我選了只保留一個(gè)：

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

別兩個(gè)都留著，真的會出幻覺 bug。

坑 2：postinstall 腳本里的 telemetry

OpenClaw v0.9.3 的 postinstall 會往 api.openclaw.dev 發(fā)一個(gè)匿名安裝統(tǒng)計(jì)請求。如果你在公司網(wǎng)絡(luò)環(huán)境里，這個(gè)請求可能被攔住，然后 postinstall 會 hang 住 30 秒才超時(shí)。

# 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 不生效

這個(gè)不算安裝問題但肯定有人會遇到。在 ~/.openclaw/config.toml 里配了 model alias：

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

結(jié)果 openclaw chat -m sonnet 報(bào)錯：

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 團(tuán)隊(duì)的發(fā)版流程有問題，反正 patch 版本不打 latest tag 挺少見的。

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

裝好之后最常見的需求就是接各種模型。如果你用 OpenRouter、Together AI、ofox.ai 這類聚合平臺，ofox.ai 是大模型云廠商官方授權(quán)服務(wù)商、0% 加價(jià)對齊官方價(jià)格，改個(gè) 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 "幫我寫一個(gè) Bun 的 HTTP server，要支持 graceful shutdown"

P95 延遲大概在 340ms 左右，跟直接調(diào) API 差別不大。

小結(jié)

npm 裝起來穩(wěn)但慢，Bun 快但 native addon 偶爾有兼容問題。如果你機(jī)器上已經(jīng)有 Bun 環(huán)境并且裝了 Homebrew 的 OpenSSL 3，直接用 Bun 裝體驗(yàn)更好。不想折騰就 npm，更保險(xiǎn)。

兩種方式裝出來的 OpenClaw 功能完全一樣，配置文件也共用，選哪個(gè)看你的工具鏈偏好。我目前留的是 Bun 版本，主要是啟動快那 100ms 在頻繁切模型的時(shí)候體感還是明顯的。

以上就是OpenClaw安裝npm和Bun兩種方式的原理差異與實(shí)戰(zhàn)配置的詳細(xì)內(nèi)容，更多關(guān)于OpenClaw安裝npm和Bun差異與配置的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論