Gemini CLI

Gemini CLI 是 Google 推出的开源终端智能体，可以在终端中理解项目、分析文件并在获得授权后使用命令和工具。通过配置 Gemini API 地址、API Key 和模型 ID，可以让 Gemini CLI 使用 AGTCloud 的 Gemini Generate Content 兼容入口。

本教程只介绍 Gemini CLI 的基础连接与安全验证流程。文件修改、Shell 命令、函数调用和其他智能体能力取决于目标模型，以及对应模型对 Gemini Parts、Function Call 等协议结构的实际支持情况。

准备工作

开始前，请确认你已经：

• 安装 Node.js 20 或更高版本；
• 准备 Bash、Zsh 或 PowerShell 终端；
• 在 API Keys 页面创建 AGTCloud API Key；
• 从模型广场复制当前 Key 可见、且支持 Gemini Generate Content 的模型 ID；
• 准备一个不包含敏感代码和生产凭证的测试目录。

MODEL_ID 是需要替换的占位符，不是实际模型名称。请使用当前 API Key 可见且支持 Gemini Generate Content 的模型 ID。

安装 Gemini CLI

推荐安装当前稳定版本。不同安装方式得到的是同一个 gemini 命令。

npm install -g @google/gemini-cli

安装完成后检查版本：

gemini --version

如果提示找不到命令，请重新打开终端，并确认 npm 全局命令目录已经加入 PATH。

配置 AGTCloud

Gemini CLI 需要四个环境变量：API Key、模型 ID、自定义 Gemini API 地址和 Bearer 鉴权方式。

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

配置项说明

本教程不设置 GOOGLE_GENAI_API_VERSION，让 Gemini CLI 使用 Gemini API 默认的 v1beta。也不要把完整的 generateContent 请求路径写入 Base URL。

保存用户级配置

确认临时配置能够工作后，可以将变量写入 Gemini CLI 的用户级 .env 文件。该文件可能包含真实 API Key，请不要提交到代码仓库。

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI 会按当前工作目录和父目录查找环境文件。项目中更近的 .env 或 .gemini/.env 可能优先于用户级配置；发现配置没有生效时，应先排查这些文件。

固定 API Key 认证方式

Gemini CLI 支持多种 Google 认证方式。通过 AGTCloud 使用时，应选择 Gemini API Key，而不是 Google 登录或 Vertex AI。

在用户级 settings.json 中合并以下配置，不要覆盖文件中已有的主题、权限或其他设置：

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

配置文件位置：

保存后完全退出 Gemini CLI，再重新启动。selectedType 与 GEMINI_API_KEY_AUTH_MECHANISM=bearer 分别负责选择 API Key 认证流程和按 AGTCloud 要求生成 Bearer Header，二者不能相互替代。

选择模型

默认模型由 GEMINI_MODEL 决定。需要为单次会话临时指定模型时，可以运行：

gemini --model MODEL_ID

交互会话中的 /model 可以作为辅助入口，但其列表不一定自动包含当前 AGTCloud API Key 返回的所有模型。遇到模型不存在或不可见时，请从模型广场重新复制完整模型 ID，并优先通过 GEMINI_MODEL 或 --model 指定。

验证连接

gemini -p "请只回复：AGTCloud 连接成功。" --output-format json

gemini -p "@README.md 请用三点概括项目用途，不要修改任何文件。" --output-format json

gemini

常见问题

遇到无法定位的问题时，请记录请求时间、API Base URL、模型 ID、Gemini CLI 版本、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key 或包含凭证的 .env 文件。

安全建议

• 不要把真实 API Key 写入仓库、共享脚本、截图、日志或聊天记录；
• 建议先使用临时环境变量验证，成功后再保存用户级配置；
• 为 .env 文件设置合适的本机访问权限，并避免同步到公共云盘；
• 首次使用工具能力时保持人工审批，并在非生产项目中验证；
• 共享排障信息前，删除完整 Key、用户名、本地路径和业务源码。

下一步

• API Key、Base URL 与认证
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• 协议选择
• 错误与排障