Google Gemini CLI 上手体验：免费的终端 AI 编程 Agent，真香还是坑？

上周刷 Twitter 的时候看到一堆人在讨论 Gemini CLI，说是 Google 出的终端 AI 编程助手，免费用、开源、100 万 token 上下文。我当时的第一反应是：又来一个？Claude Code 和 Codex 已经打得不可开交了（可以看看这篇 AI编程工具深度实战对比），Google 这时候入场是来送人头的还是来搅局的？

本着"不亲自试一下就没有发言权"的原则，我花了大概三天时间深度使用 Gemini CLI，从安装配置到日常开发，从简单脚本到项目级别的重构，都跑了一遍。这篇文章就是我的真实体验记录，有惊喜也有翻车，不吹不黑。

为什么我会关注 Gemini CLI

先说背景。我之前一直在用 Claude Code，偶尔用 Codex。Claude Code 确实强，尤其是多文件协调和复杂重构这块，基本上没人能打。但有个问题——贵。一个月下来 API 费用能干到 100-200 刀，对于个人开发者或者刚起步的小团队来说，这个成本还是肉疼的。

Codex CLI 好一些，开源免费安装，但还是要 OpenAI 的 API key，按 token 付费。ChatGPT Plus 用户倒是能用，但 20 刀一个月也不算便宜。

这时候 Google 说：来，Gemini CLI，免费用，100 万 token 上下文，每分钟 60 次请求，每天 1000 次。

说实话，我一开始是不信的。天下哪有免费的午餐？Google 的"免费"通常意味着你的数据会被拿去训练模型。但架不住好奇，还是装了一个试试。

安装踩坑记

安装过程本身很简单，但细节上有几个坑值得注意。

基本安装

Gemini CLI 需要 Node.js 18 或更高版本。如果你还没装 Node，先搞一个：

# 用 nvm 安装 Node（推荐）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

source ~/.bashrc

nvm install 20

nvm use 20

然后装 Gemini CLI：

npm install -g @google/gemini-cli

或者用 Homebrew（macOS/Linux）：

brew install gemini-cli

装完之后验证一下：

gemini --version

第一个坑：Node 版本

我服务器上的 Node 是 16.x，装完之后直接报错：

Error: Gemini CLI requires Node.js 18 or higher

这没什么好说的，升级就完了。但如果你和我一样用 nvm 管理版本，记得在项目目录下设置默认版本：

nvm alias default 20

不然每次开新终端又回到老版本，很烦。

第二个坑：npm 全局安装权限

在 Linux 上用 npm 全局安装的时候可能会遇到权限问题：

Error: EACCES: permission denied

解决办法有两种：

# 方法一：修改 npm 全局目录（推荐）

mkdir ~/.npm-global

npm config set prefix '~/.npm-global'

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

source ~/.bashrc

# 方法二：用 sudo（不推荐，但能用）

sudo npm install -g @google/gemini-cli

我推荐方法一，因为用 sudo 装全局包后续升级、卸载都要 sudo，很麻烦。

第三个坑：网络问题

在国内的服务器上装的时候可能会卡住或者超时。这时候换个 npm 源就行：

npm config set registry https://registry.npmmirror.com

npm install -g @google/gemini-cli

装好之后记得改回来，或者只在这次安装的时候用：

npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com

登录与认证

安装完第一步是登录。Gemini CLI 支持两种认证方式：

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

直接在终端运行：

gemini

第一次运行会弹出浏览器让你用 Google 账号授权。授权完成后，终端就能用了。

这个方式最简单，免费额度是每分钟 60 次请求，每天 1000 次。对于个人开发者来说，这个额度基本够用了。我一天高强度使用下来，大概也就用了 200-300 次请求。

方式二：API Key（脚本/服务器）

如果你要在 CI/CD 或者脚本里用，没法弹浏览器，那就用 API Key：

# 在 Google AI Studio 创建 API Key

# https://aistudio.google.com/apikey

export GEMINI_API_KEY="your-api-key-here"

gemini

也可以写到 .bashrc 里持久化：

echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.bashrc

source ~/.bashrc

第四个坑：Google 账号在中国大陆的问题

这个不多说了，懂的都懂。如果你在国内服务器上用，建议直接走 API Key 的方式，配合代理。或者用 Google Cloud 的 Vertex AI 认证，那个走的是 GCP 通道，相对好一些。

实际使用体验

好了，装也装完了，登录也搞定了，来看看实际用起来怎么样。

基本对话

启动 Gemini CLI 后，你会看到一个交互式终端界面：

$ gemini

╭─────────────────────────────────────────────────╮

│  Gemini CLI                                      │

│  Type your message or /help for commands          │

╰─────────────────────────────────────────────────╯

> 帮我写一个 Python 脚本，统计一个目录下所有文件的行数

Gemini CLI 会直接生成代码，然后问你要不要执行。这个交互模式和 Claude Code 类似，但有一个区别——Gemini CLI 默认不会自动读取你的项目上下文，你需要明确告诉它去看哪些文件。

代码生成能力

我测试了几个常见的编程任务：

任务一：写一个 FastAPI 服务

> 帮我用 FastAPI 写一个简单的 CRUD API，管理待办事项，用 SQLite 存储

Gemini CLI 生成的代码质量还不错，基本能跑。但有个问题——它生成的代码风格偏"教科书"，缺少一些实际开发中的细节，比如错误处理、日志记录这些。和 Claude Code 比起来，Claude 生成的代码会更"生产就绪"一些。

任务二：重构现有代码

这是我比较看重的能力。我拿了一个实际项目的文件让 Gemini CLI 帮我重构：

> 读取 src/utils.py，把里面所有的字符串操作函数提取到 src/string_utils.py，然后更新所有引用

Gemini CLI 读取文件后，给出了重构方案，创建了新文件，也更新了引用。但有几处引用它漏掉了，导致 import 报错。我手动修了两处，才跑通测试。

这算是一个比较典型的体验：Gemini CLI 能完成 80% 的工作，但剩下 20% 需要你自己收尾。

任务三：Debug 一个报错

这个场景下 Gemini CLI 表现得不错。我把一个报错信息贴给它：

> 我运行 pytest 的时候报了这个错：ImportError: cannot import name 'url_encode' from 'werkzeug.urls'

> 帮我看看怎么回事

它很快识别出这是 Werkzeug 版本兼容性问题，给出了解决方案：降级 Werkzeug 或者更新 Flask。还附带了具体的 pip install 命令。

速度：这是 Gemini CLI 最大的优势

说真的，速度是 Gemini CLI 最让我惊喜的地方。和 Claude Code 比，Gemini CLI 的响应速度明显更快。Claude Code 有时候一个复杂请求要等 10-20 秒才开始输出，Gemini CLI 通常 2-3 秒就开始了。

当然，速度快不等于质量高。后面会详细对比。

上下文能力

Gemini CLI 用的是 Gemini 2.5 Pro，号称 100 万 token 上下文。我实际测试了一下，让它读取一个大概有 50 个文件的小项目：

> 分析当前目录下的项目结构，告诉我整体架构和可能的改进点

它确实能把整个项目吞下去，给出全局性的分析。这点和 Claude Code 的 agentic search 有异曲同工之妙。但 Gemini CLI 的分析深度不如 Claude Code——它更倾向于给出表面性的建议，而 Claude Code 能深入到具体的代码逻辑。

MCP 集成：Gemini CLI 的隐藏大招

Gemini CLI 有一个其他工具没有的特性——内置 MCP (Model Context Protocol) 支持。这意味着你可以给 Gemini CLI 添加各种"工具"，让它在对话中调用。

什么是 MCP

简单来说，MCP 是一个让 AI Agent 调用外部工具的协议。比如你可以让 Gemini CLI 在写代码的时候顺便搜索文档、查数据库、调用 API 等等。

我在之前的文章里详细介绍过 MCP（MCP 到底是什么？一个全栈开发者的实战理解），这里不展开了。重点说说 Gemini CLI 的 MCP 集成怎么用。

配置 MCP Server

Gemini CLI 的 MCP 配置在 ~/.gemini/settings.json 里：

{

  "mcpServers": {

    "filesystem": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

    },

    "github": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-github"],

      "env": {

        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"

      }

    }

  }

}

配好之后，Gemini CLI 就能在对话中使用这些工具了。比如你可以说：

> 搜索 GitHub 上关于 Gemini CLI 的最新 issues，看看有没有人遇到和我一样的问题

Gemini CLI 会自动调用 GitHub MCP Server 来搜索 issues，然后把结果返回给你。

内置 Google Search

除了 MCP，Gemini CLI 还内置了 Google Search 能力。你可以在对话中直接搜索：

> 搜索一下 FastAPI 的最新版本有什么新特性

它会调用 Google Search 获取最新信息，然后结合搜索结果来回答你。这个功能在查文档、查 API 变更的时候特别有用。

MCP 的实际体验

说实话，MCP 集成是 Gemini CLI 的差异化优势，但目前体验还不够成熟。配置 MCP Server 的过程比较繁琐，而且不是所有 MCP Server 都能稳定工作。我试了 filesystem server 和 GitHub server，filesystem 基本没问题，GitHub server 偶尔会超时。

但这个方向是对的。随着 MCP 生态的成熟，这个功能会越来越有价值。

和 Claude Code、Codex 的深度对比

用了三天之后，我来做一个详细的对比。

代码质量

这是最重要的维度。我的体感是：

Claude Code 的代码质量最高。它生成的代码通常可以直接用在生产环境，错误处理、边界情况、代码风格都考虑得比较周全。在复杂任务上（比如多文件重构、架构设计），Claude Code 的表现明显领先。

Codex CLI 次之。GPT-5.3 在标准编程任务上的表现很好，Terminal-Bench 2.0 的分数甚至比 Claude 高（77.3% vs 65.4%）。但在复杂的多步骤任务上，Claude 的 agentic 能力更强。

Gemini CLI 的代码质量最不稳定。有时候生成的代码很棒，有时候会有明显的 bug。我个人的体感大概是 50-60% 的情况下代码能直接用，剩下的需要手动修复。和网上一些评测说的数据基本吻合。

速度

Gemini CLI 最快。响应速度是三者中最好的，基本 2-3 秒就开始输出。

Claude Code 中等。开启 Fast Mode 后速度提升明显，但默认模式下有时候会等比较久。

Codex CLI 最慢。网络延迟加上 OpenAI API 的处理时间，有时候一个简单请求要等 5-10 秒。

上下文能力

Claude Code 和 Gemini CLI 都支持 100 万 token 上下文，能覆盖大多数项目。Claude Code 还有 Compaction API，理论上可以支持"无限对话"。

Codex CLI 的上下文是 40 万输入 + 12.8 万输出，小一些但也够用。

工具集成

Claude Code 的工具集成最完善——原生支持 Git、CI/CD、IDE 插件、Slack 等等。

Gemini CLI 有 MCP 集成和内置 Google Search，这是独特优势。但整体工具生态还在发展中。

Codex CLI 最轻量，基本上就是在终端里跑，没有太多内置工具。

价格

• Claude Code：$100-200/月/开发者
• Codex CLI：免费安装，需要 OpenAI API key（按量付费）或 ChatGPT Plus（$20/月）
• Gemini CLI：免费（每天 1000 次请求），付费走 Vertex AI

对个人开发者来说，Gemini CLI 的价格优势是碾压级的。

适合什么场景

根据我的体验，这三个工具各有适用场景：

用 Claude Code 的场景：

• 大规模重构
• 需要高度准确性的任务
• 多文件协调修改
• 企业级项目

用 Codex CLI 的场景：

• 日常编程辅助
• 交互式调试
• 快速原型
• OpenAI 生态内的项目

用 Gemini CLI 的场景：

• 预算有限的个人开发者
• 需要快速迭代的原型开发
• 需要搜索集成的任务
• 学习和实验

实战：用 Gemini CLI 搭建一个小项目

说了这么多理论，来一个实战案例。我用 Gemini CLI 从零搭建了一个简单的 URL 短链接服务，记录一下完整过程。

第一步：项目初始化

mkdir url-shortener && cd url-shortener

gemini

> 帮我用 Python FastAPI 搭建一个 URL 短链接服务，要求：

> 1. POST /shorten 接口，接收长 URL，返回短链接

> 2. GET /{short_id} 接口，重定向到原始 URL

> 3. 用 SQLite 存储

> 4. 包含基本的输入验证

> 5. 写好 requirements.txt

Gemini CLI 生成了大约 150 行代码，分成了 main.py、models.py、database.py 三个文件。代码结构还行，但有几个问题：

• 没有加 CORS 中间件
• 短 ID 生成用的是 hashlib，但没处理冲突
• 没有日志记录

第二步：修修补补

> 加上 CORS 支持，短 ID 要处理冲突（如果已存在就重新生成），加上 logging

Gemini CLI 修改了代码，加了 CORS 和冲突处理。但 logging 的配置有点粗糙，我手动改了一下。

第三步：加测试

> 写单元测试，用 pytest，覆盖主要功能

生成的测试文件有 80 多行，覆盖了创建短链接、重定向、无效 URL 等场景。跑了一下，5 个测试过了 3 个，有 2 个是因为测试数据假设不对。修了一下测试数据，全过了。

第四步：Docker 化

> 帮我写 Dockerfile 和 docker-compose.yml

这个它做得不错，Dockerfile 用的是多阶段构建，docker-compose 也配了环境变量和数据卷。

整体评价

整个过程大概花了 1 小时，比我自己从零写快了不少，但中间修修补补的时间也不少。如果用 Claude Code，可能 30-40 分钟就能搞定，而且质量会更高。但 Claude Code 那个价格……嗯，看场景吧。

常见问题和解决方案

问题一：Gemini CLI 启动后卡住

这通常是因为网络问题。如果你在国内，确保代理配置正确：

export https_proxy=http://127.0.0.1:7890

export http_proxy=http://127.0.0.1:7890

gemini

问题二：响应内容被截断

Gemini CLI 有时候会在长回答中间截断。这时候可以：

> 继续（接上文）

或者在设置里调大 max output tokens：

{

  "maxOutputTokens": 8192

}

问题三：MCP Server 连接失败

检查你的 MCP 配置文件路径是否正确，Server 是否已安装：

# 手动测试 MCP Server

npx @modelcontextprotocol/server-github

如果报错，先装依赖再试。

问题四：代码生成质量不稳定

这是 Gemini CLI 目前最大的问题。我的应对策略是：

1. 给更详细的 prompt，包括具体的代码风格要求
2. 生成后让 Gemini CLI 自己 review 一遍
3. 关键代码还是自己把关

> review 一下你刚才生成的代码，看看有没有 bug 或者可以改进的地方

这个"自我 review"有时候能发现问题，有时候不能。别完全信它。

Gemini CLI 的独特优势

说了这么多，总结一下 Gemini CLI 相比其他工具的独特优势：

免费。这是最大的优势。对于个人开发者、学生、开源项目来说，零成本使用一个 100 万 token 上下文的 AI 编程 Agent，这在之前是不可想象的。

速度快。响应速度是三个工具里最好的，体感非常明显。

MCP 集成。虽然还不够成熟，但 MCP 的方向是对的。随着生态发展，这个能力会越来越强。

开源。Apache 2.0 协议，你可以自己 fork、修改、部署。对于企业来说，这意味着可以在内网部署，数据不出公司。

Google 生态。如果你已经在用 Google Cloud、Android Studio、VS Code 等 Google 系工具，Gemini CLI 的集成会更顺畅。

Gemini CLI 的不足

代码质量不稳定。这是目前最大的硬伤。复杂任务的成功率不如 Claude Code，偶尔会生成有 bug 的代码。

文档和社区。相比 Claude Code 和 Codex，Gemini CLI 的文档和社区资源还比较少。遇到问题的时候，能找到的参考资料有限。

长会话一致性。在长时间的对话中，Gemini CLI 有时候会"忘记"之前讨论的内容，导致前后不一致。Claude Code 的 Compaction API 在这方面做得更好。

工具生态不成熟。MCP Server 的数量和质量都有待提高。目前可用的 MCP Server 比较少，而且有些不太稳定。

我的选择建议

经过三天的深度使用，我的建议是这样的：

如果你预算充足，追求质量——用 Claude Code。它在代码质量、多文件协调、工具集成方面都是目前最好的。

如果你预算有限，主要做原型和学习——用 Gemini CLI。免费、速度快、上下文大，非常适合个人开发者。

如果你在 OpenAI 生态里，需要交互式编程——用 Codex CLI。它和 ChatGPT、GitHub Copilot 的集成最好。

如果你像我一样是个工具控——三个都装，根据场景切换。我现在的习惯是：日常小任务用 Gemini CLI（免费），重要项目用 Claude Code（质量），偶尔用 Codex 换换口味（不同模型的思路有时候能给你新灵感）。

进阶技巧：让你的 Gemini CLI 更好用

用了几天之后，我摸索出了一些提升效率的小技巧。

项目级配置

Gemini CLI 支持项目级配置。在项目根目录下创建 .gemini/ 目录，里面放配置文件：

mkdir -p .gemini

你可以在这个目录下放一个 GEMINI.md 文件，作为项目的上下文说明：

# 项目说明

这是一个使用 FastAPI + SQLAlchemy 的后端项目。

## 技术栈

- Python 3.11

- FastAPI 0.104

- SQLAlchemy 2.0

- PostgreSQL 15

## 代码规范

- 使用 type hints

- 函数和变量用 snake_case

- 类名用 PascalCase

- 所有 public 函数必须有 docstring

## 目录结构

- src/ - 源代码

- tests/ - 测试

- docs/ - 文档

这样 Gemini CLI 在启动时会自动读取这个文件，了解你的项目背景。比每次都要解释"我用的是什么技术栈"方便多了。

使用 system prompt

你可以在 ~/.gemini/settings.json 里配置 system prompt：

{

  "systemInstruction": "你是一个资深 Python 开发者，写代码时注重可读性和测试覆盖。生成代码时默认包含 type hints 和 docstring。"

}

这样每次对话的默认行为都会遵循这个设定，不用每次都重复要求。

快捷命令

Gemini CLI 支持一些斜杠命令：

• /help - 查看帮助
• /clear - 清除当前对话
• /quit - 退出
• /theme - 切换主题颜色

这些命令不多，但 /clear 特别有用——当对话太长导致质量下降的时候，清掉重新开始是个好习惯。

管道输入

Gemini CLI 支持从管道读取输入，这在脚本中非常有用：

# 把报错信息喂给 Gemini CLI

cat error.log | gemini "分析这个报错，给出解决方案"

# 分析代码文件

cat src/main.py | gemini "review 这段代码，找出潜在的 bug"

# 结合 git diff

git diff | gemini "帮我写这个 commit message"

这个功能在 CI/CD 场景下特别有价值。你可以用 Gemini CLI 来自动 review PR、分析测试失败、生成 changelog 等等。

批量操作

如果你要对多个文件做类似的操作，可以配合 shell 脚本：

for file in src/*.py; do

    echo "Processing $file..."

    cat "$file" | gemini "给这个文件添加 type hints，直接输出修改后的完整代码" > "${file}.typed"

    mv "${file}.typed" "$file"

done

不过这种批量操作要小心，建议先在一个文件上测试，确认效果后再批量跑。

Gemini CLI 在团队中的应用

虽然我主要从个人开发者的角度写的这篇文章，但 Gemini CLI 在团队中也有不少应用场景。

Code Review 辅助

把 Gemini CLI 集成到 CI 流程里，自动 review PR：

#!/bin/bash

# review-pr.sh

PR_DIFF=$(gh pr diff $1)

echo "$PR_DIFF" | gemini "Review 这个 PR 的代码变更，指出潜在问题和改进建议。重点关注：

1. 安全漏洞

2. 性能问题

3. 代码风格不一致

4. 缺少的测试覆盖

输出格式：按文件分组，每个问题标注严重程度（高/中/低）"

这个不能替代人工 review，但可以作为一个初步筛选，帮你发现一些明显的问题。

文档生成

让 Gemini CLI 为你的代码生成文档：

find src -name "*.py" | while read file; do

    cat "$file" | gemini "为这个 Python 文件生成详细的中文文档，包括：模块说明、类和函数的用途、参数说明、返回值说明、使用示例" > "docs/$(basename $file .py).md"

done

生成的文档可能需要人工修改，但比从零写要快得多。

测试生成

这是一个非常实用的场景：

cat src/user_service.py | gemini "为这个模块写完整的单元测试，要求：

1. 使用 pytest

2. 覆盖所有 public 方法

3. 包含正常情况和边界情况

4. mock 外部依赖

5. 测试文件命名为 test_user_service.py"

Gemini CLI 生成的测试覆盖率通常在 70-80% 左右，剩下的边界情况需要你自己补充。但作为起步已经很好了。

和其他工具的搭配使用

Gemini CLI 不是万能的，但它可以和其他工具很好地配合。

配合 Git

# 自动生成 commit message

git diff --staged | gemini "根据这个 diff 写一个简洁的 commit message，遵循 conventional commits 规范"

# 分析 git log

git log --oneline -20 | gemini "分析最近的提交历史，总结这段时间的开发重点"

# 解决 merge conflict

cat conflicted-file.py | gemini "这个文件有 merge conflict，帮我解决"

配合 Docker

# 生成 Dockerfile

cat requirements.txt | gemini "根据这些依赖生成一个优化的 Dockerfile，使用多阶段构建"

# 分析 Docker 问题

docker logs my-app 2>&1 | tail -50 | gemini "分析这些容器日志，找出问题"

配合数据库

如果你配了 MCP Server 连接数据库，那就更方便了：

> 查询 users 表中最近 7 天注册的用户数量，按天分组

> 分析 orders 表的索引使用情况，看看有没有可以优化的地方

未来展望

AI 编程 Agent 这个赛道现在越来越卷了。Claude Code、Codex、Gemini CLI 三家各有优势，竞争也在推动整个行业快速进步。

我觉得接下来几个趋势值得关注：

MCP 生态的成熟。MCP 协议让 AI Agent 可以调用任意工具，这是一个根本性的能力扩展。随着更多 MCP Server 被开发出来，AI 编程 Agent 的能力边界会不断外推。

本地模型的崛起。虽然目前 Gemini CLI、Claude Code、Codex 都是调用云端模型，但随着本地模型（Llama、Qwen 等，这里有一份 零基础上手：Llama 3 与 Qwen 等主流大模型本地一键部署实战指南）的能力提升，未来可能会出现完全本地运行的 AI 编程 Agent。隐私敏感的场景会首先受益。

多 Agent 协作。目前的工具都是单 Agent 模式。但未来很可能会出现多 Agent 协作的场景——比如一个 Agent 负责写代码，一个负责 review，一个负责测试。这种分工协作的模式可能会大幅提升开发效率。

价格战。Google 的免费策略已经给市场带来了压力。我猜测 Anthropic 和 OpenAI 也会逐步降低价格或者推出更多免费额度。对开发者来说，这是好事。

后续计划

后面我打算继续深入研究 Gemini CLI 的 MCP 集成，看看能不能搭一些有趣的自动化工作流。另外也想试试 Gemini CLI 在大型项目上的表现——目前测试的都是小项目，不知道 100 万 token 的上下文在实际大项目里能发挥多少。

有啥问题或者使用心得，评论区聊。

• 本文写于 2026 年 5 月，基于 Gemini CLI 最新版本。AI 工具迭代很快，文中的具体数据和体验可能会随版本更新而变化。*