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

測試時間：2026年2月

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

第一章：OpenClaw 安裝與配置

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

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

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

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

解決方案：通過以下命令監(jiā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 安裝失敗（Error 125）

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

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

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

1.3 Token Mismatch 與配置文件混亂

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

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

解決方案：手動同步 token：

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

此命令可重新打開正確的web認證，頁面token與當前后臺運行一致。

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

1.4 Gemini API 接入報 fetch failed

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

同類擴展：

1.5 MiniMax API 域名陷阱（重點大坑）

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

問題思路：MiniMax 存在國內版與版兩個獨立服務，域名不同：

• 國內版：api.minimaxi.com
• 版：api.minimax.io（注意結尾的 i）

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

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

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

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

第二章：Gemini CLI 安裝與認證

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

2.1 Google 賬號 OAuth 同意失敗

問題描述：瀏覽器跳轉后報錯：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 的部分服務在受限制，OAuth 流程可能被攔截或返回異常狀態(tài)。

解決方案：直接使用 API Key 認證：

1.前往 Google AI Studio 獲取 API Key

2.運行 gemini 后選擇 2. Use Gemini API Key

3.粘貼 API Key 完成認證

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

2.2 對話超時 443

問題描述：登錄或對話時提示 Failed to exchange authorization code for tokens: connect ETIMEDOUT 74.125.203.95:443。

問題思路：終端嘗試連接 googleapis.com 進行 OAuth 認證或 API 調用時被防火墻攔截，導致連接超時。

解決方案：

2.3 API Error: fetch failed

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

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

2.4 配額耗盡

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

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

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

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

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

3.1 cc-switch 測速 404

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

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

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

3.2 自簽名證書檢測（重點）

問題描述：提示 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 運行時的 TLS 驗證機制檢測到證書鏈問題。可能原因包括：

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

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

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

export NODE_TLS_REJECT_UNAUTHORIZED=0 claude .

方案二：關閉

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

最新評論