macOS AI CLI工具安装配置避坑指南
2026-06-20阅读 0热度 0
OpenClaw
### 前提条件：macOS（M系列芯片）
### 测试时间：2026年2月
先说点背景。在 macOS M 系列芯片上折腾 AI CLI 工具，很多人都卡在安装和网络配置上——不是报错就是超时，搞了大半天连个对话都没跑通。这篇文章直接给结论和实战方案，不讲废话。
先说结论，这篇东西主要聊三件事，刚好涵盖了目前 Mac 上主流的三款 AI CLI 工具：OpenClaw、Gemini CLI、Claude Code。你会发现，这三款工具的坑其实不少是相通的——网络问题、认证问题、配置问题，只不过各自的“歪脖子树”角度不同罢了。
## 一、OpenClaw：安装与配置的"重重关卡"
OpenClaw 的依赖树规模惊人——709 个包（2026.2x 版本），整个安装过程包括网络下载、本地服务启动、LaunchAgent 注册等多个环节。任何一个环节的网络异常，轻则安装失败，重则运行时报错，防不胜防。
### 1.1 npm install 后网络卡死
**问题描述**：很多人执行 `npm install -g openclaw` 之后，终端就卡在那里一动不动，第一反应是“坏了，是不是卡死了”。
**问题思路**：其实大概率不是卡死，是 npm 在下载那 709 个包的时候网络太慢——从 npm 官方仓库拉依赖包的速度本身就随缘，加上包体积不小，没反应是常态。
**解决方案**：直接监控目录变化，判断安装是否真的在进行：
ls -la /usr/local/lib/node_modules/openclaw # 目录有新增文件 → 正在安装
du -sh /usr/local/lib/node_modules/openclaw # 大小持续增长 → 正在下载
耐心等到终端输出 `added 709 packages in 18m`，才算真正安装完成。18 分钟是正常水平，别急。
### 1.2 LaunchAgent 安装报错（Error 125）
**问题描述**：执行 `openclaw gateway install` 时，直接甩出一个报错：`Bootstrap failed: 125: Domain does not specify specified action`。
**问题思路**：macOS 的 launchd 有个硬性要求——必须是在图形界面登录会话（gui/501）下才能 bootstrap。你如果通过 SSH 远程连接、切到 root 账号、或者跑在无头环境里，都会触发这个错误。说到底，它不认识你那个"非人类登录"的环境。
**解决方案**：最简单直接的办法——在本地图形界面会话里老老实实执行安装命令，不要通过 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 与当前后台运行一致。
**同类扩展**：在多用户环境下，务必统一使用单一用户身份管理 CLI 工具，别让 root 和普通用户混着用——否则配置污染只是一个命令的事。
### 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 官网的聊天 agent 也给出了错误的地址。
小红书上也有人被这个坑坑惨了。
**解决方案**：别无他法，只能以官方文档中的 curl 测试用例为准（官网对接 OpenClaw 的地址是 `https://platform.minimaxi.com/docs/coding-plan/openclaw`），确认正确的 baseurl 后再对接。在 Anthropic 兼容端点配置中，选带 CN 的模型，再填写 API Key。
## 二、Gemini CLI：安装与认证
Gemini CLI 的命门在 Google 账号 OAuth 认证和 Google AI API 上。如果网络环境不通畅，认证跳转和 API 调用两个环节都可能卡死。
### 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 流程可能被拦截或返回异常状态。这个问题的本质是：你的网络环境对 Google 服务的访问受限。
**解决方案**：绕过 OAuth，直接用 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 等）都可能遇到类似问题，优先考虑 API Key 方案是比较稳妥的做法。
### 2.2 对话超时 443
**问题描述**：登录或对话时提示 `Failed to exchange authorization code for tokens: connect ETIMEDOUT 74.125.203.95:443`。
**问题思路**：终端尝试连接 `googleapis.com` 进行 OAuth 认证或 API 调用时被防火墙拦截，导致连接超时。那个 IP 地址 74.125.203.95:443 正是 Google API 的典型入口。
**解决方案**：略。
### 2.3 API Error: fetch failed
**问题描述**：对话时提示 `[API Error: fetch failed]`。
**问题思路**：Node.js 运行时没有自动读取系统环境变量中的设置。很多网络环境需要系统袋里才能正确访问 Google API，但 Node.js 默认不读取系统袋里。
**解决方案**：略。
### 2.4 配额耗尽
**问题描述**：提示 `[API Error: You ha ve exhausted your daily quota on this model.]`。
**问题思路**：Gemini CLI 默认使用较高级模型，免费额度极低——每天大约只有 50 次请求。如果你试图进行大量对话，很快就会被拦截。
**解决方案**：去 AI Studio 确认配额使用情况。如果已耗尽，换一个 Google 账号重新生成 API Key 并在终端替换即可。
## 三、Claude Code：配置与网络问题
Claude Code（`claude`）默认走 Anthropic 官方 API，也就是说，如果你要接入第三方兼容端点（比如 MiniMax），证书和域名问题是主要障碍。
### 3.1 cc-switch 测速 404
**问题描述**：执行 `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 残留的自签名/中间证书
- 网络环境干预
**解决方案**：分两种情况处理。
**方案一：临时禁用证书验证（仅用于快速验证，不推荐长期使用）**
export NODE_TLS_REJECT_UNAUTHORIZED=0 claude .
**方案二：关闭**
（此处原文不完整，需要根据上下文补充）
