# Gemini CLI 上手教程：安装、登录、免费额度与国内使用注意

> Google 官方开源的 Gemini CLI 怎么装？Google 账号登录和 API Key 两种方式怎么选？免费档每天 1000 次请求怎么拿？国内网络环境有什么坑？一篇跑通。
> 更新于 2026-08-09 · 难度 初级 · 来源 https://aicdks.com/guides/gemini-cli-guide

Gemini CLI 是 Google 官方开源（GitHub: google-gemini/gemini-cli）的命令行 AI 编程工具，定位对标 Codex CLI 和 Claude Code。它最大的卖点是**免费额度真的大方**：个人 Google 账号登录就有每天约 1000 次模型请求，不用绑卡。对想先零成本体验「终端 AI 编程」的人，这是目前门槛最低的入口。

## 你需要准备什么

1. **Node.js 20 以上**。没装的看 [Codex 安装教程](/guides/install-codex-cli-china)第一步，方法通用。
2. **一个 Google 账号**（推荐方式），或一个 Gemini API Key。没有 Google 账号可以看[谷歌邮箱账号专区](/category/邮箱账号)。
3. **能访问 Google 服务的网络**。登录和调用都要连 Google 服务器。

## 安装：两种方式

```bash
# 方式一：npx 免安装，尝鲜用
npx @google/gemini-cli

# 方式二：全局安装（推荐日常使用）
npm install -g @google/gemini-cli
gemini
```

macOS 也可以 `brew install gemini-cli`。npm 慢就切 npmmirror 镜像（`npm config set registry https://registry.npmmirror.com`）。

## 登录：两种方式怎么选

### 方式 A：Sign in with Google（推荐）

首次运行 `gemini`，选 **Sign in with Google**，浏览器弹出 Google 登录页授权即可。这条路的额度：

| 账号类型 | 每天请求上限（参考） |
| --- | --- |
| 普通 Google 账号（免费） | 约 1,000 次/天，60 次/分钟 |
| Google AI Pro 订阅 | 约 1,500 次/天 |
| Google AI Ultra 订阅 | 约 2,000 次/天 |

免费档就能用到 Gemini 主力模型和 1M token 上下文，模型由 CLI 自动调度（额度紧张时可能被调度到 Flash 等轻量模型）。**每日额度到点自动刷新，用完不是号废了**——限额机制的通用逻辑见[这篇](/guides/quota-limits-explained)。

注意：部分账号类型（比如 Workspace 企业账号）登录时会要求选择一个 Google Cloud 项目，按提示设置 `GOOGLE_CLOUD_PROJECT` 环境变量即可；个人 Gmail 账号一般不需要。

### 方式 B：Gemini API Key

去 [Google AI Studio](https://aistudio.google.com/apikey) 生成一个 key：

```bash
export GEMINI_API_KEY="你的key"
gemini
```

API Key 免费档每天约 250 次请求（限 Flash 模型），比 Google 登录少；好处是**可以指定具体模型**、可升级按量计费拿更高配额。国内拿不到官方计费的话，也可以用兼容 Gemini 接口的[中转额度](/category/api-中转与额度)。

**结论：个人用户无脑选方式 A**；要跑脚本/CI、或要固定模型，再用方式 B。

## 基本用法

```bash
cd my-project
gemini            # 进入交互模式，直接说需求
```

常用操作：

- `/model`：切换模型；
- `/stats`：查看本次会话的额度消耗；
- `gemini -p "总结这个目录的代码结构"`：非交互模式，适合写进脚本；
- 项目根目录放 `GEMINI.md`，写清项目规范，Gemini 会遵守（作用等同 Codex 的 AGENTS.md）。

配置文件在 `~/.gemini/settings.json`，支持配 MCP 服务器、主题、代理等，玩法和 [Claude Code 的配置体系](/guides/claude-code-config-deep)类似。

## 国内使用注意

1. **终端也要走代理**。浏览器能开 google.com 不代表终端能连上。登录卡住或请求超时，先 `export https_proxy=http://127.0.0.1:端口`（端口看你代理软件的设置）再运行 gemini。
2. **登录回调打不开**。OAuth 登录要在浏览器完成后回调到本地端口，代理软件开「全局/增强模式」一般能解决；实在不行用方式 B 的 API Key 登录绕过 OAuth。
3. **账号风险**。频繁换 IP、用一次性邮箱注册的 Google 账号跑大量请求，可能触发 Google 风控要求手机验证。建议用养熟的账号，或直接买[稳定的成品 Google 账号](/category/邮箱账号)（注意事项见[封号自保清单](/guides/account-safety-guide)）。
4. **免费额度是给个人开发用的**，拿去做多人共享或商用服务违反条款，容易被限。

## 和 Codex CLI / Claude Code 怎么选

| | Gemini CLI | Codex CLI | Claude Code |
| --- | --- | --- | --- |
| 免费额度 | **约 1000 次/天，最大方** | 无（要订阅或 API） | 无（要订阅或 API） |
| 上手成本 | 最低 | 中 | 中 |
| 复杂编码任务口碑 | 一般 | 强 | 强 |

简单说：**零成本体验选 Gemini CLI，生产力干活再上 Codex / Claude Code**。三家 Agent 的完整对比见[AI 编程 Agent 横评](/guides/ai-coding-agents-overview)。Gemini 账号档次（免费/AI Pro/Ultra）的区别见 [Gemini 账号指南](/guides/gemini-account-guide)。

额度数字和模型策略 Google 调整比较频繁，以 [gemini-cli 官方文档](https://github.com/google-gemini/gemini-cli) 的最新说明为准。