夜雨聆风如果你只是在网页里用 Gemini，体验其实还停留在“聊天工具”阶段。
但如果你想让 Gemini 直接进入终端，帮你看代码、分析项目、处理文件、执行脚本任务，那就可以试试 Gemini CLI。
它更适合开发者，也更适合经常和代码、命令行、自动化流程打交道的人。
这篇就整理一份 Mac / Linux 版 Gemini CLI 安装配置教程，从安装、配置中转站、常用命令到排错方法，尽量讲清楚，适合收藏备用。
unsetunset基本介绍unsetunset
Gemini CLI 是谷歌提供的开源命令行 AI 工具，可以把 Gemini 的能力直接接入终端。
简单理解： 你不用每次打开网页，也不用来回复制粘贴，可以直接在命令行里让 Gemini 帮你分析代码、处理文件、生成内容、执行任务。
通过设置中转站，也可以在网络受限的情况下正常使用 Gemini CLI 服务。
unsetunset🚀 为什么选择 Gemini CLI？unsetunset
Gemini CLI 的优势，不是“能聊天”，而是能更自然地接入开发工作流。
如果你平时经常需要看代码、改代码、写脚本，Gemini CLI 会比网页版更顺手。
unsetunset📦 安装方式unsetunset
unsetunset快速安装unsetunset
Gemini CLI 支持多种安装方式，可以根据自己的使用习惯选择。
使用 npx 即时运行（无需安装）
# 使用官方仓库npx https://github.com/google-gemini/gemini-cli这种方式适合先试用，不需要提前安装。
使用 npm 全局安装
npm install -g @google/gemini-cli如果你打算长期使用，建议直接全局安装。
使用 Homebrew 安装（macOS / Linux）
brew install gemini-cli如果你本来就习惯用 Homebrew 管理工具，这种方式也比较方便。
unsetunset系统要求unsetunset
使用前先确认环境：
Node.js 版本 20 或更高 支持 macOS / Linux
⚠️ 如果后面运行命令报错，建议优先检查 Node.js 版本是否满足要求。
unsetunset配置unsetunset
Gemini CLI 常见配置方式有两种：
如果是第一次配置，建议直接用 配置文件方式。
unsetunset方式一：使用配置文件（推荐）unsetunset
📌Key接口密钥注册入口：https://letaicode.cn/?aff=KbmuqF
unsetunset步骤 1：创建配置目录unsetunset
Gemini CLI 的全局配置文件位于用户主目录下的 .gemini 文件夹中。
macOS / Linux：
~/.gemini如果没有这个目录，可以手动创建。
unsetunset步骤 2：在 .gemini 目录下创建 .env 文件，添加以下内容：unsetunset
GOOGLE_GEMINI_BASE_URL=https://letaicode.cn/geminiGEMINI_API_KEY=YOUR_API_TOKEN_HEREGEMINI_MODEL=gemini-3-pro-preview参数说明：
GOOGLE_GEMINI_BASE_URL | |
GEMINI_API_KEY | |
GEMINI_MODEL |
⚠️ 注意：YOUR_API_TOKEN_HERE 要替换成你自己创建的 key，也就是 sk- 开头的那个。
unsetunset步骤 3：在 .gemini 目录下创建 settings.json 文件，内容如下：unsetunset
{"ide": {"enabled": true },"security": {"auth": {"selectedType": "gemini-api-key" } }}这个配置主要用于启用 IDE 相关能力，并指定认证方式为 Gemini API Key。
unsetunset方式二：设置环境变量unsetunset
如果你不想使用配置文件，也可以直接设置环境变量。
macOS / Linux：
# 设置 API 密钥export GEMINI_API_KEY=sk-xxxxx# 设置 API 中转站地址export GOOGLE_GEMINI_BASE_URL=https://letaicode.cn/gemini# 设置使用的模型 IDexport GEMINI_MODEL="gemini-3-pro-preview"💡 建议： 如果你希望每次打开终端都自动生效，可以把这些内容添加到 .bashrc、.zshrc 或其他 shell 配置文件中。
unsetunset🚀 快速开始unsetunset
配置完成后，就可以开始使用 Gemini CLI。
unsetunset基本使用unsetunset
在当前目录启动
gemini进入项目目录后执行这个命令，就可以让 Gemini 读取当前目录上下文，辅助你分析项目。
包含多个目录
gemini --include-directories ../lib,../docs适合项目代码和文档不在同一个目录的情况。
使用特定模型
gemini -m gemini-2.5-flash如果只是轻量任务，可以指定速度更快的模型。
unsetunset脚本非交互模式unsetunset
Gemini CLI 不只能在终端里聊天，也可以直接接入脚本。
获取简单文本响应：
gemini -p "解释这个代码库的架构"获取结构化 JSON 输出：
gemini -p "解释这个代码库的架构" --output-format json这个功能很适合做自动化，比如批量分析代码、生成报告、整理结果等。
unsetunset快速示例unsetunset
unsetunset启动新项目unsetunset
cd new-project/gemini然后输入：
> 为我编写一个 Discord 机器人，使用我提供的 FAQ.md 文件回答问题这类场景适合从零开始搭建小项目。
unsetunset分析现有代码unsetunset
git clone https://github.com/google-gemini/gemini-clicd gemini-cligemini然后输入：
> 给我一个昨天所有更改的摘要如果你刚接手一个项目，或者想快速理解历史提交，这个用法很实用。
unsetunset📋 主要功能unsetunset
unsetunset代码理解与生成unsetunset
Gemini CLI 在代码场景里比较实用，尤其适合下面几类任务：
查询和编辑大型代码库 使用多模态能力从 PDF、图片或草图生成新应用 使用自然语言调试问题和故障排除
简单说，它不是只回答问题，而是可以参与到代码理解、生成和修改流程里。
unsetunset自动化与集成unsetunset
Gemini CLI 也适合接入自动化流程：
自动化操作任务，比如查询拉取请求或处理复杂的变基操作 使用 MCP 服务器连接新功能 在脚本中非交互式运行，实现工作流自动化
如果你经常处理重复任务，这部分会很有价值。
unsetunset高级功能unsetunset
Gemini CLI 还支持一些进阶能力：
使用内置 Google 搜索获取实时信息 对话检查点，用于保存和恢复复杂会话 自定义上下文文件 GEMINI.md，为项目定制行为
📌 其中 GEMINI.md 很适合团队项目。 你可以提前写好项目规则、代码风格、注意事项，让 Gemini 更贴合你的项目习惯。
unsetunset常用命令和功能示例unsetunset
下面这些示例可以直接作为日常提示词参考。
unsetunset探索代码库unsetunset
> 描述这个系统架构的主要组成部分> 有哪些安全机制？> 为新开发者提供一份分步骤的入门文档适合刚接手一个项目，或者需要快速整理项目文档。
unsetunset处理现有代码unsetunset
> 为 GitHub issue #123 实现一个初稿> 帮我将这个代码库迁移到最新版本的 Java。先制定一个计划💡 建议： 这类任务不要一上来就让它直接改，先让 Gemini 制定计划，再分步骤执行，效果会更稳。
unsetunset自动化工作流程unsetunset
> 制作一个幻灯片，展示过去 7 天的 git 历史，按功能和团队成员分组> 制作一个全屏 Web 应用用于墙上显示，展示我们互动最多的 GitHub issues适合做团队周报、项目复盘、数据展示等任务。
unsetunset系统交互unsetunset
> 将此目录中的所有图像转换为 png，并使用 exif 数据中的日期重命名它们> 按支出月份整理我的 PDF 发票这类场景非常适合处理批量文件，比手动操作效率高很多。
unsetunsetGitHub 集成unsetunset
使用 Gemini CLI GitHub Action，可以将 Gemini CLI 集成到 GitHub 工作流中。
@gemini-cli 获取帮助 | |
如果团队已经重度使用 GitHub，这部分会很实用。
unsetunset故障排除unsetunset
如果你在使用过程中遇到问题，可以优先从下面几个方向排查。
检查环境变量是否正确设置：
echo$GEMINI_API_KEYecho$GOOGLE_GEMINI_BASE_URL如果输出为空，说明环境变量没有正确生效。
检查网络连接是否稳定，中转站是否可访问：
curl -I https://letaicode.cn/如果这里无法访问，后续 Gemini CLI 大概率也无法正常调用。
查看是否有错误信息输出
终端里的报错信息通常很关键。
常见问题一般集中在：
key 填错 模型名称写错 中转站不可访问 环境变量没有生效 权限或路径问题
按报错逐项排查，通常能定位到原因。
SOCKS 代理格式检查
如果使用 SOCKS 代理，请确保代理格式正确，例如：
socks5://<user>:<pass>@<proxy>:<port>使用内置命令报告问题：
# 在 CLI 中直接报告 bug/bugunsetunset发布版本说明unsetunset
Gemini CLI 有不同发布版本，可以根据需求选择。
unsetunset预览版（Preview）unsetunset
每周二 UTC 23:59 发布新的预览版本。 使用 preview 标签安装：
npm install -g @google/gemini-cli@preview适合想提前体验新功能的用户。
unsetunset稳定版（Stable）unsetunset
每周二 UTC 20:00 发布新的稳定版本。 使用 latest 标签安装：
npm install -g @google/gemini-cli@latest日常使用更推荐稳定版。
unsetunset每夜版（Nightly）unsetunset
每天 UTC 00:00 发布每夜版本。 使用 nightly 标签安装：
npm install -g @google/gemini-cli@nightly每夜版适合测试新功能，但稳定性可能不如正式版本。
unsetunsetMCP 服务器使用unsetunset
Gemini CLI 支持在 ~/.gemini/settings.json 中配置 MCP 服务器，用来扩展自定义工具能力。
常见示例：
> @github 列出我的开放拉取请求> @slack 向 #dev 频道发送今天提交的摘要> @database 运行查询查找不活跃用户💡 简单理解： MCP 可以让 Gemini CLI 连接 GitHub、Slack、数据库等外部工具，让它不只是回答问题，而是真正参与到你的工作流里。
unsetunset卸载unsetunset
如果你后续不再需要使用 Gemini CLI，可以参考官方卸载指南进行卸载。