本文最后更新于 2026-05-11，文章内容可能已经过时。

终端里装一个Google AI助手：Gemini CLI完整上手指南

你有没有遇到过这种情况——

官方下载地址：https://github.com/google-gemini/gemini-cli（通过 npm 安装：npm install -g @anthropic-ai/gemini-cli，国内可直接访问）

接手一个陌生的开源项目，打开目录一看，几十个文件夹、几百个文件，README写得语焉不详。你在终端里发了两个小时的呆，不知道从哪里下手。

以前的解法是：把核心文件一段一段复制到ChatGPT，来回粘贴，上下文断了又断，问到一半忘了问什么。

现在有个更优雅的解法：Gemini CLI——Google官方开源的终端AI助手，直接在命令行里读懂你整个代码库，然后跟你聊。

不是第三方套壳，是原厂出品。免费额度比你想象的大得多。今天这篇文章，带你从零跑通它。

第一章：Gemini CLI是什么，凭什么值得你停下来

市面上的命令行AI工具不少，但Gemini CLI的定位很独特。

它是Google DeepMind官方维护的开源项目，代码在GitHub上完全公开，不是哪家公司套了个壳子卖给你的"AI终端增强工具"。这意味着它和Gemini模型的集成是原生级别的，而不是通过API拼凑出来的体验。

几个关键数字先放这里：

  • 免费额度：个人Google账号每分钟60次请求，每天1500次请求
  • 上下文窗口：Gemini 3.1 Pro支持100万token，大约等于750本普通小说的文字量
  • 开源协议：Apache 2.0，可以自由修改和商用

和同类工具对比一下：

工具 免费额度 上下文窗口 是否开源 国内直连
Gemini CLI 60 req/min，1500/day 100万 token ✅ ❌（需中转）
GitHub Copilot CLI 无免费版 约8K token ❌ ❌
Claude CLI（非官方） 无官方版本 20万 token 部分 ❌

100万token的上下文窗口是核心竞争力。这意味着你可以把整个中型项目的代码库塞进去，让Gemini一次性理解全局，而不是像其他工具那样只能看到"一个窗口"的内容。

第二章：安装全流程，三端覆盖

前置条件：检查Node.js版本

Gemini CLI基于Node.js，要求版本18或以上。先确认：

node --version

如果版本低于18，去 nodejs.org 下载LTS版本安装。

一行命令安装

npm install -g @google/gemini-cli

安装完成后验证：

gemini --version

看到版本号输出就说明安装成功。

Windows用户的额外说明

Windows下推荐在PowerShell或WSL2环境里操作。如果遇到权限报错，以管理员身份运行PowerShell，或者在npm配置里改全局安装路径：

# 以管理员身份运行PowerShell
npm install -g @google/gemini-cli

常见报错速查

报错信息 原因 解决方法
EACCES: permission denied npm全局目录权限不足 用sudo或修改npm prefix
node: command not found Node.js未安装或未加入PATH 重新安装Node.js，重启终端
npm ERR! code ENOTFOUND 网络问题，无法访问npm registry 切换npm镜像：npm config set registry https://registry.npmmirror.com
gemini: command not found 全局bin目录未加入PATH 执行npm config get prefix，将输出路径的/bin加入PATH
Error: Cannot find module 安装不完整 卸载重装：npm uninstall -g @google/gemini-cli && npm install -g @google/gemini-cli

第三章：接入8848AI API中转——解锁完整能力的关键

这是全文最核心的部分，也是中国用户最容易卡住的地方。

直接用Google账号登录Gemini CLI，在国内网络环境下会遇到两个问题：一是访问不稳定，二是额度管理麻烦。更好的方案是用API Key + 中转节点的方式接入，稳定、可控、不需要翻墙。

为什么需要API中转

Gemini CLI支持自定义API端点。通过中转节点，请求会从国内服务器转发到Google的API，你这边直连中转节点，速度和稳定性都有保证。

这里用的是 8848AI API中转服务——它聚合了Gemini、Claude、GPT系列等主流模型，一个Key管全部，对国内用户来说省去了最麻烦的那一步。注册后在控制台复制Key，填入下面的配置就行，整个过程不超过3分钟。

配置方式一：环境变量（推荐）

macOS / Linux（.bashrc 或 .zshrc）：

# 添加到 ~/.zshrc 或 ~/.bashrc
export GEMINI_API_KEY="你的8848AI API Key"
export GEMINI_API_BASE_URL="https://api.884819.xyz/v1"

保存后执行：

source ~/.zshrc  # 或 source ~/.bashrc

Windows（PowerShell 环境变量）：

# 临时设置（当前会话有效）
$env:GEMINI_API_KEY = "你的8848AI API Key"
$env:GEMINI_API_BASE_URL = "https://api.884819.xyz/v1"

# 永久设置（写入系统环境变量）
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的8848AI API Key", "User")
[System.Environment]::SetEnvironmentVariable("GEMINI_API_BASE_URL", "https://api.884819.xyz/v1", "User")

配置方式二：配置文件

在用户主目录创建 ~/.gemini/settings.json：

{
  "apiKey": "你的8848AI API Key",
  "apiBaseUrl": "https://api.884819.xyz/v1",
  "model": "gemini-3.1-pro-high"
}

验证配置是否生效

gemini -m gemini-3.1-pro-high "你好，简单介绍一下你自己"

看到Gemini的回复，说明整条链路已经通了。

⚠️ 安全提示：API Key是敏感信息，不要提交到Git仓库。如果你在项目目录下操作，记得把 .gemini/ 和包含Key的配置文件加入 .gitignore。

第四章：5个让效率翻倍的实战场景

安装配置只是开始，下面这些才是让你真正"哇"出来的部分。

场景一：读懂陌生代码库

进入项目目录，启动交互模式：

cd /path/to/your/project
gemini

在交互模式里，用 @ 符号引用文件或目录：

> @src/ 这个项目的核心架构是什么？主要的数据流是怎么走的？

Gemini会读取整个 src/ 目录的内容，然后给你一个清晰的架构说明。100万token的上下文窗口在这里发挥作用——大多数中型项目的代码量都在这个范围内。

场景二：自动生成提交信息

这是最高频的使用场景之一，一行命令：

git diff --staged | gemini -p "根据以下diff，生成一条规范的Git commit message，使用约定式提交格式（Conventional Commits）"

再也不用对着diff发呆想"这次改动怎么描述"了。

场景三：批量处理文本文件

假设你有一堆日志文件需要提取关键信息：

cat error.log | gemini -p "从这份日志中提取所有ERROR级别的记录，按模块分类，输出Markdown表格"

或者批量翻译：

for file in *.md; do
  gemini -p "将以下Markdown文档翻译成英文，保持原有格式" < "$file" > "en_$file"
done

场景四：调试报错日志

遇到一个看不懂的报错，直接管道过去：

python your_script.py 2>&1 | gemini -p "分析这个错误，告诉我根本原因和修复方案"

或者结合代码上下文：

gemini -p "$(cat error.log)\n\n相关代码：\n$(cat src/main.py)\n\n请分析错误原因并给出修复建议"

场景五：用自然语言写Shell脚本

不会写Shell？直接说需求：

gemini -p "写一个Shell脚本：监控指定目录下的文件变化，当有新文件创建时，自动压缩并移动到备份目录，同时记录日志。要求兼容macOS和Linux。"

Gemini会给你一个完整的、可直接运行的脚本，还会附上使用说明。

第五章：进阶配置与避坑指南

GEMINI.md：让AI记住你的项目规范

在项目根目录创建 GEMINI.md 文件，Gemini CLI会自动读取它作为项目上下文：

# 项目规范

## 技术栈
- 后端：Python 3.11 + FastAPI
- 前端：React 18 + TypeScript
- 数据库：PostgreSQL 15

## 代码规范
- Python遵循PEP 8，使用Black格式化
- 变量命名使用snake_case
- 函数必须有类型注解和docstring

## 提交规范
- 使用Conventional Commits格式
- feat/fix/docs/refactor/test/chore

## 注意事项
- 所有API接口必须有错误处理
- 敏感配置通过环境变量注入，不硬编码

有了这个文件，每次启动Gemini CLI，它都知道你在做什么项目、遵循什么规范，不需要每次重新解释背景。

模型选择逻辑

Gemini CLI支持在 gemini-3.1-pro-high 和 gemini-3-flash 之间切换：

# 使用Pro版本（能力更强，适合复杂任务）
gemini -m gemini-3.1-pro-high "..."

# 使用Flash版本（速度更快，适合简单任务）
gemini -m gemini-3-flash "..."

选择建议：
- 代码审查、架构分析、复杂推理 → 用 gemini-3.1-pro-high
- 生成commit信息、简单问答、格式转换 → 用 gemini-3-flash

Flash版本速度明显更快，在不需要深度推理的场景下，体感差异非常明显。

3个新手最容易踩的坑

坑一：上下文窗口管理

虽然支持100万token，但在长对话中，早期的上下文可能被截断。如果发现AI"忘记"了之前说的内容，用 /clear 命令清除历史，重新开始一个干净的会话。

坑二：敏感信息泄露风险

用 @ 引用文件时，要注意别把包含密钥、密码的配置文件引用进去。建议在 GEMINI.md 里明确标注哪些文件不应该被引用，养成习惯。

坑三：token消耗成本控制

免费额度的1500次/天看起来很多，但如果每次都引用大型代码库，消耗会很快。几个省token的技巧：
- 只引用相关的子目录，而不是整个项目
- 简单任务用Flash模型
- 批量任务合并成一次请求

如果你同时在用多个AI工具，8848AI的统一计费其实更好算账——在 api.884819.xyz 的控制台可以看到每个模型的消耗明细，避免月底账单惊喜。

行动清单：今天就能完成的3步

读到这里，给你一个最简洁的行动路径：

  1. 安装：npm install -g @google/gemini-cli，确认 gemini --version 有输出
  2. 配置：去 api.884819.xyz 注册拿Key（新用户新用户注册即送体验额度。
  3. 验证：进入你最近在做的项目目录，运行 gemini，输入 @src/ 这个项目在做什么

就这三步。命令行+AI，是下一个效率分水岭，而Gemini CLI是目前这个赛道里最值得上手的工具——Google背书、免费额度大、上下文窗口无对手。

下一篇预告： Gemini CLI只是起点。Google同期开放的 Gemini 3.1 Pro Deep Research 能力，正在让"AI自动完成一份完整调研报告"从概念变成现实——我们正在测试它能不能替代人工做竞品分析，结果出乎意料。关注我们，下周见。

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。

AI工具 #Gemini #命令行AI #开发者工具 #8848AI #AI教程 #GeminiCLI #效率工具