前提條件：macOS（M系列芯片）

測試時間：2026年2月

本文涵蓋 OpenClaw、Gemini CLI、Claude Code 三款主流 AI CLI 工具的安裝、配置與調(diào)試。

第一章：OpenClaw 安裝與配置

OpenClaw 依賴樹龐大（709個包，2026.2x版本），安裝過程涉及網(wǎng)絡(luò)下載、本地服務(wù)啟動、LaunchAgent 注冊等多個環(huán)節(jié)，任何一環(huán)的網(wǎng)絡(luò)異常都會導(dǎo)致安裝失敗或運(yùn)行時報錯。

1.1 npm install 網(wǎng)絡(luò)卡死

問題描述：執(zhí)行 npm install -g openclaw 后，終端長時間無輸出，看起來像卡死。

問題思路：npm 安裝依賴包時需要從 npm 官方倉庫下載大量文件，下載速度極慢甚至超時，容易誤判為程序卡死。

解決方案：通過以下命令監(jiān)控安裝進(jìn)度，判斷是否正常進(jìn)行：

ls -la /usr/local/lib/node_modules/openclaw # 目錄有新增文件 → 正在安裝 du -sh /usr/local/lib/node_modules/openclaw # 大小持續(xù)增長 → 正在下載

直到終端輸出 added 709 packages in 18m，才算安裝完成。

1.2 LaunchAgent 安裝失?。‥rror 125）

問題描述：執(zhí)行 openclaw gateway install 報錯：Bootstrap failed: 125: Domain does not support specified action。

問題思路：macOS 的 launchd 要求 LaunchAgent 必須在圖形界面登錄會話（gui/501）下 bootstrap。SSH 遠(yuǎn)程連接、sudo root 切換、或 headless 環(huán)境下運(yùn)行均會觸發(fā)此錯誤。

解決方案：確保在本地圖形界面會話中執(zhí)行安裝命令，避免通過 SSH 或 sudo 切換身份后操作。

1.3 Token Mismatch 與配置文件混亂

問題描述：Dashboard 顯示 unauthorized: gateway token mismatch，status 顯示 RPC probe failed (code 1008)。

問題思路：服務(wù)端存儲的 gateway.auth.token 與客戶端 probe 使用的 gateway.remote.token 不一致。常見于曾使用 sudo/root 安裝導(dǎo)致配置文件路徑混亂（root 權(quán)限寫入 /usr/local/，普通用戶寫入 ~/.openclaw/）。

解決方案：手動同步 token：

openclaw config set gateway.remote.token "$(cat ~/.openclaw/openclaw.json | grep '"token"' | awk -F'"' '{print $4}')"

此命令可重新打開正確的web認(rèn)證，頁面token與當(dāng)前后臺運(yùn)行一致。

同類擴(kuò)展：多用戶環(huán)境下，務(wù)必統(tǒng)一使用單一用戶身份管理 CLI 工具，避免權(quán)限混用導(dǎo)致配置污染。

1.4 Gemini API 接入報 fetch failed

問題描述：當(dāng)配置了例如Google Gemini 時，tui 頁面和 Web 界面對話顯示 fetch failed，日志顯示 too many failed authentication attempts。

同類擴(kuò)展：

1.5 MiniMax API 域名陷阱（重點(diǎn)大坑）

問題描述：調(diào)用 MiniMax API 時返回 HTTP 401 authentication_error: invalid api key。

問題思路：MiniMax 存在國內(nèi)版與版兩個獨(dú)立服務(wù)，域名不同：

• 國內(nèi)版：api.minimaxi.com
• 版：api.minimax.io（注意結(jié)尾的 i）

大蝦引導(dǎo)頁配置模型時，如果你開通了MiniMax訂閱，要選擇帶CN的接入端點(diǎn)：

兩者 API 密鑰不互通，官方文檔也是混用的。即使咨詢 MiniMax 官方問答機(jī)器人，它也可能給出錯誤的域名答案。如下圖所示，MiniMax官網(wǎng)的聊天agent也給出了錯誤的地址。

小紅書眾多網(wǎng)友也敗在這個大坑上

解決方案：務(wù)必以官方文檔中的 curl 測試用例為準(zhǔn)，（官網(wǎng)對接OpenClaw地址 https://platform.minimaxi.com/docs/coding-plan/openclaw）確認(rèn)正確的 baseurl 后再對接 API。在 Anthropic 兼容端點(diǎn)配置中，需選擇帶 CN 的模型，再填寫 API Key。

第二章：Gemini CLI 安裝與認(rèn)證

Gemini CLI 依賴 Google 賬號 OAuth 認(rèn)證和 Google AI API，需要解決認(rèn)證跳轉(zhuǎn)和 API 調(diào)用兩層的網(wǎng)絡(luò)連通性問題。

2.1 Google 賬號 OAuth 同意失敗

問題描述：瀏覽器跳轉(zhuǎn)后報錯：Sign-in failed — The authentication did not complete successfully. The following products are not yet authorized to access your account: Gemini Code Assist, Gemini CLI。

問題思路：Gemini API 的部分服務(wù)在受限制，OAuth 流程可能被攔截或返回異常狀態(tài)。

解決方案：直接使用 API Key 認(rèn)證：

1.前往 Google AI Studio 獲取 API Key

2.運(yùn)行 gemini 后選擇 2. Use Gemini API Key

3.粘貼 API Key 完成認(rèn)證

同類擴(kuò)展：所有需要 Google OAuth 的工具（Google Cloud SDK、Firebase CLI 等均可能遇到類似問題，優(yōu)先考慮 API Key 方案。

2.2 對話超時 443

問題描述：登錄或?qū)υ挄r提示 Failed to exchange authorization code for tokens: connect ETIMEDOUT 74.125.203.95:443。

問題思路：終端嘗試連接 googleapis.com 進(jìn)行 OAuth 認(rèn)證或 API 調(diào)用時被防火墻攔截，導(dǎo)致連接超時。

解決方案：

2.3 API Error: fetch failed

問題描述：對話時提示 [API Error: fetch failed]

問題思路：Node.js 運(yùn)行時沒有自動讀取系統(tǒng)環(huán)境變量中的設(shè)置。

2.4 配額耗盡

問題描述：提示 [API Error: You have exhausted your daily quota on this model.]。

問題思路：Gemini CLI 默認(rèn)使用較高級模型，免費(fèi)額度極低（每天約 50 次請求）。

解決方案：前往 AI Studio 確認(rèn)配額使用情況。若已耗盡，更換 Google 賬號重新生成 API Key 并在終端替換。

第三章：Claude Code 配置與網(wǎng)絡(luò)問題

Claude Code（claude）默認(rèn)使用 Anthropic 官方 API，需要通過自定義端點(diǎn)訪問。配置 MiniMax 等第三方兼容端點(diǎn)時，證書和域名問題是主要障礙。

3.1 cc-switch 測速 404

問題描述：執(zhí)行 cc-switch 測速時返回 404 錯誤。

問題思路：https://api.minimaxi.com/anthropic 根路徑返回 404 是設(shè)計(jì)如此，不是 bug。只要 claude . 能正常對話，測速 404 可忽略。

解決方案：無需處理，忽略即可。

3.2 自簽名證書檢測（重點(diǎn)）

問題描述：提示 API Error: Unable to connect to API: Self-signed certificate detected. Check your proxy or corporate SSL certificates。

問題思路：使用自定義 API（如 MiniMax 的 https://api.minimaxi.com/anthropic）時，Node.js/Bun 運(yùn)行時的 TLS 驗(yàn)證機(jī)制檢測到證書鏈問題?？赡茉虬ǎ?/p>

• macOS Keychain 殘留的自簽名/中間證書
• 網(wǎng)絡(luò)環(huán)境干預(yù)等

解決方案：分兩種情況處理。

方案一：臨時禁用證書驗(yàn)證（僅用于快速驗(yàn)證，不推薦長期使用）

export NODE_TLS_REJECT_UNAUTHORIZED=0 claude .

方案二：關(guān)閉

以上就是macOS平臺AI CLI工具安裝與配置避坑指南(OpenClaw/Gemini CLI/Claude Code)的詳細(xì)內(nèi)容，更多關(guān)于macOS安裝AI CLI工具教程的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論