Gemini CLI 使用指南:将 AI 助手集成到你的终端（含网络问题与常见错误解决）

对于开发者而言，命令行终端是我们最常打交道的工具之一。如果在终端中能直接调用强大的 AI 模型，无疑会极大地提升工作效率。Google 推出的 Gemini CLI 就是这样一款工具，它能将 Gemini 的能力无缝集成到你的命令行工作流中。

本文将详细介绍 Gemini CLI 的安装、配置过程，并分享我在使用中遇到的关键问题及其解决方案。

在安装 Gemini CLI 之前，请确保你的系统中已经安装了 Node.js。这是其运行的基础环境。你可以通过在终端执行以下命令来检查：

node -v

如果未安装，请前往 Node.js 官网下载并安装 LTS (长期支持) 版本。

安装 Gemini CLI 有两种方式：

临时使用 (npx)：这种方式无需全局安装，适合快速体验。每次使用时都会从网络获取最新版本。
```
npx @google/gemini-cli
```
全局安装 (npm)：（推荐） 对于长期使用者，建议采用全局安装。这样，你就可以在系统的任何路径下通过 gemini 命令直接启动它。
```
npm install -g @google/gemini-cli
```

重要提示： Gemini CLI 在首次启动和后续使用中需要验证 Google 账户，相关服务在国内无法直接访问。因此，必须为你的终端配置代理。

这是初次配置时最容易遇到的障碍。我的解决方案如下：

当 gemini 命令成功启动并弹出浏览器进行 Google 账户授权时，说明网络配置正确。

首次成功授权后，Gemini CLI 会引导你完成几个简单的初始化配置。

选择主题：根据个人偏好选择一个命令行界面的颜色主题。
选择认证方式：
- Sign in with your Google Account: 我选择此项。通过浏览器登录 Google 账户完成认证，流程简单直观。
- Use an API Key: 你也可以前往 Google AI Studio 生成一个 API 密钥，并在此处粘贴。这种方式更适合自动化脚本或无浏览器环境。

完成这些步骤后，你就可以正式开始使用了。

在终端输入 gemini 并回车，即可进入交互模式。其输入方式非常灵活：

直接输入问题：进行常规的问答对话。
@ 符号：分析文件与目录：这是 Gemini CLI 的一个核心功能，可以直接引用本地文件或文件夹作为上下文。
- 示例：@./src/utils.js 解释这段代码的功能。
- 示例：@./project_docs 总结这个目录下的所有文档。
/ 命令：使用内置功能：输入 / 可以查看并使用内置命令，如：
- /theme: 切换主题。
- /editor: 开启多行编辑模式，方便粘贴和编辑大段代码或文本。
- /help: 查看帮助文档。
! 符号：结合 Shell 命令：将标准 Shell 命令的输出结果作为输入，直接传递给 Gemini 进行处理。
- 示例：!git diff | gemini 为这些变更生成一个合适的 commit message。
- 示例：!ls -l | gemini 解释这些文件权限的含义。

在使用过程中，你可能会遇到 Gemini CLI 运行一段时间后自动退出的问题。

原因分析：该问题是由于 Gemini CLI 默认会定时发送匿名的使用情况统计（Telemetry）到 Google 服务器。在网络不稳定的情况下，该请求失败会导致程序异常终止。

解决方案：关闭该统计功能即可。

找到配置文件 settings.json。
- Windows: C:\Users\<你的用户名>\.gemini\settings.json
- macOS/Linux: ~/.gemini/settings.json
使用文本编辑器打开该文件，添加以下字段并保存：
```
"usageStatisticsEnabled": false
```

修改配置后，重新启动 gemini，程序即可稳定运行。

通过以上步骤，你就可以将 Gemini CLI 顺利地集成到日常的开发工作中。它能够有效减少在不同应用间切换的频率，无论是代码解读、文档生成还是命令查询，都能在终端内一站式完成。

希望这篇指南能帮助你顺利地使用 Gemini CLI。如果你有其他使用技巧，也欢迎交流。