本文首发【零一探秘】公众号
谷歌新出的开源AI编程工具 Gemini-CLI再次引爆互联网，短短两天的时间github star已经达到了36k。我在完整体验这个工具后，整理了Gemini-CLI的基础命令、高阶用法（包括配置mcp、项目的规则约束文件gemini.md）以及记忆管理等方面，另外在使用过程中踩过的一些坑以及对应的解决方案。
Gemini-CLI安装与身份验证
先说一下gemini cli的安装，官方默认提供了以下两种安装方式：
- 全局安装：npm install -g @google/gemini-cli
- 直接运行：npx github.com/google-gemi…
重要： 我在体验之后，发现gemini官方在短短两天内发布了四个版本（主要是对gitbub issues用户反馈的一些问题进行修复），由于目前Gemini-CLI的bug较多而且不太稳定，建议大家安装的时候使用以下命令直接安装最新的版本：
npm install -g @google/gemini-cli@latest
安装完成后，运行gemini命令启动，首次启动需要进行身份验证的设置，官方提供了3种验证方式：
1. Google 登录（推荐） ： 启动 CLI 后选择 Google 登录选项，浏览器会自动跳转到认证的页面，按照指示一步步完成即可，完成认证后身份凭据会缓存在本地；
注意： 如果你是Google Workspace 账户的话，需要配置Google Cloud Project 可以执行*export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"*这种方式进行临时配置， 也可以基于以下命令进行永久设置：
echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
source ~/.bashrc
2. Gemini API 密钥： 可以通过访问Google AI Studio的网址aistudio.google.com/app/apikey申… KEY，每日有一定的免费调用额度。采用这种方式的话，我们需要设置环境变量：
#临时设置
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
#永久设置：
echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
source ~/.bashrc
3. Vertex AI： 这种方式适用于企业用户，通过以下方式进行设置：
非 Express 模式配置：
# 设置 Application Default Credentials
gcloud auth application-default login
# 设置环境变量
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1" # 或其他区域
export GOOGLE_GENAI_USE_VERTEXAI=true
Express 模式配置：
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
常用命令使用说明
/chat：
这个命令主要是用于管理对话聊天记录，比如我们在退出命令行终端时，可以使用 /save + tag 把当前对话加上标签。当下一次启动cli工具时，就可以用 /chat resume tag 来恢复对话，也可以使用用 /chat list 来列出记录的对话
/compress： 用于压缩当前的对话上下文为摘要,节省input token,我在执行后 ✦ Chat history compressed from 2644 to 195 tokens. 节省了超过 90% 的 input token
@命令：
@的作用是在命令行终端注入文件或目录内容,下面我给出了几个使用示例:
# 分析单个文件
@src/components/Button.tsx 这个组件有什么问题？
# 分析整个目录
@src/ 总结这个项目的结构
# 分析多个文件
@package.json @README.md 分析项目配置
# 处理空格路径
@My\ Documents/file.txt 分析这个文件
在gemini-cli中执行@命令时，会自动忽略.gitignore 中的文件
Shell 命令 (!) :
可以通过!切换来执行系统命令,以下是几个使用示例:
# 执行单个命令
!git status
# 切换到 Shell 模式
!
# 现在处于 Shell 模式，直接输入命令
ls -la
git log --oneline
# 再次输入 ! 退出 Shell 模式
!
介绍完常用的一些基础命令后,下面给大家介绍一些高阶用法:
Gemini-CLI高级功能
MCP设置
这里我给大家演示一下如何在Gemini-CLI中添加mcp server。 由于我使用的是mac环境，全局的配置位于~/.gemini/settings.json这个文件中。 首先我打开cursor IDE的mcp.json,将squential-thinking这个mcp工具的配置进行复制：
然后添加到~/.gemini/settings.json文件中：
在命令行执行*/mcp schema*可以看到已经成功运行：
GEMINI.md 文件（项目规则约束）
在Gemini-CLI中,我们怎么添加类似cursor IDE中的项目规则约束mdc文件呢? 可以通过 GEMINI.md 提供项目特定的指令、规则约束和上下文。
添加方式有两种：一是全局添加，在~/.gemini/GEMINI.md文件中添加；二,我们在进行项目开发过程中，一般通过在项目根路径下创建GEMINI.md文件来添加规则；以下是我给出的一个示例
## 严格遵循的指令
1. 请你用简体中文与用户交流。
2. 你必须在每次对话前**仔细**阅读你的内部规则，这很重要，否则整个工作流程都无法继续。
3. 仔细理解用户的意图，当你认为用户的意图是一次大需求时，请合理规划最佳路径。必要时可以在创建一个 TODO 任务来跟踪这个需求的进展，你需要使用记忆工具来创建和管理这些任务。
4. 请确保在每次对话开始前检查记忆中是否存在与当前会话相关的未完成任务。当存在未完成任务时，请在对话中持续跟踪。每当一个任务完成后，必须在回答结束前通过记忆工具来更新任务状态。
## 项目开发规范
- 使用 TypeScript 5.0+
- 遵循 ESLint 配置
- 所有函数需要 JSDoc 注释
- 接口名称以 `I` 开头
- 私有成员以 `_` 开头
## 项目结构
- `src/`: 源代码
- `tests/`: 测试文件
- `docs/`: 文档
- `dist/`: 构建输出
## 特殊说明
当修改 API 时，务必更新相应的类型定义和测试用例。
在这里，我推荐采用第二种方式来指定项目的技术栈以及开发规范，从而约束LLM的行为。
记忆管理命令/memory
通过使用*/memory*命令可以对全局以及项目路径下的记忆文件进行管理，以下是相关的命令：
# 查看当前记忆
/memory show
# 刷新记忆内容
/memory refresh
# 添加临时记忆
/memory add 这个项目使用 React 18
踩坑指南及修复建议
我在使用过程中还是踩了不少坑，下面我总结了几种频繁出现的问题以及对应的解决方案，提供给大家作为参考：
Gemini CLI 出现闪退的情况
很多用户反馈使用 Gemini CLI 出现闪退的情况，我最开始使用时也经常出现，以下是解决办法： 把 { "usageStatisticsEnabled": false } 加到 ~/.gemini/settings.json（或项目根目录 /.gemini/settings.json）后，CLI 就会停止向 Google 的 Clearcut 服务上报匿名使用统计，从而绕过当前导致“20 秒左右就闪退/自动退出”的遥测网络错误。
这是官方文档里列出的“退出遥测（usage statistics）”开关。
为什么它能解决闪退？ 最近的 bug 报告显示，CLI 每隔一段时间尝试把遥测日志 POST 到 play googleapis com；在网络异常时，这个 Promise 被拒绝却没有被正确捕获，进程就直接崩溃。
关闭 usageStatisticsEnabled 后，这些请求不会再发出，CLI 也就不会异常退出。
触发速率限制后，CLI 工具不断循环切换模型并卡住
github issues: github.com/google-gemi…
当用户请求过多时，gemini-cli 会一直显示如图中的错误提示,这个提示会每隔一分钟左右在控制台重复出现，程序陷入死循环，无法正常响应。
按照官方回应的说法是产品上线初期访问量远超预期，导致内部容量超载，触发了速率限制和模型切换逻辑异常。
解决方案： 使用以下命令升级到0.1.4+以上版本
npm install -g @google/gemini-cli@latest
gemini --version
Gemini 2.5 Pro API 返回 429 错误（请求过多）
使用 gemini-2.5-pro 时，API 返回 429 Too Many Requests 错误，提示资源耗尽（Resource has been exhausted）。
解决方案：
- 升级 gemini-cli 到最新版本，命令和上面一样
- 删除环境变量
GEMINI_API_KEY和GOOGLE_CLOUD_PROJECT,用Google 账号重新登录 gemini-cli
如果遇到使用过程中自动切换到 flash 2.5 模型的情况，可以使用gemini api key的方式或者在启动时手动指定模型版本
gemini-cli --model gemini-2.5-pro
写在最后
最后说说我使用gemini-cli的体验使用感受： 对比Claude code来说，整体UI风格很不错，默认配色挺舒服的，diff 页面也很好看，支持多种主题可以选择； 可以配置项目记忆文件这一点很好！ 另外就是每天可以白嫖每分钟 60 次，每天1000次使用，我想这也是gemini-cli一出来就爆火的原因吧😄 今天的分享就这么多，期待后续gemini-cli更稳定的1.0版本~
