Gemini CLI 国内使用教程：免费终端 AI 编程上手（2026）

Gemini CLI 是 Google 开源的终端 AI 智能体，免费额度慷慨、还能用上 Gemini 的百万级上下文，是 Claude Code、Codex CLI 之外又一个值得收进工具箱的选择。难点在于「国内怎么用」——直连 Google 经常不稳。这篇 Gemini CLI 国内使用教程会带你完成安装、讲清三种登录方式，并给出网络不通时用 API Key 或第三方中转把它跑起来的具体做法，附常用命令与避坑提示。

Gemini CLI 是什么

Gemini CLI 是 Google 官方开源的命令行 AI 智能体，直接在终端里调用 Gemini 模型：读代码、跨文件改代码、跑命令、联网查资料、通过 MCP 接入外部工具，还支持图片/PDF 等多模态输入。它和 Claude Code、Codex CLI 属于同一类「终端里的 agentic 编程工具」，最大卖点是免费额度大、上下文窗口长。

安装：一行命令搞定

Gemini CLI 用 Node 分发，先确保本机装了 Node.js 20 或以上（node -v 查看）。然后任选一种方式安装：

# 方式一：全局安装（推荐）
npm install -g @google/gemini-cli

# 方式二：免安装，直接跑一次
npx @google/gemini-cli

# 方式三：macOS 用 Homebrew
brew install gemini-cli

# 安装后在项目目录启动交互式 CLI
gemini

启动后输入 gemini 进入交互界面，第一次会让你选择登录/鉴权方式。国内用户的关键选择就在这一步。

三种登录方式怎么选

如果你有稳定的科学上网环境，直接用 Google 账号登录最省事，能吃到免费额度。如果没有，或者想在国内网络下稳定使用，就走 API Key + 中转的路线。

国内怎么用：API Key + 中转配置

从中国大陆直连 Google 服务成功率偏低、延迟大。稳妥做法是用环境变量把 Gemini CLI 指向一个可用的接入点：一是 GEMINI_API_KEY 填你的密钥，二是 GOOGLE_GEMINI_BASE_URL 指向国内可达的中转地址（自建代理或第三方中转站）。设置后需重启 gemini 生效。

# 在 shell 配置里设置环境变量（以 bash/zsh 为例）
export GEMINI_API_KEY="你的_API_密钥"
export GOOGLE_GEMINI_BASE_URL="https://你的中转地址"
# 可选：指定模型
export GEMINI_MODEL="gemini-3-pro"

# 重启终端或 source 后再启动
gemini

常用操作速览

• 在项目根目录运行 gemini 进入交互，直接用自然语言下达任务，它会读你的代码库上下文。
• 用 GEMINI.md 文件给项目写长期上下文/规则（类似 CLAUDE.md、AGENTS.md 的作用）。
• 通过 MCP 接入外部工具（数据库、浏览器、第三方 API 等），扩展它能干的活。
• 多模态：可以把截图、PDF、草图丢给它，让它据此生成或修改代码。
• 百万级上下文适合一次性喂进大型代码库做整体分析或重构规划。

和 Claude Code、Codex CLI 怎么比

三者都是终端 agentic 工具，用法接近，区别主要在模型、额度和生态。Gemini CLI 胜在免费额度大、上下文长；Claude Code 胜在代码质量口碑好、生态成熟；Codex CLI 背靠 OpenAI 模型。国内用户不必二选一——把它们都配好，按任务和额度灵活切换即可。想了解 Claude Code 怎么接国产模型、Codex CLI 国内怎么用，可以看站内对应教程。

Gemini CLI 把「在终端里免费用上强模型」变成了现实，国内用户只要迈过网络这道坎就能顺畅使用。但工具只是起点——真正拉开差距的，是你能不能把需求拆清楚、把 AI 的产出审查到位、把它稳定用进真实项目。想系统掌握用 AI 工具做出能交付产品的方法，欢迎来 IMAI 看看我们的体系化实战课程。