macOS 平台 AI CLI 工具安装与配置避坑指南（OpenClaw、Gemini CLI、Claude Code）
前提条件：macOS（M系列芯片）
测试时间：2026年2月
本文涵盖 OpenClaw、Gemini CLI、Claude Code 三款主流 AI CLI 工具的安装、配置与调试。
第一章：OpenClaw 安装与配置
OpenClaw 依赖树庞大（709个包，2026.2x版本），安装过程涉及网络下载、本地服务启动、LaunchAgent 注册等多个环节，任何一环的网络异常都会导致安装失败或运行时报错。
1.1 npm install 网络卡死
问题描述：执行 npm install -g openclaw 后，终端长时间无输出，看起来像卡死。
问题思路：npm 安装依赖包时需要从 npm 官方仓库下载大量文件，下载速度极慢甚至超时，容易误判为程序卡死。
解决方案：通过以下命令监控安装进度，判断是否正常进行：
ls -la /usr/local/lib/node_modules/openclaw # 目录有新增文件 → 正在安装 du -sh /usr/local/lib/node_modules/openclaw # 大小持续增长 → 正在下载
直到终端输出 added 709 packages in 18m，才算安装完成。
1.2 LaunchAgent 安装失败（Error 125）
问题描述：执行 openclaw gateway install 报错：Bootstrap failed: 125: Domain does not support specified action。
问题思路：macOS 的 launchd 要求 LaunchAgent 必须在图形界面登录会话（gui/501）下 bootstrap。SSH 远程连接、sudo root 切换、或 headless 环境下运行均会触发此错误。
解决方案：确保在本地图形界面会话中执行安装命令，避免通过 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 工具，避免权限混用导致配置污染。
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 后再对接 API。在 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 流程可能被拦截或返回异常状态。
解决方案：直接使用 API Key 认证：
- 前往 Google AI Studio 获取 API Key
- 运行
gemini后选择2. Use Gemini API Key - 粘贴 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 调用时被防火墙拦截，导致连接超时。
解决方案：
2.3 API Error: fetch failed
问题描述：对话时提示 [API Error: fetch failed]
问题思路：Node.js 运行时没有自动读取系统环境变量中的设置。
2.4 配额耗尽
问题描述：提示 [API Error: You have 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 残留的自签名/中间证书
- 曾使用调试代理工具（Charles、Proxyman、mitmproxy）未完全移除 CA 证书
- 机场 WiFi、运营商劫持、DNS 污染等网络环境干预
- 代理软件开启 TLS 解密（MITM）
解决方案：分两种情况处理。
方案一：临时禁用证书验证（仅用于快速验证，不推荐长期使用）
export NODE_TLS_REJECT_UNAUTHORIZED=0 claude .
方案二：关闭
同类扩展：
