切换深浅色
Gemini CLI 接入 XXAPI
让 AI 帮你完成配置
首次安装或切换到 XXAPI，都可以使用。
AI 打不开链接时，。
查看短提示词
Gemini CLI 是 Google 的终端助手，可以读取文件、分析项目和执行任务。下面使用它内置的 API Key 认证，把模型请求发送到 XXAPI。
准备 Node.js LTS、XXAPI Key，以及支持 Gemini 原生协议的模型。只有 OpenAI 兼容接口的 Gemini 渠道，应改用 Cherry Studio；两种接口不能只靠更换模型名互相代替。
1. 选择模型和密钥
打开 模型广场，查看目标模型的接口说明，确认包含 Gemini 原生接口，再复制模型 ID。到 API 密钥 创建该分组的 Key。
查看当前可用模型与分组从 XXAPI 后台读取
选择与你的 API Key 相同的分组，再复制模型名称。
这里的服务器地址用根域 https://xxapi.ai。Gemini CLI 会自行添加 API 版本和模型路径，不需要填 /v1 或 /v1beta。
✓ 完成标志
已准备支持 Gemini 原生协议的模型 ID 和对应 Key。
2. 检查 Node.js
Windows 默认按 PowerShell 步骤操作。如果你已经在 WSL 里工作，请全程使用 Linux 步骤；安装、Key 和配置都放在 WSL 的 Linux 用户目录中。
Windows 打开 PowerShell，macOS / Linux 打开终端，依次输入下面两行。
sh
node --version
npm --versionNode.js 至少需要 20，建议安装当前 LTS。命令找不到时，先看 安装环境。官方推荐系统为 Windows 11 24H2 及以上、macOS 15 及以上或 Ubuntu 20.04 及以上。
✓ 完成标志
node 与 npm 都显示版本号。
3. 安装 Gemini CLI
继续在终端执行。
sh
npm install -g @google/gemini-cli装完重新开终端，检查版本。
sh
gemini --versionWindows 若提示 npm.ps1 被禁止，把安装命令开头换成 npm.cmd。如果之后提示 gemini.ps1 被禁止，将本页的 gemini 命令写成 gemini.cmd 即可。
✓ 完成标志
gemini --version 显示版本号。
4. 填入地址、密钥和模型
把两个占位值换成自己的 Key 与模型 ID，按系统选择一段执行。
Windows PowerShell
powershell
$env:GOOGLE_GEMINI_BASE_URL = "https://xxapi.ai"
$env:GEMINI_API_KEY = "替换为你的XXAPI_API_Key"
$env:GEMINI_MODEL = "替换为模型广场中的Gemini模型ID"macOS / Linux
bash
export GOOGLE_GEMINI_BASE_URL="https://xxapi.ai"
export GEMINI_API_KEY="替换为你的XXAPI_API_Key"
export GEMINI_MODEL="替换为模型广场中的Gemini模型ID"以前用 Google 登录或配过其他中转站
备份 ~/.gemini/settings.json，以及自己曾编辑过的 .gemini/.env。检查里面是否还有旧地址、Key 或模型。
启动后输入 /auth，把认证方式切换为 Use Gemini API key。Google 登录和 Vertex AI 路径不使用本页的网关设置。不要直接删除整个 .gemini 目录，里面还有其他个人设置。
✓ 完成标志
当前窗口中已填好三项值，没有多加路径。
5. 进入练习文件夹并启动
Windows PowerShell
powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\xxapi-demo" | Out-Null
Set-Location "$env:USERPROFILE\xxapi-demo"
geminimacOS / Linux
bash
mkdir -p ~/xxapi-demo
cd ~/xxapi-demo
gemini第一次出现认证选择时，选择 Use Gemini API key。它会读取第 4 步的 Key。遇到文件夹信任提示，核对是练习目录后再继续。
✓ 完成标志
已进入 Gemini CLI 的输入框，当前模型与第 1 步一致。
6. 发一条消息，核对请求
输入下面这句并发送。
text
请只回复“连接成功”，先不要调用工具或修改文件。收到回复后，在 XXAPI 的使用日志中核对时间与模型。模型选择器里出现名称，只说明你选中了它；实际回复和记录能确认这次调用是否成功。
✓ 完成标志
收到回复，XXAPI 中出现刚才的请求。
7. 保存设置或开始正式使用
先退出 Gemini CLI，进入自己的项目文件夹，再运行 gemini。如果你仍使用同一个终端，刚才的配置会继续生效。
下次打开终端也想保留配置
可以把下面三行存入个人 ~/.gemini/.env，Windows 对应 %USERPROFILE%\.gemini\.env。已经有文件时只修改同名项。
dotenv
GOOGLE_GEMINI_BASE_URL=https://xxapi.ai
GEMINI_API_KEY=替换为你的XXAPI_API_Key
GEMINI_MODEL=替换为模型广场中的Gemini模型ID此文件包含 Key，放在自己的用户目录，别放进项目仓库。已有项目 .env 可能影响读取结果；每次更换配置后先新开会话核对模型与 XXAPI 使用日志。
✓ 完成标志
可以在选定项目中发起新会话，配置仍指向 XXAPI。
常见问题
返回 404 或提示不支持 generateContent
检查 Base URL 只到根域，然后确认分组支持 Gemini 原生协议。把 OpenAI 的 /v1 地址填进 Gemini CLI 会走错路径。
仍打开 Google 登录网页
在 CLI 中用 /auth 选择 Use Gemini API key。确认启动发生在设置了第 4 步变量的终端里。
基础对话可以，搜索或工具调用失败
这些能力需要客户端、模型与渠道共同支持。先记录报错对应的功能和模型，再检查模型说明。不要通过开启全部权限来处理接口不兼容问题；需要图形聊天时可改用 Cherry Studio 的 OpenAI 兼容模式。