1. macOS 上 Gemini CLI 到底能做什么，为什么值得折腾
Gemini CLI 是 Google 官方开源的命令行 AI 编程助手，跑在终端里，能读你当前项目的文件、执行 shell 命令、做代码审查、生成补丁，甚至帮你排查报错。它和编辑器里的插件不一样，它更像一个待在终端里的结对程序员，你cd到哪个目录，它就能感知哪个目录的上下文。适合谁？适合每天泡在终端里的后端、运维、全栈，也适合想用命令行快速验证模型能力的人。
但 macOS 上从零跑通它，坑其实不少。Node.js 版本不对、Homebrew 装完 PATH 没生效、npm 全局目录没权限、首次鉴权卡在 OAuth 跳转、Base URL 配错导致请求打到默认端点超时……这些问题我在不同机器上几乎都踩过一遍。所以这篇不聊虚的，就按「Homebrew 装 Node.js → npm 全局装 Gemini CLI → 配好统一 Key 和 Base URL → 跑一次最小对话」这条链路，把每一步的可复制命令和验证动作都写清楚，目标是一次跑通。
核心检索词先摆出来：Gemini CLI 在 macOS 上的安装，本质是三件事——环境（Node.js）、工具（npm 全局包）、鉴权（API Key + Base URL）。三者缺一，gemini命令要么找不到，要么启动后报鉴权失败。很多人卡在第三步，是因为默认走的是 Google 账号 OAuth 流程，网络环境一复杂就容易断。用 TaoToken 统一 Key 的好处是：把 Base URL 指向一个稳定端点，Key 用同一个，Claude Code、Codex、Gemini CLI 之间可以复用，不用每个工具单独折腾一套鉴权。
我实测下来，整条链路顺利的话 10 分钟内能跑通，前提是命令别抄错、环境变量别写错文件。下面从环境准备开始，一步步来。
2. Homebrew 装 Node.js 与 npm 全局安装 Gemini CLI 的完整命令
这一节解决「工具装不上」的问题。Gemini CLI 要求 Node.js 18 或更高，macOS 上最省心的方式是 Homebrew。如果你还没装 Homebrew，先跑官方安装脚本：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"装完 Homebrew 后，Apple Silicon（M 系列）机器需要把 brew 加进 PATH，脚本结束时会提示你跑两条命令，类似：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc eval "$(/opt/homebrew/bin/brew shellenv)"Intel 机器的路径是/usr/local/bin/brew，按提示来即可。接着更新并安装 Node.js：
brew update brew install node装完验证版本，两个命令都要有输出：
node --version npm --version正常会看到v20.x.x或更高，npm 是10.x.x左右。如果node提示 command not found，八成是 PATH 没刷新，重开一个终端窗口，或者source ~/.zshrc再试。
Node.js 就绪后，全局安装 Gemini CLI：
npm install -g @google/gemini-cli如果报EACCES权限错误，说明 npm 全局目录归 root 所有。不建议直接sudo npm install -g，那样后续升级还会遇到权限问题。更干净的做法是把 npm 全局目录改到用户目录下：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc然后再跑一次npm install -g @google/gemini-cli，就不会有权限问题了。装完验证：
gemini --version能打印出版本号，说明 CLI 本体装好了。这一步如果失败，先别急着往下走，回到node --version确认环境，再检查which gemini是否指向~/.npm-global/bin/gemini或 Homebrew 的 node 目录。
3. 配置 Base URL 与 API Key：settings 与 auth.json 可复制片段
工具装好只是第一步，真正决定能不能用起来的是鉴权配置。Gemini CLI 默认走 Google 账号 OAuth，首次启动会弹浏览器。如果你希望用统一 Key 走稳定端点，就要显式配置 Base URL 和 API Key。这里给出可复制的配置片段，路径和字段名按实际文件来。
先拿 Key：登录 TaoToken 控制台，在 API Keys 页面创建一个新密钥，复制出来。控制台地址是 https://taotoken.net/console ，创建密钥的入口在 https://taotoken.net/api-keys 。Key 形如sk-开头的一串字符，别泄露。
Gemini CLI 读取配置有两种方式：环境变量和配置文件。环境变量最直接，写进~/.zshrc：
export GOOGLE_GEMINI_BASE_URL="https://taotoken.net/api" export GEMINI_API_KEY="sk-你的实际密钥"保存后source ~/.zshrc，用echo $GOOGLE_GEMINI_BASE_URL和echo $GEMINI_API_KEY验证输出非空。
如果你更习惯用配置文件，Gemini CLI 支持在项目或用户目录下放settings.json。用户级配置放在~/.gemini/settings.json，内容如下：
{ "selectedAuthType": "gemini-api-key", "apiKey": "sk-你的实际密钥", "baseUrl": "https://taotoken.net/api" }注意selectedAuthType要设成gemini-api-key，这样启动时不会走 OAuth 流程。如果你用的是 Codex 那套auth.json结构，字段名不同，Gemini CLI 不直接读auth.json，别混用。三件套记牢：Base URL + Key + Model ID。Model ID 在对话里用/model切换，默认gemini-2.5-pro，需要更强推理可以切gemini-3-pro-preview。
配置完再确认一次文件路径没写错：zsh 是~/.zshrc，bash 是~/.bash_profile，别把 export 写进~/.zsh_profile这种不存在的文件里，那样source会报错。
4. 验证请求：gemini --version 与一次最小对话跑通
配置写完，必须做两步验证，缺一不可。第一步是版本验证，确认 CLI 可执行：
gemini --version输出类似0.1.0或更高。如果这里就报错，说明安装环节有问题，回到第 2 节排查。
第二步是真正发一次请求，验证 Base URL 和 Key 都生效。先建个空目录避免干扰：
mkdir -p ~/gemini-test && cd ~/gemini-test gemini首次启动如果配置正确，会直接进入对话界面，不再弹 OAuth。如果它还是提示你选鉴权方式，说明selectedAuthType没生效，检查~/.gemini/settings.json是否被正确读取，或者环境变量是否在当前 shell 生效。
进入对话后，输入一句最小 prompt：
用一句话解释什么是递归正常会流式返回一段文字。如果卡住不动，或者报401 Unauthorized，就是 Key 或 Base URL 的问题。如果报local proxy failed或连接超时，检查 Base URL 是否写成了https://taotoken.net/api（注意结尾不要多加/gemini之类的路径，除非文档明确要求）。
想验证模型切换，在对话里输入：
/model用方向键选gemini-2.5-pro或gemini-3-pro-preview，确认后继续对话。如果/model列表是空的，通常是 Base URL 没配对，模型列表拉不下来。
一次成功的最小对话，输出应该像这样：
> 用一句话解释什么是递归 递归是指一个函数在其定义中直接或间接调用自身， 通过把大问题拆成同类的小问题来求解，直到达到基准条件。看到这段，说明整条链路通了。此时你可以cd到任意项目目录再跑gemini，它会自动读取当前目录上下文。
5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把最容易撞上的几个报错对照着说清楚，都是真实遇到过的。
401 Unauthorized：Key 无效或没被读取。先echo $GEMINI_API_KEY确认非空，再确认 Key 没有多余空格或换行。如果用的是settings.json，检查apiKey字段拼写，别写成api_key或apikey。还有一种情况是 Key 被复制时带了引号，去掉引号。
local proxy failed / connection refused：Base URL 写错或端点不可达。确认写的是https://taotoken.net/api，不要带尾部斜杠，也不要自己拼/v1之类路径。用curl -I https://taotoken.net/api看是否能通，返回 4xx 也算通，返回Could not resolve host才是网络问题。
reading choices 报错 / 返回结构解析失败：通常是 Base URL 指向了一个不兼容 OpenAI 或 Gemini 原生格式的端点。Gemini CLI 期望的是 Gemini 原生 API 结构，如果端点返回的是 OpenAI 格式的choices数组，解析就会失败。确认 Base URL 用的是文档里给 Gemini CLI 专用的那个，别拿 Claude Code 的端点来填。
OAuth 反复弹窗 / 卡在浏览器授权：说明selectedAuthType没设成gemini-api-key，CLI 还在走默认 OAuth。检查~/.gemini/settings.json是否存在且字段正确，或者环境变量GEMINI_API_KEY是否在当前 shell 可见。改完配置后完全退出gemini再重进，别在旧会话里试。
gemini: command not found：PATH 问题。which gemini看有没有输出，没有就检查~/.npm-global/bin是否在 PATH 里，或者重开终端。Homebrew 装的 node，全局包一般在/opt/homebrew/bin下，确认这个路径也在 PATH。
Node 版本过低：node --version低于 18 会直接报错。用brew upgrade node升级，或者brew install node@20指定版本。
排查顺序建议：先gemini --version确认工具在，再echo两个环境变量确认配置在，最后发一次最小对话确认链路通。三步定位，比盲目改配置快得多。
6. 把 Key 统一起来：后续接入与长期使用建议
跑通之后，你会发现真正省事的地方在于 Key 统一。同一个 TaoToken Key，配到 Gemini CLI 用GEMINI_API_KEY+GOOGLE_GEMINI_BASE_URL，配到 Claude Code 用ANTHROPIC_BASE_URL+ANTHROPIC_API_KEY，配到 Codex 用auth.json里的OPENAI_BASE_URL+OPENAI_API_KEY。三件套字段名不同，但值来自同一个控制台，不用每个工具单独注册、单独记 Key。
如果你打算长期在终端里用 AI 编程，建议把配置写进 shell 配置文件而不是临时 export，这样每次开终端都生效。同时把~/.gemini/settings.json也留一份，双保险。升级 CLI 用npm update -g @google/gemini-cli，升级后如果行为异常，先gemini --version确认版本，再检查配置有没有被覆盖。
想验证更多模型能力，可以直接在模型对话页面试：https://taotoken.net/model-chat 。如果你要把 Gemini CLI 接进日常编码流、配合 Agent 做长任务，可以看 Coding Plan：https://taotoken.net/coding-plan 。接入文档和字段说明在 https://taotoken.net/doc ，API Keys 管理在 https://taotoken.net/api-keys ，控制台总入口 https://taotoken.net/console 。
最后一个实用技巧：把gemini包一层 alias，带上常用参数，比如alias g='gemini --model gemini-2.5-pro'，写进~/.zshrc，日常敲g就能进对话。项目里需要它读上下文时，先cd到项目根目录再启动，别在~下直接跑，否则它读不到你的代码。
