Gemini CLI 本地部署怎么选：安装、离线与数据去向说明

卷心菜 技术创作者 2026-11-01 11 阅读

Gemini CLI 是在终端里运行的开源 AI 编程代理；“本地部署”可能指 CLI 安装在电脑上，也可能指接入本机模型，这两种方式的数据边界完全不同。本文按官方 Gemini CLI、企业账号和个人本地模型三条路径，说明可执行的安装方式、适用场景与限制。官方仓库当前页面显示 Gemini CLI 已转为面向 Gemini Code Assist Standard / Enterprise、Code Assist for GitHub on Google Cloud，以及旧版付费 API / Vertex 密钥的工作流；个人免费访问、Google AI Pro 和 Google AI Ultra 已于 2026 年 6 月 18 日转移至 Antigravity CLI。因此，搜索“Gemini CLI 本地部署”时，首先不能把“本地运行程序”误认为“模型完全离线”。

先分清三种“本地”：程序、模型和数据

官方 Gemini CLI 是一个开源终端代理，安装在用户电脑上，但它默认连接 Google 的 Gemini 服务。程序在本地运行，不代表代码、提示词和工具调用结果都留在本地。

补充资料显示，“Gemini 本地”通常混合了三种含义：终端设备内置的 Gemini Nano、让 Gemini CLI 对接本地 LLM（语言模型，即部署在自有电脑或服务器上的模型服务），以及企业级 Gemini 部署方案。它们的区别不在于“有没有一个叫 Gemini 的命令”，而在于模型在哪里运行、请求是否离开设备、谁负责身份认证。

方案 程序在哪里 模型在哪里 是否能完全离线 适合谁
官方 Gemini CLI 用户电脑 Google 服务 默认不能 企业 Gemini Code Assist 用户
官方 Gemini CLI + 远程 API 用户电脑 Gemini API 或 Vertex AI 不能 需要云端模型能力的个人开发者
Gemini CLI 开源分支 + 本地 LLM 用户电脑 自有电脑或服务器 取决于配置 需要控制代码外发边界的团队

这张表是按官方仓库与补充资料整理的使用边界，不是官方发布的“本地部署认证清单”。实际选型时，先问两个问题：代码是否允许出网，以及是否必须使用企业许可证。

官方 Gemini CLI 的 3 种安装方式

官方仓库给出了多种安装命令。macOS、Linux 用户可以使用 npm、Homebrew 或临时运行 npx；Windows 和受限环境还可以使用 Anaconda。下面三条命令均来自 Gemini CLI 官方仓库 README，未添加来源中没有出现的参数。

  1. 不想安装，先直接运行

    在终端执行：

    npx @google/gemini-cli

    npx 会调用 npm 包执行器临时运行 Gemini CLI，不需要先做全局安装。适合第一次确认本机环境和登录流程的人；缺点是每次启动都可能需要重新获取包内容，具体速度取决于 npm 网络和缓存状态。

  2. 需要长期使用，安装 npm 全局版

    npm install -g @google/gemini-cli

    这条方式适合大多数已经使用 Node.js 和 npm 的开发者。安装后，在终端输入 gemini 启动。若系统提示找不到 gemini，先确认当前 shell 的 npm 全局可执行目录是否已经加入 PATH，再重新打开终端；这是路径问题，不代表 Gemini CLI 本身安装失败。

  3. macOS 或 Linux 使用 Homebrew

    brew install gemini-cli

    Homebrew 方式适合已经用 Homebrew 管理开发工具的 macOS、Linux 用户。它和 npm 全局安装都能提供长期可用的命令，二者选一种即可，不需要重复安装。若公司电脑禁止全局写包目录，选 npx 临时运行通常更容易通过权限检查。

受限环境可使用官方仓库给出的 Anaconda 流程：

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

这条命令链要先创建环境、激活环境，再在环境内安装 CLI。确认当前环境已激活后，再运行 gemini。不要把 conda create 和 conda activate 合并成一条命令，因为前者创建环境，后者切换当前 shell 的环境。

账号与权限：安装前必须处理的事

第一项是确认账号类型。官方仓库 README 明确提示，Gemini CLI 面向 Gemini Code Assist Standard / Enterprise 以及 Code Assist for GitHub on Google Cloud 用户；同时保留旧版付费 API / Vertex 密钥路径。个人免费访问、Google AI Pro 和 Google AI Ultra 已转向 Antigravity CLI，日期为 2026 年 6 月 18 日。这个日期是当前选择 CLI 的重要分界：不要仅凭“Gemini”名称就假定个人订阅可以直接登录 Gemini CLI。

第二项是确认 Node.js、npm 或 Homebrew 环境。运行以下命令查看版本：

node -v
npm -v

如果使用 Homebrew，再执行：

brew --version

第三项是确认认证方式。根据账号许可证准备 Gemini Code Assist、Code Assist for GitHub、旧版付费 API 或 Vertex AI 的访问条件；具体账号入口应在 Google Cloud 或 Google AI 官方认证页面完成。若使用本地 LLM 分支，则还要准备本机模型服务，并确认它提供 OpenAI 兼容 API。这里的“OpenAI 兼容 API”指请求地址和字段格式与 OpenAI API 相似，能让兼容客户端连接；它不表示数据会发送回 OpenAI。

接入本机模型：能离线，但要核对分支边界

官方 Gemini CLI 的设计重点是 Google 的企业工作流；补充资料中的 Open Gemini CLI 则是第三方 fork，其 README 声称可以连接任意 OpenAI-compatible API，包括 Ollama、vLLM、LlamaEdge 等本地模型服务。也就是说，想让代理使用本机模型，不能把“官方 Gemini CLI 安装在本机”误认为“已经离线”。

使用本地模型分支时，实际链路应是：

Gemini CLI 分支 → 本机模型服务地址 → 本机模型

若服务地址写错、模型服务没有启动或接口格式不匹配，终端中的请求就会失败。此时应先单独确认本机模型服务能响应，再把同一地址填入 CLI 配置。这个排错顺序比反复重装 CLI 更有效，因为 CLI 安装与模型服务是两个独立层次。

还要注意，开源分支的维护者、实现细节和更新节奏可能不同于 Google 官方仓库。补充资料将其描述为用于接入其他模型服务的 fork，而不是 Google 官方发布的企业离线版。因此，涉及源代码审计、许可证审查、生产环境变更和凭据管理时，应把它当作独立软件评估，不能只看名字里的“Gemini”。

数据到底会去哪里：按请求链路判断

判断隐私边界，不要看程序图标或安装目录，而要看每次请求经过哪些端点。官方 Gemini CLI 连接 Google 服务时，模型调用本身会离开本机；工具执行则可能读取工作区文件、运行命令或访问外部服务。即使模型来自本地 LLM，代理执行的 shell 命令、插件或 MCP 服务也可能主动联网。

可以按下面顺序检查：

  1. 查看启动时显示的认证方式和模型提供方，确认当前会话走的是 Google、Vertex AI、旧版 API，还是本地兼容服务。
  2. 查看 CLI 的配置目录和项目级配置，核对模型服务地址、API 地址和认证变量；不要把真实 API 密钥写进仓库或截图。
  3. 检查项目目录中是否启用了插件、MCP 或其他工具扩展，并逐个确认它们会把什么文件发送给什么服务器。
  4. 在敏感项目中，先用无敏感内容的测试目录运行一次，确认请求地址后再处理正式代码。

这是按请求链路做出的边界推导，不是 Google 对某个具体客户端作出的隐私承诺。补充资料把 Gemini CLI × 本地 LLM 描述为减少代码外发的方式，但只有在模型、插件、MCP 和依赖工具都不额外联网时，才接近真正的离线使用。

常见卡点：先分层，不要反复重装

卡点一：个人账号登录后无法使用。 官方仓库把当前 Gemini CLI 的目标用户限定在 Gemini Code Assist Standard / Enterprise、Code Assist for GitHub on Google Cloud，以及旧版付费 API / Vertex 密钥路径。先核对许可证和认证入口；如果目标是个人免费访问、Google AI Pro 或 Google AI Ultra，官方 README 指向的是 Antigravity CLI，而不是继续重复登录 Gemini CLI。

卡点二：终端找不到 gemini 命令。 先判断是否实际执行过全局安装。若只执行了 npx @google/gemini-cli，它本来就是临时运行方式，不会自动创建永久的 gemini 命令。需要长期使用时执行：

npm install -g @google/gemini-cli

然后重新打开终端，再检查 PATH 是否包含 npm 的全局可执行目录。

卡点三：本地模型能启动，CLI 却连不上。 不要把模型服务启动成功等同于 CLI 配置正确。分别确认服务监听地址、端口、API 路径和认证方式；本地模型服务通常不应暴露到公网。若本地服务只监听回环地址，CLI 也应在同一台机器上运行。

卡点四：Anaconda 安装后仍提示找不到 Node.js。 conda create 只创建环境，必须先执行 conda activate gemini_env，再执行 npm 安装。激活后用 node -v 和 npm -v 复查；确认版本存在后，再启动 gemini。

卡点五：以为“离线”就不会产生外部请求。 本地模型只解决推理请求的落点，插件、MCP、下载器、Git 命令或项目脚本仍可能联网。最小可行做法是先用隔离目录、关闭额外扩展，并从系统网络日志或代理日志中确认请求是否离开本机。

怎么算成功，以及如何继续查证

安装成功的第一层标志是：终端能够启动 Gemini CLI，并进入交互界面，而不是立即报 Node.js、权限或命令路径错误。使用 npx 时，只要出现交互界面就说明包已被执行；使用全局安装或 Homebrew 时，则应能在终端启动 gemini。

接入本机模型的成功标志更具体：CLI 能发起一次不涉及敏感内容的测试请求，本地模型服务日志出现对应请求，同时没有出现指向 Google 或其他云端模型地址的调用。若还要验证“离线”，应临时阻断外部网络后再做一次受控测试，并检查插件、MCP 和命令执行没有额外访问外部地址。

目前本文引用的官方仓库页面没有给出一组可直接复制到 Gemini CLI 中的本地模型配置文件，也没有提供统一的离线部署认证路径。因此，不能凭空写出“官方 Gemini CLI 一键离线安装命令”。如果需要标准安装和版本信息，应以官方仓库 README 及其安装文档为准；如果需要本地模型接入，应阅读对应 fork 的 README，并把该 fork 当作独立软件审查。

延伸阅读入口：

如果只是要试运行，优先执行 npx @google/gemini-cli；如果项目代码不能出网，则先准备本地模型服务，再选择经过审查的兼容分支，并用网络阻断测试确认它确实没有偷偷访问云端。

# AI# 知识

评论区

0 条评论

登录后可评论。

卷心菜 11 阅读