Gemini CLI 安装配置教程:Mac / Linux 全流程

如果你只是在网页里用 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

参数说明：

⚠️ 注意：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 工作流中。

如果团队已经重度使用 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/bug

unsetunset发布版本说明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，可以参考官方卸载指南进行卸载。