通过 AGIPower 使用 Gemini CLI 指南

Gemini CLI 是 Google 推出的开源 AI 终端代理工具，可以将 Gemini 的能力直接带入您的终端。它基于 ReAct（Reason + Act）循环架构，能够自主完成编程、调试、文件操作、内容生成等复杂任务。Gemini CLI 提供了 100 万 Token 上下文窗口、60 次/分钟的请求速率，以及丰富的 MCP 工具集成能力。通过 AGIPower，您可以为 Gemini CLI 配置自定义 API 端点，获得更灵活的模型选择和更稳定的服务体验。

前置条件

Node.js 18+ 环境
AGIPower API Key（参见下方获取 AGIPower API Key）

安装 Gemini CLI

npm（推荐）

npm install -g @google/gemini-cli

pnpm

pnpm install -g @google/gemini-cli

npx（免安装试用）

npx @google/gemini-cli

验证安装：

gemini --version

安装完成后，在终端中输入 gemini 即可启动。

获取 AGIPower API Key

订阅制 API Key（推荐）

适用场景：个人开发、学习探索、轻量团队协作
特点：固定月费、成本可预测
API Key 格式：sk-ss-v1-xxx

获取方式：
1. 访问 https://agipower.ai/platform/subscription
2. 选择合适套餐
3. 在控制台创建订阅 API Key

按量付费 API Key

适用场景：生产环境、商业产品、企业应用
特点：按实际使用量计费、便于统一成本核算
API Key 格式：sk-xxx

获取方式：
1. 访问 https://agipower.ai/platform/pay-as-you-go
2. 充值账户
3. 在控制台创建按量付费 API Key

配置方案

配置简洁，仅需 3 个环境变量即可快速接通。

Step 1: 创建配置目录

mkdir -p ~/.gemini

Step 2: 配置环境变量

您可以通过 ~/.gemini/.env 文件配置环境变量。Gemini CLI 会自动从该文件加载：

GEMINI_API_KEY=sk-ss-v1-xxx  # [!code highlight]
GEMINI_MODEL=google/gemini-2.5-pro  # [!code highlight]
GOOGLE_GEMINI_BASE_URL=https://api.agipower.ai  # [!code highlight]

也可以在 shell 配置文件中设置：

macOS/Linux/WSL

# 编辑 ~/.zshrc 或 ~/.bashrc 文件
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GEMINI_MODEL="google/gemini-2.5-pro"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"

Windows PowerShell

# 编辑 PowerShell 配置文件
$env:GEMINI_API_KEY = "sk-ss-v1-xxx"
$env:GEMINI_MODEL = "google/gemini-2.5-pro"
$env:GOOGLE_GEMINI_BASE_URL = "https://api.agipower.ai"

# 若需永久生效，请添加到 PowerShell 配置文件中：
# notepad $PROFILE

请确保将 sk-ss-v1-xxx 替换为您的真实 AGIPower API Key。您可以在 AGIPower 控制台中获取 API Key。

Step 3: 配置 settings.json

将认证方式设置为 Gemini API Key，避免 Gemini CLI 启动时要求 Google 登录：

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

GEMINI_API_KEY：您的 AGIPower API Key
GEMINI_MODEL：指定使用的模型，可以是 AGIPower 支持的 Google 模型
GOOGLE_GEMINI_BASE_URL：AGIPower Vertex AI 兼容端点
selectedType：认证方式，设置为 gemini-api-key 跳过 Google 登录

Step 4: 验证连接

# 重新加载配置文件（如使用 shell 配置方式）
source ~/.zshrc  # 或 source ~/.bashrc

# 最小冒烟测试
gemini -p "Reply with OK only." --output-format json

如果返回结果中包含 "response": "OK"，说明基础链路已通。继续测试只读文件分析：

# 进入任意项目目录
cd my-project

# 引用文件进行分析
gemini -p "@README.md Summarize this file in one sentence." --output-format json

如果能正确读取文件并返回摘要，说明 AGIPower + Gemini CLI 的只读分析链路可用。

认证方式

Gemini CLI 原生支持多种认证方式：

方式	适用场景	说明
Google 账号登录（OAuth）	本地开发	最高免费额度：60 RPM / 1000 RPD
API Key	CI/CD、脚本	通过 `GEMINI_API_KEY` 环境变量设置

通过 AGIPower 使用时，选择 API Key 方式，将 AGIPower API Key 设置到 GEMINI_API_KEY 环境变量即可。如需重新认证，可使用以下命令：

gemini --reauth

核心功能

GEMINI.md 上下文文件

GEMINI.md 是 Gemini CLI 的核心特性之一，类似于 Claude Code 的 CLAUDE.md。它作为持久化上下文，在每次会话开始时自动加载，让 AI 了解项目背景和约定。 Gemini CLI 按以下层级查找并合并 GEMINI.md 文件：

位置	作用域	说明
`~/.gemini/GEMINI.md`	全局	适用于所有项目的通用指令
`项目根目录/GEMINI.md`	项目级	项目特定的规范和约定
`当前目录/GEMINI.md`	目录级	子目录特定的上下文

描述项目的技术栈和架构
指定代码风格和命名规范
说明构建、测试和部署流程
列出常用的项目命令
支持通过 @path/to/file.md 语法导入其他文件

常用斜杠命令

Gemini CLI 提供了丰富的内置命令来管理会话和配置：

命令	说明
`/help`	显示帮助信息和可用命令列表
`/stats`	查看当前会话的 Token 使用情况和统计信息
`/memory show`	查看当前加载的 GEMINI.md 上下文内容
`/memory add <文本>`	向 AI 记忆中添加内容
`/theme`	切换 UI 主题
`/tools`	查看当前可用的工具列表
`/mcp`	管理 MCP 服务器连接
`/chat`	保存和恢复会话历史
`/copy`	将最后的输出复制到剪贴板

自定义斜杠命令

Gemini CLI 支持创建自定义命令，存放在以下位置：

全局命令：~/.gemini/commands/ — 在所有项目中可用
项目命令：<项目根目录>/.gemini/commands/ — 仅在当前项目中可用

例如，创建一个 /plan 命令：

# ~/.gemini/commands/plan.toml
[command]
description = "Plan changes without implementing"

[command.prompt]
content = """
Please analyze the following request and provide a detailed step-by-step plan.
Do NOT implement any changes — only plan them.

Request: $input
"""

MCP 集成

Gemini CLI 支持 MCP（Model Context Protocol）服务器，可以扩展 AI 的工具能力：

# 添加 MCP 服务器
gemini mcp add <server-name> -- <command>

# 查看已配置的 MCP 服务器
gemini mcp list

# 移除 MCP 服务器
gemini mcp remove <server-name>

在 settings.json 中也可以配置 MCP 服务器：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

非交互模式

Gemini CLI 支持非交互调用，适合脚本和 CI 场景：

# 单次问答，JSON 格式输出
gemini -p "解释什么是 REST API" --output-format json

# 引用文件进行分析
gemini -p "@src/main.ts 这个文件的入口逻辑是什么？" --output-format json

支持的模型

通过 AGIPower，您可以在 Gemini CLI 中使用多种 Gemini 模型。可以通过 GEMINI_MODEL 环境变量指定模型：

# 在 .gemini/.env 或 shell 配置文件中设置
export GEMINI_MODEL="google/gemini-2.5-pro"

推荐用于 Gemini CLI 的模型：

模型名称	模型 Slug	说明
Gemini 2.5 Pro	`google/gemini-2.5-pro`	Google 主力模型，推荐首选
Gemini 2.5 Flash	`google/gemini-2.5-flash`	注重响应速度，适合快速迭代

通过 AGIPower 模型列表查看 Google AI 协议可用模型
使用模型的 slug 名称（如 google/gemini-2.5-pro）
如需指定特定供应商，请参考 Provider Routing 文档

即使模型名可以切换成功，也不代表工具调用会一并可用。当前限制主要来自 AGIPower 对 Gemini CLI Agent 协议的兼容性，而不只是模型本身。

已知问题：工具调用报错 \

当模型尝试使用内置工具（如 Google Search）时，可能出现以下报错：

[API Error: {"error":{"code":"400","type":"invalid_params","message":"Invalid JSON payload received. Unknown name \"id\" at 'contents[...].parts[0].function_response': Cannot find field."}}]

原因：Gemini CLI 在向 API 发送工具调用结果时，会在 functionResponse 中携带 id 字段。该字段在部分 API 版本中尚未支持，导致请求被拒绝。

临时解决方案：修改 Gemini CLI 本地安装文件，注释掉 callId 的传递。

找到文件（路径中的 Node 版本号请替换为您的实际版本）：

~/.nvm/versions/node/<版本号>/lib/node_modules/@google/gemini-cli/node_modules/@google/gemini-cli-core/dist/src/core/turn.js

找到 handlePendingFunctionCall 方法（约第 183 行），将 callId, 注释掉：

handlePendingFunctionCall(fnCall, traceId) {
    const name = fnCall.name || 'undefined_tool_name';
    const args = fnCall.args || {};
    const callId = fnCall.id ?? `${name}_${Date.now()}_${this.callCounter++}`;
    const toolCallRequest = {
        // callId,  // [!code warning]
        name,
        args,
        isClientInitiated: false,
        prompt_id: this.prompt_id,
        traceId,
    };

保存文件后重启 Gemini CLI 即可。

每次更新或重装 Gemini CLI 后需要重新执行此修改
后续 AGIPower 补齐 function calling 兼容性后将自动支持，届时无需此修改

故障排除

常见问题解决

Gemini CLI 启动后要求 Google 登录

问题：启动 Gemini CLI 时弹出 Google OAuth 登录页面 解决方案：

检查 ~/.gemini/settings.json 中的 selectedType 是否正确设置为 "gemini-api-key"
使用 cat ~/.gemini/settings.json 验证配置内容

API Key 错误

问题：提示 API Key 无效或未授权 解决方案：

检查 API Key 是否正确（订阅制以 sk-ss-v1- 开头，按量付费以 sk- 开头）
确认 API Key 已激活且有足够余额
在 AGIPower 控制台中验证 Key 状态

连接失败问题

问题：Gemini CLI 无法连接到 AGIPower 服务 解决方案：

检查网络连接是否正常
验证 Base URL 是否配置正确为 https://api.agipower.ai
确认防火墙设置是否阻止了外部连接
尝试使用 curl https://api.agipower.ai/v1/models 测试连接

.env 配置文件不生效

问题：在 ~/.gemini/.env 中设置了变量但未生效 解决方案：

Gemini CLI 的 .env 加载遵循就近原则，命中第一份即停止
检查当前项目目录下是否已有 .env 或 .gemini/.env（会覆盖全局配置）
检查 Shell 中是否已 export 过同名变量：env | grep -E "GEMINI_|GOOGLE_"
检查父目录中是否存在更早命中的 .env 文件
重新打开终端窗口，或执行 source ~/.zshrc 重新加载配置

改文件时报 function_response 相关错误

问题：尝试让 Gemini CLI 自动编辑文件时出现类似错误：

Invalid JSON payload received. Unknown name "id" at 'contents[3].parts[0].function_response': Cannot find field.

解决方案：

这是已知限制，详见工具调用报错章节
当前请将使用场景限制为问答和只读分析
不要依赖 Gemini CLI 完成自动编辑、命令执行等 Agent 操作
后续 AGIPower 补齐 function calling 兼容性后将自动支持

模型不可用

问题：使用某个模型时提示模型不可用或不支持 解决方案：

访问 AGIPower 模型列表确认模型是否可用
检查 GEMINI_MODEL 环境变量中的模型名拼写是否正确
尝试使用 google/gemini-2.5-pro 等默认模型进行测试
确认您的账户是否有权限访问该模型

请求偶发超时

问题：只读文件分析请求偶尔超时 解决方案：

重试通常可成功
缩小 prompt 和引用文件的范围
如频繁超时，尝试换用较小的模型（如 google/gemini-2.5-flash）
检查网络连接是否稳定

沙盒模式问题

问题：启用沙盒模式后命令执行失败 解决方案：

确认系统中已安装 Docker
检查 Docker 服务是否正在运行：docker ps
尝试禁用沙盒模式测试：在 settings.json 中设置 "sandbox": false
如果使用自定义沙盒，检查 .gemini/sandbox.Dockerfile 配置

进阶配置

项目级配置

Gemini CLI 支持在项目根目录创建独立配置，覆盖全局设置：

mkdir -p <project-root>/.gemini

项目级 settings.json

// <project-root>/.gemini/settings.json
{
  "model": {
    "name": "google/gemini-2.5-pro"
  }
}

项目级 .env

# <project-root>/.gemini/.env
GEMINI_MODEL=google/gemini-2.5-pro

适用场景：

不同项目使用不同模型
团队统一默认行为
商业项目使用按量付费 Key，个人项目使用订阅 Key

请不要将包含真实 API Key 的 .env 文件提交到版本库。如果需要把配置共享给团队，建议只提交 settings.json 模板。

会话保留

Gemini CLI 支持会话历史保留，方便回顾之前的对话：

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d"
    }
  }
}

会话历史存储在 ~/.gemini/history/ 目录下，可按需调整 maxAge 或设为 false 关闭。

配合不同场景的推荐配置

日常开发

# 平衡性能和成本
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-pro"

代码审查

# 注重推理能力
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-pro"

快速迭代

# 注重响应速度
export GEMINI_API_KEY="sk-ss-v1-xxx"
export GOOGLE_GEMINI_BASE_URL="https://api.agipower.ai"
export GEMINI_MODEL="google/gemini-2.5-flash"

如果您在使用过程中遇到任何问题，或有任何建议和反馈，欢迎通过以下方式联系我们：

官方网站：https://agipower.ai
技术支持邮箱：support@agipower.ai

更多联系方式和详细信息，请访问我们的联系我们页面。

关于 AGIPower

API 参考

最佳实践

帮助中心

Gemini cli

通过 AGIPower 使用 Gemini CLI 指南

前置条件

安装 Gemini CLI

获取 AGIPower API Key

配置方案

Step 1: 创建配置目录

Step 2: 配置环境变量

Step 3: 配置 settings.json

Step 4: 验证连接

认证方式

核心功能

GEMINI.md 上下文文件

常用斜杠命令

自定义斜杠命令

MCP 集成

非交互模式

支持的模型

已知问题：工具调用报错 \

故障排除

常见问题解决

Gemini CLI 启动后要求 Google 登录

API Key 错误

连接失败问题

.env 配置文件不生效

改文件时报 function_response 相关错误

模型不可用

请求偶发超时

沙盒模式问题

进阶配置

项目级配置

会话保留

配合不同场景的推荐配置

关于 AGIPower

API 参考

最佳实践

帮助中心

Documentation Index

​通过 AGIPower 使用 Gemini CLI 指南

​前置条件

​安装 Gemini CLI

​获取 AGIPower API Key

​配置方案

​Step 1: 创建配置目录

​Step 2: 配置环境变量

​Step 3: 配置 settings.json

​Step 4: 验证连接

​认证方式

​核心功能

​GEMINI.md 上下文文件

​常用斜杠命令

​自定义斜杠命令

​MCP 集成

​非交互模式

​支持的模型

​已知问题：工具调用报错 \

​故障排除

​常见问题解决

​Gemini CLI 启动后要求 Google 登录

​API Key 错误

​连接失败问题

​.env 配置文件不生效

​改文件时报 function_response 相关错误

​模型不可用

​请求偶发超时

​沙盒模式问题

​进阶配置

​项目级配置

​会话保留

​配合不同场景的推荐配置

通过 AGIPower 使用 Gemini CLI 指南

前置条件

安装 Gemini CLI

获取 AGIPower API Key

配置方案

Step 1: 创建配置目录

Step 2: 配置环境变量

Step 3: 配置 settings.json

Step 4: 验证连接

认证方式

核心功能

GEMINI.md 上下文文件

常用斜杠命令

自定义斜杠命令

MCP 集成

非交互模式

支持的模型

已知问题：工具调用报错 \

故障排除

常见问题解决

Gemini CLI 启动后要求 Google 登录

API Key 错误

连接失败问题

.env 配置文件不生效

改文件时报 function_response 相关错误

模型不可用

请求偶发超时

沙盒模式问题

进阶配置

项目级配置

会话保留

配合不同场景的推荐配置