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 SiliconM 系列机器需要把 brew 加进 PATH脚本结束时会提示你跑两条命令类似echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zshrc eval $(/opt/homebrew/bin/brew shellenv)Intel 机器的路径是/usr/local/bin/brew按提示来即可。接着更新并安装 Node.jsbrew 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 CLInpm 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 Keysettings 与 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 读取配置有两种方式环境变量和配置文件。环境变量最直接写进~/.zshrcexport GOOGLE_GEMINI_BASE_URLhttps://taotoken.net/api export GEMINI_API_KEYsk-你的实际密钥保存后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 是~/.zshrcbash 是~/.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 UnauthorizedKey 无效或没被读取。先echo $GEMINI_API_KEY确认非空再确认 Key 没有多余空格或换行。如果用的是settings.json检查apiKey字段拼写别写成api_key或apikey。还有一种情况是 Key 被复制时带了引号去掉引号。local proxy failed / connection refusedBase 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-keyCLI 还在走默认 OAuth。检查~/.gemini/settings.json是否存在且字段正确或者环境变量GEMINI_API_KEY是否在当前 shell 可见。改完配置后完全退出gemini再重进别在旧会话里试。gemini: command not foundPATH 问题。which gemini看有没有输出没有就检查~/.npm-global/bin是否在 PATH 里或者重开终端。Homebrew 装的 node全局包一般在/opt/homebrew/bin下确认这个路径也在 PATH。Node 版本过低node --version低于 18 会直接报错。用brew upgrade node升级或者brew install node20指定版本。排查顺序建议先gemini --version确认工具在再echo两个环境变量确认配置在最后发一次最小对话确认链路通。三步定位比盲目改配置快得多。6. 把 Key 统一起来后续接入与长期使用建议跑通之后你会发现真正省事的地方在于 Key 统一。同一个 TaoToken Key配到 Gemini CLI 用GEMINI_API_KEYGOOGLE_GEMINI_BASE_URL配到 Claude Code 用ANTHROPIC_BASE_URLANTHROPIC_API_KEY配到 Codex 用auth.json里的OPENAI_BASE_URLOPENAI_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 Planhttps://taotoken.net/coding-plan 。接入文档和字段说明在 https://taotoken.net/doc API Keys 管理在 https://taotoken.net/api-keys 控制台总入口 https://taotoken.net/console 。最后一个实用技巧把gemini包一层 alias带上常用参数比如alias ggemini --model gemini-2.5-pro写进~/.zshrc日常敲g就能进对话。项目里需要它读上下文时先cd到项目根目录再启动别在~下直接跑否则它读不到你的代码。
