最近后台收到不少私信，都在问同一个组合：CC-switch 和 Gemini CLI。一个是命令行 AI 客户端，一个是专门管理 AI 命令行工具配置的小枢纽，两个搭配起来确实能省不少事。我实际用了一个多月，把安装、配置、切换、踩坑的完整过程整理成这篇详细教学，跟着做就能把这条链路跑通。这篇文章适合刚接触 Gemini CLI 的开发者，也适合手上同时握了好几套模型服务配置、来回手动改文件改到崩溃的朋友。
整篇会按“工具定位 -> 环境准备 -> CC-switch 配置 -> Gemini CLI 实战 -> 问题排查 -> 进阶玩法”的顺序来写，该贴命令的地方我一句不落，该讲原理的地方也会用大白话解释，保证你从头到尾跟下来能把这套环境真正跑起来，而不是看了一堆概念转头就忘。
1. 把工具先看透：它们解决什么问题
1.1 CC-switch 给谁用、解决什么痛
CC-switch 是一个开源项目，它的定位非常聚焦：帮你管理多个 AI 编程命令行工具的配置文件。那些工具包括 Claude Code、Codex、Gemini CLI 等，它们各自的配置存放位置不一样、字段不一样，默认情况下你要切换服务商，就得手动去改 JSON、导出环境变量、重启终端，非常烦。
举个真实场景。我之前同时维护几个项目，一个项目用的是 Gemini 官方接口，另一个项目因为业务需要走第三方兼容服务，还有一个项目日常调试用别的模型。以前我的手动作业流程是：打开配置文件、找到 base_url、替换成目标地址、把 api_key 换掉、改 model 名、保存、退出，然后重启终端让改动生效。一次两次还好，一天切五六次，几乎每次都会漏改某一个字段，改完还要花时间确认到底改对没有。
CC-switch 解决的就是这个痛点。它把这些零散的配置文件管理起来，你在界面里提前录入好多套配置，之后只需要点一下按钮，它就把该写的字段自动写到对应的 CLI 工具配置里。说白了，它不碰模型本身，也不改写任何代码，它只做“配置文件管家”这一件事。
我整理了一下它的典型使用场景：
- 同时有多个 API 平台的账号，想根据需要快速换。
- 同一个平台下有不同的模型，想在模型之间来回试。
- 不同项目分别用不同服务商配置，不想每次手动改。
- 多人协作时，希望团队的 CLI 配置能统一切换、统一维护。
1.2 Gemini CLI 不只聊天，还是一台“终端副驾”
Gemini CLI 是 Google 出品的官方命令行 AI 助手。你可以把它理解为跑在终端里的智能助手，它能读你项目里的代码、分析报错、写测试、改文件，也能直接跟你对话。它和网页端的最大区别是，它长在你命令行里，能直接感知你当前目录的内容，干活效率比复制粘贴高太多。
Gemini CLI 的实际能力可以拆成几块：
- 交互式对话：在终端输入 gemini 进入聊天界面，连续多轮问答。
- 代码理解：给定文件路径或让它直接浏览当前目录，分析逻辑、定位 bug。
- 多模态输入：传一张截图或设计稿给它，它也能读取并给出建议。
- 与编辑器联动：VS Code 里有 Gemini CLI Companion 这类扩展，把终端能力和编辑器上下文结合起来。
对大多数开发者来说，Gemini CLI 最大的价值是“不用离开终端就能处理代码问题”。你写代码时遇到编译错误，把报错丢给它；写测试时，让它先生成一批用例；做 review 时，让它先扫一遍改动。它不是替代你写代码，而是把你从重复劳动里拉出来。真正用顺手之后，我会觉得终端不再只是打命令的地方，更像是多了一个随叫随到的结对程序员。
1.3 两个工具是如何配合的
CC-switch 和 Gemini CLI 是上下游关系。CC-switch 在“配置层”干活，负责把你选中的服务商、模型、密钥写到 Gemini CLI 的配置文件里；Gemini CLI 在“应用层”干活，负责读取配置、发起对话、处理任务。
如果打个比方，CC-switch 是遥控器，Gemini CLI 是电视机。遥控器本身不产生画面，但它能让你在几个频道之间一键切换；电视负责出内容。你要是没有遥控器，手动拧旋钮也能看电视，但体验天差地别。
这个配合关系决定了使用顺序：先把 Gemini CLI 装好跑通，再用 CC-switch 管理它的多套配置，最后日常操作都走 CC-switch 切换。反过来先装 CC-switch 再装 Gemini CLI 也能行，但首次认证 Gemini CLI 时建议先撇开 CC-switch，把原生链路跑通，避免后面排查问题时搞不清是工具的问题还是配置工具的问题。
2. 环境准备：装之前把这些先备好
2.1 Node.js 环境安装与验证
装 Gemini CLI 之前，最基础的是 Node.js。Gemini CLI 是一个 npm 包，所以没有 Node.js 一切免谈。官方要求 Node.js 18 以上，我建议直接装 20 LTS，稳定且兼容性最好。检查命令：
node -v npm -v如果提示找不到命令，就去 Node.js 官网下载对应系统的 LTS 安装包，一路下一步装完，再打开新的终端验证。安装完之后默认 npm 也在，不用单独装。
这里有个很多人忽略的细节：装完 Node.js 后，如果之前已经打开了好几个终端窗口，那些窗口里的 PATH 环境变量不会自动更新，必须开一个新终端才能识别 node 命令。我见过太多人说“明明装了 Node 但报错找不到”，十有八九就是没开新窗口。
Git 不是硬性要求，但如果你打算让 Gemini CLI 帮忙分析仓库、生成 commit message，最好提前装好。VS Code 属于可选项，装它的目的是使用 Gemini CLI Companion 扩展，如果你只喜欢纯终端操作，这块可以跳过。
2.2 申请 Gemini API Key 的完整流程
使用 Gemini CLI 前，需要准备一个 Google AI 平台的 API Key。打开 Google AI Studio，登录账号，在 API Key 管理页面创建一个新的密钥，创建后复制保存。这个 Key 就像你账号的一把钥匙，之后不管是直接用环境变量还是塞进配置工具，都用它。
几个关键点：
- API Key 只在创建时完整显示一次，创建完立刻复制到本地密码管理器。
- 不要把 Key 提交到 git 仓库，也不要在公共场合截图。
- 如果需要在多个项目里共用，最好的做法是每个项目单独建一个 Key，出问题方便单独吊销，不影响其他项目。
创建好之后建议先在网页端随便发起一次对话，确认这个 Key 确实有效，再往下走。这一步能避免后面把环境问题误判成 Key 问题。
2.3 下载安装 CC-switch（三个平台都过一遍）
CC-switch 提供了常见的桌面端安装包。打开它的 GitHub Releases 页面，根据系统选择文件：
- Windows：下 .exe 安装包，双击安装。
- macOS：下 .dmg 文件，打开后拖到 Applications。
- Linux：一般用 .AppImage，下载后 chmod +x 直接运行。
Windows 上如果安装过程中遇到 SmartScreen 拦截，点“更多信息”再选“仍要运行”即可，这是常见的安全提示拦截，不用慌。macOS 首次打开如果提示来自未知开发者，去系统设置的“隐私与安全性”里点“仍要打开”。
安装完之后，第一次打开 CC-switch，界面会提示你选择要管理的 CLI 工具，比如 Claude Code、Gemini CLI、Codex 等。这个选择很关键，因为后面所有操作都围绕你选定的工具展开。你要是还没装 Gemini CLI，这里可以先退出去，等第四章装完再回来选。
2.4 首次打开 CC-switch 的界面认认门
装好 CC-switch 后，界面布局一般是这样：左侧是工具列表，右侧是配置卡片区，顶部是新增按钮。第一次用，建议先把界面上的选项挨个点一遍，不用怕点错，它不执行任何破坏性操作，只是读取本地配置。
有一个地方需要留意：CC-switch 的界面语言和命名在不同版本里可能稍微不一样，但核心概念就三样，配置名称、配置内容、切换按钮。你只要抓住这三样，无论界面怎么变都不会迷路。如果某个界面显示“未检测到工具配置”，不用紧张，这是正常的，等 Gemini CLI 第一次运行生成配置文件后，再回来看这里就变状态了。
3. CC-switch 配置实操：从新增到一键切换
3.1 添加第一套 Gemini CLI 配置
打开 CC-switch，选择 Gemini CLI 作为目标工具。这时候界面应该是一个配置列表，通常是空的。点击“新增”或“添加配置”，填写这些字段：
- 配置名称：随意写，方便认就行，比如“Gemini 官方”或“项目A专用”。
- Base URL：默认情况下填 Gemini API 的官方地址；如果你用的是别的兼容服务，则填对应的接口地址。
- API Key：填入之前创建的密钥。
- 模型：比如 gemini-2.5-pro、gemini-2.0-flash 之类的具体模型名。
- 其他可选字段：根据你自己的服务商文档决定，没有就不填。
我建议第一套配置先老老实实用官方地址，目的不是立刻满足多配置，而是先验证整个链路通不通。等官方配置稳定了，再去添加第三方兼容服务的方案。
不同字段的作用我整理成一张表：
| 字段 | 说明 | 示例 |
|---|---|---|
| 配置名称 | 方便自己识别 | 工作用 / 个人用 / 项目A专用 |
| Base URL | API 接口地址 | https://generativelanguage.googleapis.com 或兼容服务地址 |
| API Key | 访问凭据 | AIza... 开头的长字符串 |
| 模型 | 要使用的模型名 | gemini-2.5-pro / gemini-2.0-flash |
如果你用的是 DeepSeek 开放平台这样的国产模型服务，也想交给 CC-switch 来管，思路是一样的：在 CC-switch 里新增一条配置，把 Base URL 指向 DeepSeek 开放的兼容地址，模型名改成 deepseek-chat 之类的官方模型标识，然后切换过去就能被 Gemini CLI 识别。这样你就能在同一个终端工具里，按项目需求来回切换不同模型服务。
3.2 CC-switch 切换时到底改了什么
CC-switch 的核心操作就是切换。点击目标配置前面的开关或“启用”按钮，CC-switch 会把选中的配置自动写入对应 CLI 工具的参数文件。
以 Gemini CLI 为例，它的配置通常存在用户目录下的 .gemini 配置文件夹里。CC-switch 做的就是帮你定位那个文件，把 Base URL、API Key、模型等字段安全地替换进去。手工版本的步骤是：找到 settings.json，改内容，保存，重启。CC-switch 把这三步压缩成了一步。
切换完之后，怎么知道真的生效了？最简单的方法：打开终端，跑一句简单的命令让 Gemini CLI 输出配置信息；或者进到配置目录，手动查看 settings.json 里的字段是否变化。我平时会直接问 Gemini CLI 一句“你现在是什么模型”，它能答上来就说明切换成功。
这里有个重要的细节：CC-switch 只是改了配置文件，它不会主动重启当前终端里已经跑着的 Gemini CLI 进程。如果你已经开着一个 Gemini CLI 会话，切完配置之后，那个老会话用的还是旧配置。所以最佳实践是切换完配置后，把旧的命令行会话退出去，重新开一个新会话再干活。
3.3 多个配置并存的管理思路
多配几套之后，你会发现命名规范特别重要。我现在的习惯是“场景-模型-服务商”三段式，例如“work-pro-gemini”、“daily-flash-google”、“test-local-model”。这样一眼就能看清楚这套配置是给谁用的，避免临时切错。
另外，API Key 属于敏感信息，CC-switch 虽然做了本地保存，但我仍然建议：
- 不要把多个环境的 Key 混在一个配置里。
- 定期更换不再使用的 Key。
- 给不同项目开独立 Key，出问题方便单独吊销。
最后，推荐一个我自己坚持了很久的习惯：所有 AI 配置都定期备份。CC-switch 的配置列表是存在本地的，如果你的系统重置或换电脑，那套配置列表不会自动迁移。我的做法是把常用配置的字段（名称、Base URL、模型）整理成一个 JSON 文件放到自己的笔记仓库里，换机器时直接照着重新录入，几分钟搞定。
4. Gemini CLI 安装到实战：手把手跑通
4.1 npm 全局安装与两种认证方式
环境齐了，就可以装 Gemini CLI：
npm install -g @google/gemini-cli装完先验证版本：
gemini --version如果提示命令不存在，多半是 npm 全局安装目录没在 PATH 里。Windows 上需要手动把%APPDATA%\npm加进环境变量 Path；macOS 或 Linux 一般会自动配置，如果不行就检查 npm prefix。
首次运行gemini，它会询问你采用哪种登录方式。一种是 OAuth 登录，按提示跳到浏览器授权；另一种是用 API Key 认证。我日常更推荐 API Key 方式，因为 OAuth 的 token 有时效性，过期又要重新授权；API Key 稳定，配合环境变量也方便脚本调用。
设置环境变量：
- Windows PowerShell：
$env:GEMINI_API_KEY="你的key" - macOS / Linux：
export GEMINI_API_KEY="你的key"
如果你希望 key 永久生效，Windows 用户可以用setx GEMINI_API_KEY "你的key"；macOS 用户可以把 export 写进~/.zshrc；Linux 用户写进~/.bashrc。改完记得重新加载配置或者开新终端。
4.2 常用命令与参数一览
Gemini CLI 的日常使用，绕不开这几个参数。我整理成一张速查表，方便你贴到笔记里：
| 参数 | 作用 | 示例 |
|---|---|---|
/exit | 退出交互模式 | 在会话里输入/exit |
-p | 单次提问模式（prompt） | gemini -p "写一个快速排序" |
--model | 指定模型名 | gemini -p "你好" --model gemini-2.5-pro |
--output | 把结果写入文件 | gemini -p "生成 readme" --output README.md |
-i/--interactive | 强制进入交互模式 | gemini -i |
--help | 查看完整参数 | gemini --help |
单次提问模式是我用得最多的。它适合在脚本里调用，也适合快速确认“模型到底通没通”。比如你刚切完配置，最稳妥的验证方式就是跑一句gemini -p "回复OK两个字母"，看到正常返回，链路就是通的。
4.3 三个真实场景实战
场景一，分析项目结构。
cd 到项目根目录，执行：
gemini -p "分析当前目录下的项目结构，告诉我这个项目的技术栈和入口文件"Gemini CLI 会读取目录信息并给出结构化回答。这个命令在接手别人代码时尤其好用，十几秒就能对陌生项目有个大致认知。
场景二，解释一段报错。
把报错信息复制进命令：
gemini -p "下面这段报错是什么意思？如何修复：<粘贴报错>"它会先定位报错来源，再给修复建议。注意，别只丢一句“报错了”，要把完整的堆栈或错误码贴上去，信息越全，回答越准。
场景三，生成测试用例。
gemini -p "为 utils.ts 里的 formatDate 函数写一份 unit test，覆盖空输入、非法日期、正常日期三种情况"这类场景里最有用的诀窍是给足上下文。别光丢一句话“帮我看看代码”，而是说“当前目录是 xxx 仓库，入口是 main.py，我想让这个脚本支持 xxx，你先把核心函数找出来再给方案”。上下文越清晰，回答越靠谱。
4.4 VS Code Companion 联动
装好 Gemini CLI 之后，再去 VS Code 扩展市场搜“Gemini CLI Companion”，装好它。装完在左侧栏或底部面板找到 Companion 面板，它会自动识别终端里装好的 Gemini CLI，并建立会话。
在编辑器里的用法更顺手：
- 选中一段代码，右键选择“Explain”或“Ask Gemini CLI”。
- 在面板里直接提问，当前打开文件会自动作为上下文。
- 让它在编辑器里生成代码建议，你决定要不要接受。
这里有个容易踩的小坑：当你用 CC-switch 切换了配置之后，已经开着的 VS Code 进程不会立刻感知到，需要重载窗口（Ctrl+Shift+P输入 “Reload Window”）或等下次启动时再使用。否则你面板里看到的还是旧配置的会话。
5. 高频踩坑与排查记录
5.1 常见问题速查表
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 提示 node 不是内部或外部命令 | Node.js 没装或 PATH 没配好 | 重装 Node.js 并重启终端 |
| 提示 gemini 命令不存在 | npm 全局目录没在 PATH | 手动添加 npm 全局路径到 PATH |
| 401 或认证失败 | API Key 错误或环境变量未生效 | 重新 export 后重启终端，检查 Key 是否完整 |
| 模型名不识别 | 填了不存在的模型名 | 用gemini --help或官方文档确认模型名 |
| CC-switch 切了没生效 | 配置没写入目标文件 / 终端有缓存 | 查看 settings.json，重开终端 |
| VS Code 面板还是旧配置 | 编辑器缓存了会话 | Reload Window 重载 |
| 安装后启动闪退 | Node 版本过低 | 升级到 Node 20 或更高 |
这张表是我实际使用中碰到过的高频问题汇总。前三个问题占了七成情况，基本都出在环境变量上，别急着怀疑工具，先看变量。
5.2 我踩过的坑和一些操作小技巧
先说一个我实际损失过时间的坑。我之前给 Gemini CLI 配了一个“测试用”的 API Key，后来在 CC-switch 里也存了一份，两边都能用。结果某天我把 CC-switch 里那个配置改了，但终端里还残留着老的环境变量，导致同一个会话里一会儿是新 key 一会儿是旧 key，报错反复横跳。后来我养成了习惯：切换配置后，第一时间重启当前终端，并主动确认环境变量干净了才继续用。
第二个坑和 node 版本有关。有一次我机器上默认 node 是 16，虽然系统没报错，但 Gemini CLI 安装后启动就闪退。换了 nvm 切到 Node 20 之后一切正常。所以如果遇到奇怪的启动失败，先去查 node 版本，别一上来就重装包。
第三个技巧是：使用 Gemini CLI 时，如果拿到的回答不符合预期，不要急着换工具，先检查自己给的指令是不是太模糊。它和普通搜索引擎不一样，你给的信息越具体，它越能接近你要的答案。举例来说，“把这个函数改好”和“这个函数在并发场景下会丢更新，请加一个锁，并保持接口签名不变”是两种完全不同的效果。
6. 让这套组合更顺手的几个进阶玩法
6.1 用 nvm 管好 Node.js 版本
如果你同时在跑多个 Node 项目，强烈建议别直接在系统里装一个 Node 就用。Windows 用 nvm-windows，macOS 用 nvm，安装后可以随时切换 Node 版本：
nvm install 20 nvm use 20 node -vGemini CLI 需要一个相对新的 Node，而很多老项目可能又需要 Node 16，两者共存互不干扰的最好方式就是 nvm。这也是我在换机器后最先装的工具之一。
6.2 在项目里固定 Gemini CLI 配置
如果你有一些项目固定使用某个模型或 Base URL，可以在项目目录下建一个.gemini文件夹，把针对项目的配置放进去。这样切到不同仓库时，Gemini CLI 会自动加载对应的项目配置，而不是每次都沿用全局配置。配合 CC-switch 做更细粒度控制后，基本能做到“开箱即用”。
这个做法的好处是：团队协作时，你不需要每个人都在自己机器上手工改一套配置，只要项目里有约定好的配置结构，新同事 clone 下来就能跑。当然，涉及到密钥的部分仍然不建议直接提交到仓库，尽量用环境变量或本地 untracked 文件来保存。
6.3 和 Git 工作流结合的实际用法
最后分享一个我特别常用的组合拳。写完代码准备提交之前，用 Gemini CLI 生成 commit message：
git diff | gemini -p "根据这段 diff 帮我写一个简洁的 commit message，要求不超过20个字"还有 code review 场景：
git log --oneline HEAD~5 | gemini -p "帮我根据最近五条提交生成一个周报摘要"这些用法不需要额外装任何插件，只要 Gemini CLI 能跑就行。它把终端的标准输入和命令行模型结合得很自然，反而是最省事的用法。配合 CC-switch 在不同项目间切换配置后，你甚至可以做到每个项目提交信息风格统一，因为你可以给不同项目切换不同模型或不同规则。
我个人在实际操作中的体会是，CC-switch 和 Gemini CLI 这对组合真正解决的是“配置混乱”和“重复劳动”两个问题。工具本身都不复杂，关键是把配置流程固定成习惯：环境用 nvm 管，Key 用环境变量，切配置用 CC-switch，具体干活交给命令行里的 Gemini。任何一个环节断掉都会让人多花不少冤枉时间。如果你也在折腾这套环境，我建议先照着这篇把最小链路跑通，再根据自己项目慢慢加配置。有遇到新的坑也欢迎来交流，我后续会继续更新更细的场景用法。
