使用 AIMax 配置 Gemini CLI

Gemini CLI 是 Google 的终端开发工具。它可以通过 Gemini 原生协议访问 AIMax 的文本模型；本文不把某个 CLI 版本或某个模型版本作为使用前提。

本文覆盖 API Key、Base URL、模型发现和纯文本验证。工具调用、浏览器能力、扩展、MCP 和多回合 Agent 工作流需要在目标模型上分别验证。

准备工作

按 Gemini CLI 官方安装说明安装 gemini 命令。
获取 AIMax API Key。
确认 API Key 能看到至少一个 Gemini 模型。

先查询当前 Key 可见模型：

export AIMAX_API_KEY="YOUR_API_KEY"
export AIMAX_BASE_URL="https://your-domain"

curl --request GET \
  --url "$AIMAX_BASE_URL/v1/models" \
  --header "Authorization: Bearer $AIMAX_API_KEY"

从返回的 data[].id 中选择模型，并保存为环境变量：

export AIMAX_MODEL="MODEL_FROM_MODELS"

环境变量配置

Gemini CLI 使用以下环境变量：

export GEMINI_API_KEY="$AIMAX_API_KEY"
export GOOGLE_GEMINI_BASE_URL="$AIMAX_BASE_URL"

GOOGLE_GEMINI_BASE_URL 填服务根地址，例如 https://your-domain。不要在这里追加 /v1beta，Gemini CLI 会自行拼接：

/v1beta/models/{model}:generateContent

如果当前 Shell 已经存在 Google 官方的 GEMINI_API_KEY，请先确认它没有覆盖 AIMax Key：

env | rg '^(GEMINI_API_KEY|GOOGLE_GEMINI_BASE_URL)='

最小验证

用只读、单轮文本任务验证：

gemini \
  -p "只回复 OK，不要调用任何工具。" \
  -m "$AIMAX_MODEL" \
  --approval-mode plan \
  --skip-trust \
  --output-format json

成功时应能在 JSON 中看到模型返回的 OK。如果需要换模型，只修改 AIMAX_MODEL，不需要重写 Base URL 或认证配置。

常见问题

返回无效 URL

确认 GOOGLE_GEMINI_BASE_URL 是服务根地址，不要写成：

https://your-domain/v1beta
https://your-domain/v1

否则 CLI 自动拼接路径后可能形成重复路径。

返回认证失败

确认 Gemini CLI 使用的是 GEMINI_API_KEY。
确认 Key 没有前后空格或换行。
确认没有被其他 Shell 配置或项目 .env 覆盖。

模型不可用

重新调用 GET /v1/models。
使用返回的完整模型标识，不要自行改写模型名。
确认目标模型支持 Gemini 原生 generateContent 入口。

工具调用失败

先用纯文本任务确认认证、路径和模型都正常，再单独验证工具调用、MCP、浏览器或扩展能力。文本响应成功不等于这些能力已经可用。

集成总览

聊天应用

开发工具

Agent 应用

应用平台

Gemini CLI

使用 AIMax 配置 Gemini CLI

准备工作

环境变量配置

最小验证

常见问题

返回无效 URL

返回认证失败

模型不可用

工具调用失败

协议参考

​使用 AIMax 配置 Gemini CLI

​准备工作

​环境变量配置

​最小验证

​常见问题

​返回无效 URL

​返回认证失败

​模型不可用

​工具调用失败

​协议参考

使用 AIMax 配置 Gemini CLI

准备工作

环境变量配置

最小验证

常见问题

返回无效 URL

返回认证失败

模型不可用

工具调用失败

协议参考