Gemini CLI 安装、配置、使用与认证指南

Gemini CLI 是 Google 开源的终端 AI 助手，把 Gemini 的能力直接接到命令行里，让你在终端里对话、写代码、查资料、跑工具。本文介绍其安装、配置、使用、认证方式，以及和订阅方案的关系。

一、简介与特点

二、安装

系统要求

安装方式

# 不安装，直接运行
npx @google/gemini-cli


# 全局安装（npm）
npm install -g @google/gemini-cli


# macOS / Linux（Homebrew）
brew install gemini-cli

三、认证方式

Gemini CLI 支持三种认证，任选其一即可。

方式一：Google 账号登录（推荐个人使用）

gemini
# 按提示选择 "Login with Google" 并在浏览器中完成登录


# 使用 Code Assist 许可时可设置项目
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

方式二：Gemini API Key

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

方式三：Vertex AI

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

四、模型介绍

Gemini CLI 默认或可选使用的模型来自 Google Gemini 系列，不同模型在速度、推理能力和上下文长度上有所区别。

常用模型概览

模型特点典型用途
gemini-3-pro新一代旗舰推理模型；标准约 100 万、实验版最高约 200 万 token 上下文；深度推理与代码能力更强复杂代码开发、科学研究、长文档深度分析
gemini-3-flash速度更快、首 token 延迟更低、成本较 Pro 更低；百万级上下文，多模态；性能与效率平衡日常对话、代码补全、文档摘要、实时应用、Agent 工作流
gemini-2.5-pro / gemini-2.5-pro-latest旗舰推理模型，约 100 万 token 上下文；多模态（文本、代码、图片、音视频）；适合复杂推理与代码理解代码分析、架构设计、长文档理解、深度问答
gemini-2.5-flash响应更快、成本更低；同样支持百万级上下文与多模态日常对话、快速补全、总结、脚本编写
gemini-2.0-flash稳定版本，特定任务优化，兼容性好对延迟或兼容性有要求的场景

使用 Google 账号登录时，CLI 通常默认使用 Gemini 2.5 Pro 或更新版本；使用 API Key 或 Vertex 时可在配置或命令行中指定上述任一模型。Gemini 3 系列（Pro / Flash）在 API 与 Vertex 可用后，也可通过 -m 或 model.name 选用。

上下文与能力

在 CLI 中指定模型

具体可用模型名和最新列表以 Gemini API 文档 或 Vertex AI 模型列表为准；不同认证方式下可用模型可能略有差异。

五、基本使用

交互模式

# 在当前目录启动对话
gemini


# 指定要纳入上下文的目录
gemini --include-directories ../lib,../docs


# 指定模型
gemini -m gemini-2.5-flash

非交互模式（脚本 / 自动化）

# 单次提问，输出纯文本
gemini -p "解释这个项目的架构"


# 输出 JSON，便于脚本解析
gemini -p "解释这个项目的架构" --output-format json

常用场景示例

六、配置

配置层级（优先级从高到低）

  1. 命令行参数
  2. 环境变量（含 .env）
  3. 系统设置文件
  4. 项目设置文件
  5. 用户设置文件
  6. 系统默认文件

配置中的字符串可使用环境变量："apiKey": "$MY_API_TOKEN" 或 "${MY_API_TOKEN}"。

配置文件位置

作用域路径
用户设置~/.gemini/settings.json
项目设置项目根目录 .gemini/settings.json
系统默认macOS: /Library/Application Support/GeminiCli/system-defaults.json；Linux: /etc/gemini-cli/system-defaults.json；Windows: C:\ProgramData\gemini-cli\system-defaults.json

settings.json 结构概览

配置按顶层分类组织，常用如下：

示例（节选）：

{
  "general": { "vimMode": true, "preferredEditor": "code" },
  "ui": { "theme": "GitHub", "hideBanner": true },
  "model": { "name": "gemini-2.5-pro-latest", "maxSessionTurns": 10 },
  "context": {
    "fileName": ["GEMINI.md"],
    "includeDirectories": ["../lib", "../docs"]
  },
  "tools": {
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "trust": true
    }
  }
}

MCP（Model Context Protocol）

MCP 用于把外部服务（GitHub、Slack、数据库等）的能力以「工具」形式暴露给 Gemini CLI。

常用字段：command / args、url / httpUrl、cwd、env、timeout、trust、includeTools / excludeTools。
配置可放在 ~/.gemini/settings.json（全局）或项目 .gemini/settings.json（仅当前项目）。
会话中可通过 @serverAlias 指令 使用对应工具（如 @github 列出我的 PR）。

七、与订阅方案的关系

因此：若只想在终端里用 Gemini CLI，无需购买 Gemini 应用的 Pro/Ultra 订阅；需要更高 API 配额或企业能力时，再考虑 API 付费或 Vertex AI。

八、使用 OpenRouter 的替代方案

官方 Gemini CLI 只对接 Google / Vertex 的 Gemini API，不直接支持 OpenRouter。若想通过 OpenRouter 使用 Gemini（或其它 200+ 模型），可使用社区版 Gemini CLI - OpenRouter Edition：

npm install -g @chameleon-nexus-tech/gemini-cli-openrouter

配置四个环境变量后即可用 OpenRouter 的 API Key 与模型（含 google/gemini-2.0-flash-001 等）：

export AI_ENGINE="openrouter"
export AI_API_KEY="sk-or-v1-你的OpenRouter密钥"
export AI_MODEL="google/gemini-2.0-flash-001"
export GEMINI_API_KEY="openrouter"
gemini

详见 chameleon-nexus/gemini-cli-openrouter。

九、参考链接

Pig AI 新版体验