Gemini CLI 部署

Gemini CLI 是 Google 官方的开源命令行 AI agent——形态类似 Claude Code / Codex，底层调 Gemini 模型。

WARNING

Gemini CLI 原生设计上偏向接 Google 官方账号（API Key 或 Workspace 登录），对自定义 endpoint 的支持取决于 CLI 版本。本页给的是目前社区常用的两条接入路径，具体哪条在你机器上能走通，请按下面顺序试。

前置条件

• Node.js 18+：Windows / macOS / Linux 安装指南
• why01 API Key：创建 API Key
• 控制台确认 Gemini 模型可访问：去 模型页 确认 gemini-* 系列模型在你的用户组里可见

路径 A：用环境变量直接指向 why01（首选试这个）

适合较新版本的 Gemini CLI，支持通过环境变量改 base URL。

1. 安装

npm install -g @google/gemini-cli

2. 配置环境变量

macOS / Linux

# 加到 ~/.zshrc 或 ~/.bashrc
export GEMINI_API_KEY=sk-你的why01-key
export CODE_ASSIST_ENDPOINT=https://s1.why01.top
export GOOGLE_GEMINI_BASE_URL=https://s1.why01.top
source ~/.zshrc

Windows PowerShell（永久）

[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "sk-你的why01-key", "User")
[Environment]::SetEnvironmentVariable("CODE_ASSIST_ENDPOINT", "https://s1.why01.top", "User")
[Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://s1.why01.top", "User")
# 关闭所有终端重开才生效

TIP

不同 Gemini CLI 版本读的环境变量名不同——上面三个全设上覆盖面最广。多余的设了不影响。

3. 启动

cd ~/your-project
gemini

跑一个简单任务后到 why01 控制台 → 日志 看有没有 Gemini 模型的调用——有 = 接通。

路径 B：用 OpenAI 兼容客户端调 Gemini 模型（备选，最稳）

如果路径 A 在你机器上跑不通（不同 Gemini CLI 版本对自定义 endpoint 的支持差异较大），直接放弃 Gemini CLI，改用 OpenAI 协议兼容的客户端调用 Gemini 模型——本质上达成同样的目的。

具体方式：

• Cherry Studio（桌面 GUI）：Cherry Studio 接入，添加模型时填 gemini-2.5-pro / gemini-2.5-flash 等
• Cursor（IDE）：Cursor 接入，添加 Gemini 模型名
• Claude Code 的 anthropic-style 形态 + 调 Gemini 模型：不行，Claude Code 只调 Claude 系列
• 裸 OpenAI SDK 写代码：Gemini 接入，直接 Python / Node 调 /v1/chat/completions + model: "gemini-2.5-pro"

TIP

对于"在终端用 AI 帮我写代码"这个核心需求，路径 B 用 Claude Code + Codex 任一已经能覆盖。Gemini CLI 不是必须的——按你实际需要选。

路径 A 常见问题

启动报 401 / 鉴权失败

• 检查 GEMINI_API_KEY 设进去了：echo $GEMINI_API_KEY
• 注意：Gemini CLI 默认的 401 错误信息可能引导你"登录 Google 账号"——忽略，本站走的是 API Key 路径，不要去登录 Google
• 确认 Key 未禁用未过期

启动报 404 / model not found

• Gemini CLI 默认用某个 Gemini 模型，可能你账户用户组没接入
• 用 --model 显式指定（具体参数视 CLI 版本，看 gemini --help）
• 或换用 控制台模型页 上确实可见的模型

启动跳转到 OAuth 登录页要求绑 Google 账号

部分 Gemini CLI 版本默认走 Workspace OAuth 流程，忽略 API_KEY 环境变量。这种情况：

• 升级 / 降级 CLI 到支持 API Key 鉴权的版本
• 或者直接放弃路径 A，走路径 B

Code Assist endpoint 错误

CODE_ASSIST_ENDPOINT 是 Gemini CLI 内部的"代码辅助上下文"服务地址。新版 CLI 可能拆分到不同环境变量，看官方 README 最新版的环境变量列表。

下一步

• 想横向比较 → Claude Code 部署 · Codex CLI 部署
• 直接调 Gemini 不用 CLI → Gemini API 接入
• Gemini CLI 官方仓库 → https://github.com/google-gemini/gemini-cli