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

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

你需要准备什么

Node.js 20 以上。没装的看 Codex 安装教程第一步，方法通用。
一个 Google 账号（推荐方式），或一个 Gemini API Key。没有 Google 账号可以看谷歌邮箱账号专区。
能访问 Google 服务的网络。登录和调用都要连 Google 服务器。

安装：两种方式

# 方式一：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 等轻量模型）。每日额度到点自动刷新，用完不是号废了——限额机制的通用逻辑见这篇。

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

方式 B：Gemini API Key

去 Google AI Studio 生成一个 key：

export GEMINI_API_KEY="你的key"
gemini

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

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

基本用法

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

常用操作：

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

配置文件在 ~/.gemini/settings.json，支持配 MCP 服务器、主题、代理等，玩法和 Claude Code 的配置体系类似。

国内使用注意

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

和 Codex CLI / Claude Code 怎么选

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

简单说：零成本体验选 Gemini CLI，生产力干活再上 Codex / Claude Code。三家 Agent 的完整对比见AI 编程 Agent 横评。Gemini 账号档次（免费/AI Pro/Ultra）的区别见 Gemini 账号指南。

额度数字和模型策略 Google 调整比较频繁，以 gemini-cli 官方文档的最新说明为准。