Gemini CLI 安装与配置
Gemini CLI 是 Google 开源的终端 AI 代理。它支持 Google 登录、Gemini API 密钥和 Vertex AI；本页另说明如何使用 Ya Code 提供的 Gemini 原生兼容地址。
一、准备工作
- 安装 Node.js 20 或更高版本。通过 Homebrew 安装的 macOS 用户可不单独使用 npm 全局安装。
- 使用 Google 服务时准备 Google 账户、Google AI Studio API 密钥或 Vertex AI 项目；使用 Ya Code 时先创建访问密钥。
- 确认终端能够运行
node -v和npm -v。 - 版本要求可能更新，请同时查看 Gemini CLI 官方仓库 和安装文档。
二、安装（macOS、Windows）
macOS
使用 npm：
bash
npm install -g @google/gemini-cli
gemini --version或使用官方支持的 Homebrew formula：
bash
brew install gemini-cli
gemini --version不希望全局安装时可直接运行：
bash
npx @google/gemini-cliWindows
在 PowerShell 或 Windows Terminal 中运行：
powershell
npm install -g @google/gemini-cli
gemini --version如果 PowerShell 阻止 npm 生成的脚本，可运行 gemini.cmd，或在符合组织策略的终端中执行；不要为此随意放宽全局执行策略。
三、配置目录（macOS、Windows）
macOS
- 用户设置：
~/.gemini/settings.json - 用户环境文件：
~/.gemini/.env - 项目设置：
<项目目录>/.gemini/settings.json - 项目环境文件：
<项目目录>/.gemini/.env
Windows
- 用户设置：
%USERPROFILE%\.gemini\settings.json - 用户环境文件：
%USERPROFILE%\.gemini\.env - 项目设置：
<项目目录>\.gemini\settings.json - 项目环境文件：
<项目目录>\.gemini\.env
目录不存在时可以手动创建。用户设置使用 JSON，环境文件使用 KEY=VALUE 格式。设置层级和环境文件查找规则会随版本演进，请以 Gemini CLI 配置文档 为准。
四、配置文件示例
连接 Ya Code 时，在用户级或项目级 .gemini/.env 中写入：
dotenv
GEMINI_API_KEY=sk-your-yacode-key
GOOGLE_GEMINI_BASE_URL=https://yacode.xyzsettings.json 用于界面和工具行为。下面是一个不包含凭据的最小示例；具体可用字段应以当前版本的 /settings 界面和官方配置文档为准：
json
{
"general": {
"vimMode": false
}
}配置后在项目目录运行：
bash
gemini五、配置说明
GEMINI_API_KEY用于 Gemini API 密钥认证；这里填写的是 Ya Code 密钥，而不是 Google OAuth 凭据。GOOGLE_GEMINI_BASE_URL把请求指向 Ya Code 的 Gemini 原生兼容接口。Ya Code 当前约定的根地址为https://yacode.xyz。- 使用 Google 官方服务时，不要设置自定义地址。运行
gemini后可以选择 Google 登录、Gemini API Key 或 Vertex AI，具体变量见 Gemini CLI 认证文档。 .env是环境变量文件，settings.json是 JSON 设置文件，两者用途不同。含密钥的项目.env必须加入.gitignore。
六、注意事项
sk-your-yacode-key是占位值；不要把真实密钥提交到仓库或粘贴到问题报告中。- Gemini CLI 不同版本对自定义基础地址、认证变量和设置 schema 的处理可能变化。升级后应先运行
gemini --version，并用一个非敏感请求验证兼容性。 - Ya Code 需要提供 Gemini 原生格式和相应模型；OpenAI 兼容地址不能自动等同于 Gemini 原生接口。若遇到模型或认证错误，请以 Ya Code 当前模型列表为准。
- Gemini CLI 可调用 Shell 和文件工具。处理不可信项目时，先审查上下文文件和工具确认策略。