把 AI 装进电脑：Gemini CLI 从安装到实战

不是再开一个聊天框，而是让 AI 读文件、跑命令、整理资料、生成交付件。

一、为什么 Gemini CLI 值得普通人学

很多人用 AI 的方式仍然停留在复制粘贴：把资料扔进聊天框，等一段文字，再手动搬回 Word、Excel、代码编辑器或文件夹。真正耗时间的，其实不是“让 AI 想一句话”，而是反复打开文件、对照资料、复制命令、检查格式。

Gemini CLI 的价值就在这里：它把 Gemini 放进终端，让 AI 可以在本地项目目录里工作。它能读取文件、理解项目结构、给出修改建议，也能在确认后写文件、运行命令、调用 Web Fetch / Web Search，甚至接入 MCP 扩展更多工具。

这篇文章不把它讲成神话。它不是“安装后电脑自动替人干活”的魔法，也不是只给程序员看的黑窗口。把路径、权限和边界设置好后，它更像一个可以跟着项目资料一起工作的电脑助手。

图 1｜本篇按官方文档、Google Developers 页面、Node.js/npm 文档核对；界面和额度以后可能变化，正式使用前应再检查一次。

先说结论

·想快速体验：安装 Node.js LTS，执行 npm install -g @google/gemini-cli，然后运行 gemini。

·想少踩坑：Windows 新手优先用 PowerShell；每个任务单独建文件夹；关键规则写进 GEMINI.md。

·想提高效率：先做“读资料、写初稿、整理清单”这类低风险任务，再做“改代码、跑命令、批处理”。

·想保证安全：不在陌生项目里直接 yolo；不把密钥写进公开文件；写文件和执行命令前先看确认提示。

二、核源纠偏：它到底是什么，不是什么

官方对 Gemini CLI 的定位很明确：它是开源 AI agent，直接在终端访问 Gemini；官方文档也强调它可以通过内置工具与本地环境交互，包括文件系统、Shell、Web Fetch / Search、MCP 等能力。

这意味着，它比普通聊天网页更接近“工作流入口”，但它也需要更多责任感：读文件、写文件、跑命令都可能影响本地项目，必须把权限看清楚。

本篇按 2026-05-08 可查资料整理

·安装与运行：官方推荐 npm 全局安装，也支持 Homebrew、MacPorts、Anaconda、npx、Docker/Podman 沙箱和源码运行。

·系统要求：官方安装页写明推荐 Node.js 20.0.0+，支持 PowerShell / Bash / Zsh；普通使用 4GB+ 内存，长会话和大项目建议 16GB+。

·认证方式：本地交互最简单是 Login with Google；也可以配置 Gemini API Key 或 Vertex AI。

·配置方式：支持环境变量、命令行参数、用户级 settings.json、项目级 .gemini/settings.json、GEMINI.md 项目上下文文件。

图 2｜从环境安装到项目实战的完整路径：先跑通，再提效，最后再考虑自动化和放权。

三、安装前准备：电脑上先有 Node.js 和 npm

Gemini CLI 的标准安装方式依赖 npm。npm 通常随 Node.js 一起安装，所以第一步不是直接敲 Gemini 命令，而是确认电脑上已经有 Node.js 与 npm。

图 3｜Windows 新手建议从 Node.js 官网下载 LTS 版本；不建议从不明网盘下载运行环境。

Windows 新手建议这样做

1.打开 Node.js 官网下载页，优先选择 LTS 版本。LTS 更适合普通用户和稳定工作流。

2.下载 Windows 64-bit Installer。一般 Intel/AMD 电脑选 x64，ARM 设备才考虑 arm64。

3.安装时按默认路径继续即可，重点是确保安装器能把 node / npm 加入 PATH。

4.安装完成后，不要在原来的 PowerShell 窗口里继续敲命令，先关闭再重新打开。

图 4｜Windows 安装器的关键不是复杂配置，而是让 node、npm 能被 PowerShell 识别。

四、检查环境：先看到版本号，再装 CLI

打开 PowerShell，先执行下面两条命令。如果都能输出版本号，说明电脑已经具备安装 Gemini CLI 的基础环境。

图 5｜node -v 和 npm -v 有版本号，是最简单的环境检查。

如果 PowerShell 里提示找不到 node / npm

·第一步：关闭 PowerShell，重新打开一个新窗口。很多 PATH 变量要新窗口才生效。

·第二步：在 Windows 搜索“环境变量”，检查 Path 里是否包含 Node.js 安装目录。

·第三步：仍然不行，再重新安装 Node.js LTS，并确认安装路径没有被安全软件拦截。

·第四步：企业电脑或受限电脑，考虑用 Anaconda 环境或让管理员安装。

五、正式安装 Gemini CLI：包名别写错

官方 npm 安装命令是下面这一条。重点是完整包名必须包含 @google/ 前缀。

安装完成后，执行版本检查：

图 6｜官方包名是 @google/gemini-cli；不要安装 gemini-cli、gemini/cli 等相似名字。

macOS / Linux 常用安装方式

六、第一次启动：选择授权方式

安装完成后，在项目目录里执行 gemini。首次运行时会出现授权选择。普通个人电脑优先选择 Login with Google；如果是在脚本、服务器或自动化流程里，再考虑 API Key 或 Vertex AI。

图 7｜本地电脑优先选 Login with Google；API Key 更适合脚本和无界面环境。

三种授权方式怎么选

·Login with Google：最适合个人电脑和日常交互；浏览器完成登录后，凭证会缓存在本地。

·Gemini API Key：适合脚本、自动化和无界面环境；需要保护密钥，不要写进公开仓库。

·Vertex AI：适合企业、云项目和权限管控更严格的团队；需要 Google Cloud Project、Location 和相应 IAM 权限。

图 8｜授权通常会打开浏览器，完成登录后回到终端；如果远程服务器没有浏览器，需要改用环境变量方式。

七、网络与代理：国内用户最容易卡在这里

有些电脑会出现“浏览器能打开 Gemini，但 CLI 登录或请求失败”的情况。原因通常不是安装错了，而是终端没有走同一个网络环境，或者公司网络拦截了证书。

Windows PowerShell 临时代理写法

下面这段只影响当前 PowerShell 窗口，适合排查。端口按本机代理工具实际端口修改。

·如果设置后能登录，说明问题大概率在终端网络环境。

·如果报证书错误，企业网络可能做了 TLS 检查，需要配置信任的根证书。

·如果一直 429，不要反复重试；先降低请求频率或检查账号配额。

·如果 npm 安装慢或失败，先单独排查 npm registry 与网络，别把 Node.js、npm、Gemini CLI 三个问题混在一起。

八、正确打开方式：每个任务单独建工作区

Gemini CLI 不是单纯问答窗口。它会以当前目录作为工作上下文，读写文件也围绕这个目录展开。最容易出问题的用法，是在桌面、下载目录、系统目录里随手启动。

更稳的方式，是给每个任务单独建一个工作区。比如写公众号文章、整理 Excel、检查代码、处理客户资料，都放在不同文件夹。

图 9｜每个任务独立文件夹，才能清楚知道 Gemini CLI 看到了哪些文件、可能改哪些文件。

推荐目录结构

·GEMINI.md：写项目规则、交付格式、禁止项。

·source-notes.md：放资料摘要、链接、原始笔记。

·images/ 文件夹：放截图、示意图、参考图。

·output/：放生成结果，不要和原始资料混在一起。

九、GEMINI.md：让 AI 记住项目规则

很多人觉得 CLI agent 难控制，根本原因是每次只给一句临时提示。GEMINI.md 的作用，就是把长期规则写进项目根目录，让 Gemini CLI 每次进入这个工作区都能先读规则。

图 10｜GEMINI.md 写项目规则；.gemini/settings.json 写更底层的配置。

公众号项目可以这样写

十、权限与安全：确认框不是摆设

Gemini CLI 的强大之处，在于能调用工具处理本地文件和命令；风险也在这里。官方文档强调，写文件、编辑文件、执行命令等敏感工具通常会要求确认，运行在沙箱中也可以降低副作用。

图 11｜看到文件修改 diff 后再决定是否允许；第一次接触项目时，不建议直接全部自动通过。

三种权限习惯

·新项目：只允许读取和解释，先让它输出计划，不急着改文件。

·小改动：Allow once，看清 diff 后逐次确认。

·可信项目：可以考虑 auto_edit，但运行命令仍建议保留确认。

关于 yolo，要非常克制

--approval-mode=yolo 会自动批准所有工具调用。它适合高度可信、可回滚、低风险的临时任务，不适合陌生项目、客户资料、生产代码、系统目录和含密钥文件的环境。

十一、真实案例 1：公众号资料整理

适合非程序员第一次试手。把资料、链接、截图说明放进工作区，让 Gemini CLI 读取后整理成结构化文章。

图 12｜用 Gemini CLI 做公众号初稿，不是让它凭空写，而是让它读取素材、核对来源、组织成稿。

可复制提示词

·低风险：主要是读资料和写文本。

·高收益：能把零散笔记整理成可发布框架。

·人工必须做：最后核对来源、删除口水话、检查图文节奏。

十二、真实案例 2：代码项目解释与修 bug

Gemini CLI 最典型的场景仍然是代码。正确流程不是“帮我把项目重写”，而是先让它解释结构，再聚焦一个具体问题。

图 13｜先解释架构，再定位 bug，再小步提交修改建议，风险远低于一次性大改。

推荐工作流

5.第一轮：Explain this repository architecture。先让它读项目结构。

6.第二轮：Ask questions before editing。让它先提出判断依据。

7.第三轮：只改一个文件或一个函数。确认 diff。

8.第四轮：运行测试或静态检查。把错误结果喂回去。

9.第五轮：要求输出修改总结和回滚说明。

十三、真实案例 3：CSV / Excel 数据清洗

Gemini CLI 不能直接替代 Excel 的可视化编辑，但它适合生成清洗脚本、检查字段问题、把脏数据转成规范表。适合销售流水、库存表、活动报名表、问卷结果。

图 14｜让 CLI 先生成脚本清洗 CSV，再用 Excel 打开核对，比手工一行行改更稳。

可复制提示词

·适合：批量清洗、格式统一、异常值标注、生成摘要。

·不适合：完全依赖它判断财务口径、税务口径、库存最终数量。

·关键：让它先读样本和提规则，再写脚本；不要直接覆盖原表。

十四、真实案例 4：网页研究与文章核源

做公众号最怕的是把二手传闻写成事实。Gemini CLI 的 Web Fetch / Search 能帮助整理网页信息，但最终仍要以官方来源优先。

图 15｜让工具把“已确认、待复查、不能写”的信息分开，文章事实风险会小很多。

推荐提示词

十五、进阶：把 Gemini CLI 放进脚本

熟悉交互模式后，可以尝试 headless mode。它通过 --prompt 或 -p 直接传入提示词，适合日志分析、生成 release notes、批量代码检查、把结果输出成 JSON。

图 16｜Headless mode 适合自动化，但也更需要凭证、权限和输出格式控制。

·适合做每天重复的格式化任务。

·适合接入现有 shell / PowerShell 脚本。

·不适合在没有审计的情况下自动改生产文件。

·无界面环境要提前配置 API Key、Vertex AI 或已缓存凭证。

十六、常用命令：会这几个就够用

Gemini CLI 里的很多控制命令用斜杠开头。新手至少要掌握保存/恢复会话、压缩上下文、复制输出、添加目录、查看工具和权限设置。

图 17｜常用命令速查：长任务不要只靠一直往下聊，学会保存、恢复和压缩上下文。

几个值得优先学的命令

·/chat save <tag>：做复杂任务前保存状态，方便后面恢复。

·/compress：长会话快撑爆上下文时，先压缩，再继续。

·/directory add <path>：把相关目录加入工作区，但不要把整个硬盘加进去。

·/tools：查看当前能调用哪些工具。

·/permissions：重新设置当前文件夹的信任与权限。

十七、模型、配置和上下文：别只会敲 gemini

Gemini CLI 支持通过 settings.json、环境变量和命令行参数调整行为。官方配置文档列出了优先级：命令行参数优先级最高，其次是环境变量，项目设置和用户设置再往下。

常用配置思路

·临时换模型：gemini -m 模型名。适合某次会话使用，不影响全局。

·固定项目规则：写进 .gemini/settings.json 或 GEMINI.md。

·敏感凭证：优先放环境变量或 .gemini/.env，不要写进公开文档。

·上下文太长：用 /compress 或提高任务拆分粒度。

·大项目读取：先让它说明会读哪些文件，再允许读取，不要一开始 --all-files。

十八、安装和登录最常见报错

Gemini CLI 的问题通常集中在四类：环境变量/PATH、账号授权、网络证书、额度。排查时不要一上来重装系统，也不要把所有命令混在一起试。

图 18｜错误排查按关键词处理：PATH、授权、证书、额度，是最常见四类。

遇到问题的标准排查顺序

10.先确认 node -v、npm -v、gemini --version 三个命令分别是否可用。

11.再确认当前 PowerShell 是否能访问外网，必要时临时设置代理变量。

12.再看授权方式：Google 登录、API Key、Vertex AI 不要混用。

13.最后看账号额度、地区和组织权限。Workspace 账号可能需要 Google Cloud Project。

十九、安全底线：把电脑交给 AI 前先画边界

Gemini CLI 能做的事越多，越不能把它当普通网页聊天。尤其是有客户资料、公司代码、密钥、证照、合同的项目，必须先设边界。

图 19｜安全底线不是吓人，而是让工具长期可用、可控、可追溯。

推荐默认策略

·陌生仓库：只读解释，不允许执行脚本。

·个人项目：允许读文件，小步改动，每次看 diff。

·公开资料整理：可以让它生成草稿，但事实核对人工做。

·含密钥/合同/客户资料：先复制脱敏版本到独立目录。

·需要自动化：脚本必须写日志，结果输出到新文件，不覆盖原文件。

二十、第一次上手照这张清单走

图 20｜第一次安装和使用，按这一页逐项打勾。

30 分钟上手路线

14.0-5 分钟：安装 Node.js LTS，确认 node -v / npm -v。

15.5-10 分钟：npm 安装 Gemini CLI，执行 gemini --version。

16.10-15 分钟：运行 gemini，完成 Login with Google。

17.15-20 分钟：创建专用工作区，写一个最小 GEMINI.md。

18.20-30 分钟：让它读取一份 README 或资料笔记，只做解释和整理，不改文件。

二十一、可直接复制的提示词模板

模板 1：安装完成后的自检

模板 2：让它先出计划，不直接动手

模板 3：公众号文章工作流

结尾：会用 CLI 的人，正在少做很多重复劳动

Gemini CLI 的关键价值，不是让 AI 多会说几句话，而是把 AI 放到真实工作目录里：读资料、理解上下文、写文件、跑命令、生成可交付结果。

普通人不一定要学很深的编程，也可以先从资料整理、公众号初稿、CSV 清洗、批量改名、网页核源这些低风险场景开始。

真正的分水岭不是“会不会安装一个工具”，而是能不能把任务拆成清楚的输入、规则、权限和输出。把这套流程建立起来，AI 就不再只是聊天框，而会变成电脑里的工作流助手。

资料来源与核对说明

核对日期：2026-05-08。以下来源用于核对安装命令、系统要求、认证方式、工具能力、配置路径、命令参数、安全边界和常见问题。

·Google Gemini CLI 官方文档：Installation、Authentication、Configuration、Commands、Tools、Headless Mode、Troubleshooting。

·Google Developers：Gemini CLI / Gemini Code Assist 文档。

·Google 官方博客：Gemini CLI: your open-source AI agent。

·Node.js 官方下载页、npm 官方安装说明。

·安全提醒部分参考了 2026 年 5 月公开报道中关于相似包名和伪装 CLI 工具的风险提示；具体安装仍以官方仓库和 npm 包名为准。