适用场景与准备工作

Gemini CLI 常用于终端内的代码解释、文档生成、脚本辅助和批量文本处理。

若希望减少外部服务依赖，或需要在内网、实验环境中运行模型，可以把它配置为连接本地推理服务。

需要先说明一点：CLI 本身通常是命令行交互层，本地运行的关键在于后端推理引擎，例如 Ollama、llama.cpp、LM Studio 或其他兼容 OpenAI 接口的服务。Gemini CLI 负责发送请求、展示结果，本地模型负责实际生成内容。

开始前建议准备三类资源：

• 硬件：日常文本任务建议至少 16GB 内存；运行 7B 级量化模型更稳妥，13B 及以上模型对显存和内存要求明显提高。
• 磁盘空间：常见量化模型从数 GB 到数十 GB 不等，应预留模型文件两倍以上空间。
• 系统环境：Windows、macOS、Linux 均可使用，但路径写法、权限设置和后台服务启动方式不同，配置时要按系统区分。

安装 Gemini CLI 与本地推理后端

安装 Gemini CLI

安装 Gemini CLI 前，先确认本机已有 Node.js 或官方要求的运行环境。可在终端输入 node -v 检查版本，若提示不存在，需要先安装长期支持版本。

随后使用 npm 安装对应 CLI 包。安装完成后执行 gemini --version 或相近版本检查命令，确认命令可被系统识别。

如果终端提示“command not found”，通常是全局包目录没有加入 PATH，需重新打开终端或手动补充环境路径。

选择本地推理后端

本地推理后端可按习惯选择：

• Ollama：适合新手，模型管理简单，拉取、运行、更新都比较直观。
• llama.cpp：适合希望细调参数、追求轻量部署的用户。
• LM Studio：适合偏图形界面的用户，也能提供本地接口。

无论选择哪一种，都要确认它能在本机开放一个 HTTP 接口，并兼容常见的聊天补全格式。后续 Gemini CLI 只需要把请求地址改为本地地址，例如 http://127.0.0.1:11434 或本机其他端口。

模型下载与选择建议

模型选择建议

模型下载要优先选择来源清晰、说明完整、社区反馈较多的版本。常见选择包括通用对话模型、代码模型、长文本模型和中文增强模型。

新手不建议一开始就下载体积最大的模型。7B 或 8B 级别的量化版本更适合验证流程。量化格式可降低内存占用，常见有 Q4、Q5、Q8 等，数值越高通常质量更好，但资源消耗也更高。

若主要用于代码解释和命令生成，可选择代码能力更强的模型；若主要做中文写作和总结，可选择中文表现更稳定的模型。

模型下载方式

下载方式取决于后端：

• 使用 Ollama 时，可通过 ollama pull 模型名 拉取，完成后用 ollama list 查看已安装模型。
• 使用 llama.cpp 时，通常需要手动下载 GGUF 文件，并保存到固定目录。
• 使用 图形工具 时，可在模型库中选择下载位置。

建议建立统一目录，例如 D:AIModels 或 /Users/用户名/AIModels，避免把模型分散在下载目录、桌面和临时文件夹中，后期迁移和备份会更容易。

路径设置与环境变量配置

路径配置分为两层：模型文件路径和CLI 访问地址。

模型文件路径由本地推理后端读取。例如，llama.cpp 启动时需要指定 -m 参数指向 GGUF 文件；Ollama 通常把模型放在自己的管理目录中，用户不必手动指定单个文件。

CLI 访问地址则用于告诉 Gemini CLI 把请求发送到哪里。若 CLI 支持配置文件，可在配置项中设置 baseURL、model、apiKey 等字段；若支持环境变量，可设置 GEMINI_BASE_URL、GEMINI_MODEL 或工具文档中指定的变量名。

在 Windows 中设置环境变量时，要注意反斜杠可能需要转义，路径中有空格时应使用英文引号。macOS 和 Linux 中可把变量写入 .zshrc、.bashrc 或当前 Shell 配置文件，修改后执行 source 使其生效。

为了避免误连到外部服务，建议把本地地址明确写成 127.0.0.1，并在第一次运行时查看后端日志，确认请求确实到达本机服务。

连接本地模型的基本流程

推荐按“先后端、再 CLI、最后任务”的顺序排查。

第一步：启动本地推理服务。例如 Ollama 需要先确认后台服务已运行，再执行模型测试命令；llama.cpp 可通过 server 模式启动，并指定模型文件、端口、上下文长度和线程数。

第二步：用简单请求验证后端能返回内容，可使用后端自带命令或本机 HTTP 测试工具。

第三步：打开 Gemini CLI，把模型名和接口地址指向本地服务。

第四步：输入一个短问题，例如“用三句话解释递归”，观察响应速度、中文质量和日志输出。

如果 CLI 默认要求鉴权字段，而本地服务不校验，可填入占位值，例如 local-key，但不要把真实密钥写入公开脚本。团队环境中建议使用 .env 文件或系统变量保存配置，并把含有个人信息的配置文件加入忽略列表，避免提交到代码仓库。

性能优化：从模型、参数到硬件

本地模型运行速度主要受 模型规模、量化级别、上下文长度、CPU 线程、显存和磁盘读写 影响。

若响应很慢，优先尝试更小的模型或更低位量化，而不是盲目提高线程数。线程数通常设置为物理核心数或略低，过高可能造成系统卡顿。

上下文长度也不是越大越好，长上下文会显著增加内存占用。日常问答可先设为 4096 或 8192，只有处理长文档时再提高。

有独立显卡的设备可开启 GPU 卸载，把部分层放到显存中计算。参数名称因后端而异，llama.cpp 常见为 ngl 或 gpu-layers，Ollama 则可自动适配部分硬件。

显存不足时会出现启动失败、速度异常下降或系统变得不稳定，此时应减少卸载层数、换用更小模型或降低上下文。磁盘方面，建议把模型放在 固态硬盘，首次加载会更快。笔记本用户还要注意电源模式，节能模式会明显限制推理速度。

常见问题与排查方法

• 问题一：CLI 提示连接失败。先确认后端服务是否启动，再检查端口是否一致，最后确认地址没有写成错误的主机名。
• 问题二：模型名不存在。Ollama 用户可执行列表命令查看真实名称，llama.cpp 用户要确认启动服务时使用的模型标识与 CLI 配置一致。
• 问题三：中文输出质量差。可换用中文能力更好的模型，并在系统提示中要求使用简体中文回答。
• 问题四：回答中断或报内存错误。通常是上下文过长、模型过大或并发请求过多，需要降低参数。
• 问题五：速度忽快忽慢。可能是后台任务占用资源、设备温度过高、模型首次加载尚未完成，也可能是系统把进程调到低优先级。可以关闭不必要的软件，观察 CPU、内存和显存占用。
• 问题六：CLI 能连上但返回格式异常。说明本地接口与 CLI 期望格式不完全一致，可尝试开启 OpenAI 兼容模式，或更换支持度更好的后端。

安全边界与使用建议

本地部署并不等于没有风险。模型文件可能包含来源不明的配置或脚本，下载前应查看发布者信息、校验文件完整性，并避免运行陌生安装脚本。

不要把包含密钥、客户资料、未公开代码的内容随意输入到不可信模型或插件中。即使在本机运行，也要注意日志文件可能记录提示词和输出内容，团队设备应定期清理敏感日志。

对开发者来说，Gemini CLI 接入本地模型最适合做可控的辅助工作，例如代码摘要、单元测试草稿、文档初稿、提交说明和批量格式整理。对于需要高准确率的生产操作，应保留人工复核流程。

建议先建立一个小模型用于日常快速问答，再准备一个质量更高的模型处理复杂任务；同时把配置文件、模型目录、启动脚本和参数说明记录下来，方便迁移到新设备或交给团队成员复用。

结语：先跑通，再精调

完整流程可以概括为：安装 CLI，选择本地推理后端，下载合适模型，设置模型路径和本地接口地址，验证连接，再围绕速度、质量和资源占用逐步调参。

不要一开始追求最大模型和最高参数。先用轻量模型跑通链路，确认任务效果后再升级模型规模。这样既能降低故障排查难度，也能让 Gemini CLI 在本地环境中稳定承担日常 AI 命令行任务。