从零配置 Gemini CLI

准备（Preparation） ​

预留约 10 分钟。需要 CC Switch v3.20.0、Gemini CLI，以及一把只给本机使用的可撤销 Key。CC Switch 管理 Gemini 的原生环境约定；它不会把任意 OpenAI-compatible 或 Anthropic-compatible URL 自动变成 Gemini 原生端点。

先备份 ~/.gemini/.env 和 ~/.gemini/settings.json。.env 保存 Provider 环境值，settings.json 保留 Gemini CLI 与 MCP 配置。不要覆盖无关设置，也不要把 Google OAuth 会话当作 API Key。

下载（Download） ​

从 Google Gemini CLI 官方仓库安装。官方 npm 命令是：

npm install -g @google/gemini-cli

CC Switch 只从官方 v3.20.0 Release下载，并选择匹配操作系统和架构的资源。不要使用镜像或重打包安装器。

安装后运行 gemini --version。在 CC Switch 打开 关于（About），确认显示 v3.20.0。任一版本检查失败或与下载 Release 不一致时不要继续。

首次启动（First launch） ​

先运行一次 gemini，完成 Gemini CLI 自己的 Google OAuth 或 API Key 引导，直到交互提示可用。修改 Provider 前退出该会话。首次启动会建立原生配置目录；随后配置的梭子蟹 Provider 与官方登录路径保持分离。

配置 Provider 前，再次在 CC Switch 关于（About） 确认 v3.20.0；若不一致，停止并安装匹配的官方 Release。

API Key 与分组（API Key and group） ​

在梭子蟹控制台创建专用 <API_KEY>，并分配到允许目标端点与模型的分组。只记录 Key 标签、分组和创建时间，不记录完整值。这把 Key 用于配置的梭子蟹端点，不能替代 Google OAuth，也不是 ChatGPT 订阅。

模型目录：GET /v1/models（Model catalog） ​

修改 CC Switch 前，用同一把 Key 请求 GET https://suoxie.codes/v1/models，从 data[].id 原样复制一个值作为 <MODEL_FROM_V1_MODELS>。

Windows PowerShell：

$secureKey = Read-Host 'API key' -AsSecureString
$credential = [System.Net.NetworkCredential]::new('', $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
curl.exe --fail-with-body https://suoxie.codes/v1/models `
  -H "Authorization: Bearer $env:SUOXIE_API_KEY"

macOS / Linux：

read -rsp 'API key: ' SUOXIE_API_KEY && printf '\n'
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"

这只证明 Key、分组、URL 和模型能通过模型列表端点访问，不证明服务接受 Gemini CLI 的原生请求结构。

在 CC Switch 配置 Provider ​

在 CC Switch 选择 Gemini CLI，点击 +，创建如 suoxie-gemini 的 Provider。https://suoxie.codes/v1/models 只是一把 Key 与分组的模型可见性基线；绝不能把 https://suoxie.codes/v1 作为 GOOGLE_GEMINI_BASE_URL。直连 Provider 的 Base URL 只能填 <VERIFIED_GEMINI_NATIVE_BASE_URL>，且必须先确认它真实实现 Gemini Native；再输入专用 Key，模型填 <MODEL_FROM_V1_MODELS>。不能因为模型名称相似就选择 OpenAI 或 Anthropic 格式。

CC Switch 把原生 Provider 环境写入 ~/.gemini/.env，预期字段名为：

GEMINI_API_KEY=<API_KEY>
GOOGLE_GEMINI_BASE_URL=<VERIFIED_GEMINI_NATIVE_BASE_URL>
GEMINI_MODEL=<MODEL_FROM_V1_MODELS>

<VERIFIED_GEMINI_NATIVE_BASE_URL> 必须是实际的 Gemini Native facade 或 translator，不能从模型列表推断。GOOGLE_API_KEY 是受支持的备用 Key 名称，但不要同时定义互相冲突的 Key 字段。CC Switch 会保留额外环境值，并把 settings.json 作为独立的客户端/MCP 配置。

模型映射与协议（Model mapping and protocol） ​

GEMINI_MODEL 必须与同一把 Key 和分组返回的 <MODEL_FROM_V1_MODELS> 完全一致。GOOGLE_GEMINI_BASE_URL 只改变目标地址，不会转换 OpenAI Responses、Chat Completions 或 Anthropic Messages。端点必须提供真实的 Gemini Native facade 或 translator。CC Switch v3.20.0 的 Gemini 本地路由只负责转发、日志和故障切换 Gemini 原生流量，不负责把 Gemini 转换成 OpenAI 或 Anthropic 协议。成功的 /v1/models 结果不是协议证明。

保存、启用与重启（Save, enable, and restart） ​

保存 Provider，并在 CC Switch 中设为当前 Gemini CLI Provider。CC Switch 文档说明 Gemini Provider 切换可立即生效，但首次配置仍应结束当前 Gemini 进程，再启动全新的 gemini 会话，以明确环境来源。后续热切换也必须用一条短请求验证，不能只看卡片状态。

Gemini Native 直连保留 <VERIFIED_GEMINI_NATIVE_BASE_URL>。如需 CC Switch 转发路径，打开 Settings -> Advanced -> Routing Service -> App Routing，先启动 Routing Service，再打开 Gemini CLI 应用开关。服务显示运行且 Gemini CLI 开关已启用即为成功信号；有效本地 URL 是 http://127.0.0.1:15721。它只会转发、记录并可故障切换到已验证的原生 facade，不能把 OpenAI 或 Anthropic 端点转换成 Gemini。

首个请求（First request） ​

在可丢弃的空目录运行 gemini，确认选中 <MODEL_FROM_V1_MODELS>，只发送 Reply with OK。成功标准是 Gemini CLI 经配置的 Gemini Native facade 直连或经本地转发路径返回短文本。若模型列表成功但该请求失败，应先核对原生请求结构支持；模型列表和本地路由都不能转换 OpenAI 或 Anthropic 协议，不要改猜测的模型名。

验证后清理临时 shell 变量：

Remove-Item Env:SUOXIE_API_KEY -ErrorAction SilentlyContinue
Remove-Variable secureKey, credential -ErrorAction SilentlyContinue

unset SUOXIE_API_KEY

Key 用量（Key usage） ​

打开 Key 用量，按请求时间、专用 Key、分组、端点和模型筛选，核对请求数、输入/输出 Token 与费用。出现记录能证明实际上游调用，但仍不代表所有 Gemini 能力兼容。重复请求前先刷新并扩大时间范围。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

结束 Gemini CLI，在 CC Switch 重新启用此前验证可用的 Provider，或恢复私有的修改前 .env 与 settings.json 备份。先恢复旧 Provider 并验证短请求，再关闭 Routing Service 或 Gemini CLI 应用开关。CC Switch 状态保存在 ~/.cc-switch/cc-switch.db，备份目录是 ~/.cc-switch/backups/；恢复前保留两者。不要覆盖唯一备份，也不要为了回滚自定义 API Provider 而删除官方 OAuth 配置。

.env 可能含完整 Key。它和备份不得进入公开仓库、截图、录屏、共享工单或云同步目录。确认旧 Provider 的短请求成功后，再撤销本轮临时测试 Key。怀疑泄露时立即撤销该 Key，在正确分组创建替代 Key，更新 CC Switch，新开 Gemini 会话，并在 Key 用量中核对一次新请求。