Gemini CLI 本地运行教程：离线能力与硬件门槛
Gemini CLI 是运行在终端里的 Gemini 编程代理，可用来分析代码、修改文件和执行开发任务。
截至 2026 年 10 月 15 日，官方安装文档已经明确列出系统、内存、Node.js 与网络要求；值得现在厘清的是，“本地运行”通常只表示程序运行在电脑上，并不等于模型也完全离线。
先分清：本地安装不等于离线推理
Gemini CLI 的程序可以装在本机，但默认使用 Google 托管的 Gemini 服务。官方安装文档把 Internet connection required 列为运行条件，因此只有客户端而没有网络，通常无法正常完成模型请求。
截至 2026 年 4 月 28 日发布的实验性文档还提供了一种例外：Local Model Routing Setup，即本地模型路由。它允许本机运行的 Gemma 模型负责部分路由决策，而不是把这类决策发送给托管模型。这里的“路由”是 CLI 决定把请求交给哪个模型或处理流程；它不等于整套编码代理、所有上下文和所有模型能力都已离线化。
因此，搜索“Gemini CLI 本地部署”时，实际对应三种需求：
| 目标 | 能否实现 | 需要的条件 | 关键限制 |
|---|---|---|---|
| 把 CLI 安装到自己的电脑 | 可以 | Node.js 20.0.0+、受支持系统、网络 | 模型通常仍在云端运行 |
| 在隔离环境中运行 CLI | 可以 | Docker 或 Podman | 隔离程序运行，不等于离线推理 |
| 用本地模型承担部分路由 | 可以，实验性功能 | 本地 Gemma 模型、HTTP 服务及 Gemini API 接入 | 不是完整离线模式，配置步骤更复杂 |
官方安装页同时提供 npx、全局 npm、Homebrew、MacPorts、Anaconda、源码运行和容器运行等路径。沙箱是用于隔离文件系统和网络访问的容器环境；把 CLI 放进容器，可以减少它直接接触宿主机环境的风险，但默认模型请求仍需要联网。
本地安装前，准备这三项条件
- 检查 Node.js。 官方要求 Node.js 20.0.0 或更高版本，运行下面的命令并确认版本号不低于
v20.0.0：
node --version- 确认操作系统。 官方推荐 macOS 15+、Windows 11 24H2+ 或 Ubuntu 20.04+。Windows 可在“设置 → 系统 → 系统信息”查看系统版本；Linux 可执行下面的命令：
cat /etc/os-release- 准备网络与访问方式。 默认使用方式需要网络连接；还要准备 Google 账号、Gemini Code Assist Standard 或 Enterprise 许可、Google Cloud 上的 Code Assist for GitHub，或者旧版付费 API 与 Vertex AI 凭据。当前官方仓库说明，免费个人访问以及 Google AI Pro、Ultra 账户已经转向 Antigravity CLI，不再属于当前 Gemini CLI 的免费档。
硬件方面，官方给出的分界很清楚：短会话、普通任务和常规编辑建议至少 4GB RAM；长时间会话、大型代码库和深度上下文建议 16GB RAM 以上。官方没有给出 GPU 最低要求，因为常规 Gemini CLI 的主要推理负载并不在本机执行；只有实验性的本地 Gemma 路由，才需要额外考虑本地模型运行环境和 GPU。
三种安装方式，按使用场景选
临时试用：直接用 npx
不想改系统环境时，优先使用 npx。官方给出的完整命令是：
npx @google/gemini-clinpx 会临时获取并运行 npm 包，省去全局安装。适合先确认账号、目录权限和认证流程是否正常，但每次启动都可能重新解析和获取软件，不适合作为长期固定的工作入口。
日常使用：全局安装 npm 包
需要长期在多个项目中使用时，采用官方推荐的全局安装方式：
npm install -g @google/gemini-cli安装后，在终端运行：
gemini这条路径与官方文档面向多数用户的建议一致：使用 gemini 命令启动。它适合固定工作站、开发服务器以及需要自定义 shell 环境的用户。macOS 或 Linux 如果习惯 Homebrew，也可以使用官方列出的命令：
brew install gemini-cli隔离执行：使用 Docker 或 Podman
需要把 CLI 与宿主环境隔开时，可以使用官方文档中的 Docker/Podman Sandbox 路径。它更适合处理不可信代码、审查外部项目补丁，或要求限制文件访问范围的场景。容器解决的是“运行隔离”，不是“模型离线”；容器内部仍需要能访问配置好的模型服务。
选择顺序可以概括为：先临时验证用 npx，长期工作用 npm 或 Homebrew，必须隔离时才增加容器复杂度。若需求只是“断网也能完整编码”，这三条路径都不够，因为默认模型调用明确依赖互联网。
离线需求：实验性本地模型路由怎么配
本地路由的官方方案要求三项条件同时成立：本机运行一个 Gemma 模型实现；该实现通过 HTTP 端点提供服务；Gemini CLI 再通过 Gemini API 接入它。HTTP 端点可以理解为程序之间传递请求的本地网络地址。
官方文档给出的 Windows 手工验证命令是：
.lit.windows_x86_64.exe serve --verbose这个命令启动 LiteRT-LM 的本地服务，并打开详细输出。Windows 图形加速还需要 DirectXShaderCompiler；官方文档要求从相应发行版下载 dxc 压缩包，解压后从架构对应的 bin 目录把 dxil.dll 和 dxcompiler.dll 放到 lit.windows_x86_64.exe 所在目录。
这里最容易被误解的是作用范围：本地 Gemma 只承担“路由决策”，并没有因此替代 Gemini CLI 后续需要调用的全部模型能力。按照官方描述推导，只有实际被路由到本地模型且该路径不再访问托管服务的请求，才会减少相应的云端依赖；代码理解、文件修改或需要更强模型能力的环节是否仍联网，要看具体任务与模型配置，不能把这一功能理解为完整离线代理。
常见卡点：先看认证和运行条件
官方安装页和仓库说明已经把最常见的失败条件列得很具体，但它们没有给出一个可以覆盖所有环境的统一报错文本，因此不要只盯着某一句英文提示。
安装后提示找不到 Node.js 或版本不符。 执行 node --version，确认输出达到 v20.0.0 或更高；不满足时先升级 Node.js，再重新运行全局安装命令。若全局安装后仍找不到 gemini，优先检查 npm 的全局可执行目录是否已经加入 PATH，而不是反复重复安装。
能启动 CLI，但登录或请求失败。 官方仓库当前列出的适用对象包括 Gemini Code Assist Standard 或 Enterprise、Google Cloud 上的 Code Assist for GitHub，以及旧版付费 API 或 Vertex AI 凭据。免费个人账号或 Google AI Pro、Ultra 账户应先核对是否已经转向 Antigravity CLI，而不是继续在 Gemini CLI 内反复认证。
能够打开终端，却无法稳定调用模型。 检查网络连接和当前选择的认证方式，再确认系统是否位于官方列出的 Gemini Code Assist 支持地区。容器环境还要单独检查容器内能否访问网络；宿主机联网不代表容器必然具备相同网络配置。
准备把本地 Gemma 当成完整离线方案。 先确认 HTTP 服务确实由 .lit.windows_x86_64.exe serve --verbose 启动，并检查 Gemini CLI 实际指向的端点。官方将其标为 experimental，说明接口和配置可能调整；正式使用前应重新核对当前实验性文档，而不是沿用旧博客中的地址或字段名。
怎么确认已经跑通
完成安装后，按三个可观察结果验收。
第一，执行：
gemini终端应出现 Gemini CLI 的交互界面，而不是包管理器报错。
第二，在支持的认证方式下完成登录，并确认命令行能够显示当前账号或认证状态。仓库当前面向的是组织许可、Google Cloud Code Assist for GitHub 或旧版付费 API/Vertex AI 凭据；使用其他账户时不能把登录成功等同于具备当前许可。
第三，进入一个测试项目，让 CLI 读取一个小文件并解释其用途。成功标志是终端返回与文件内容一致的回答，而不是只显示欢迎页。若这一环节超时或返回认证错误，优先检查网络、账号类型与认证方式；不要先归咎于本地硬件。
如果目标是完全断网使用，按前面的边界推导，目前官方给出的实验性本地路由只能减少部分托管模型路由，不能保证整个编码流程离线。需要先明确“哪些请求必须留在本机”，再围绕该范围测试。
官方入口与继续排查
安装、系统要求、发布方式和高级运行方式，以官方安装文档为准：
https://geminicli.com/docs/get-started/installation/
本地 Gemma 路由的命令、运行环境和实验性限制，以本地模型路由文档为准：
https://geminicli.com/docs/core/local-model-routing/
项目状态、适用账号、安装命令和源代码，以官方仓库为准：
https://github.com/google-gemini/gemini-cli
仓库 README 的定位入口可直接查看：
https://github.com/google-gemini/gemini-cli#readme
需要确认版本变化或提交记录时，继续查看官方仓库的 Releases、Issues 和 Discussions；遇到认证、模型路由或容器权限问题时，在对应 Issue 中附上操作系统、Node.js 版本、安装方式与可复现命令，会比只贴“无法运行”更容易得到有效排查。
参考来源
评论区
登录后可评论。