企业官网建设流程全解析

1. 为什么要在本地折腾 Gemini CLI 这套 Vibe Coding 工作流

如果你最近在找一款能白嫖、又能真正在终端里帮你写代码的 AI 助手，Gemini CLI 大概率已经出现在你的候选清单里了。它是什么？简单说，就是 Google 官方开源的命令行 AI 代理工具，跑在你的终端里，能读写文件、执行 shell 命令、联网搜索、抓取网页，还能通过 MCP（模型上下文协议）挂载自定义工具。适合谁？适合所有习惯在命令行里干活、又不想为 Claude Code 每月掏 20 到 200 美刀的开发者。

我自己的主力环境是 macOS，日常用 ServBay 管理本地开发所需的 Node.js、PHP、数据库这些运行时，编辑器是 VS Code。这套组合的好处是：ServBay 负责把 Node.js 环境一键装好，Gemini CLI 负责在终端里当我的结对程序员，VS Code 负责最后的代码审阅和微调。三者串起来，就是一个完整的本地 Vibe Coding 工作流——你负责描述意图，AI 负责产出，你负责验收。

但很多人卡在第一步：Node.js 版本不对、npx 拉取超时、MCP 服务接不上、终端里报一堆看不懂的错。这篇就按「环境准备 → 安装 CLI → 接入 MCP → 验证调用 → 排错」的顺序，把每一步的可复制配置和验证动作都写清楚。你跟着做，半小时内应该能在本地跑通一条完整的「终端下指令 → AI 调工具 → 返回结果」链路。

核心检索词先明确：Gemini CLI 是一个终端优先的 AI 编码代理，依赖 Node.js 20+，通过 MCP 扩展能力，配合 ServBay 可以极速搞定本地运行时环境。下面进入实操。

2. 用 ServBay 准备 Node.js 环境与 VS Code 终端链路

2.1 为什么选 ServBay 而不是手动装 Node.js

手动装 Node.js 的痛点在于版本管理。你可能系统里已经有一个 Node 18，但 Gemini CLI 要求 20 以上；或者你装了 nvm，但终端 shell 配置没生效，导致node -v和npx用的不是同一个版本。ServBay 的思路是把运行时当「软件包」来管理，点几下就装好，路径也统一，省去很多环境变量折腾。

从 ServBay 官网下载安装包，装好后打开主界面，左侧菜单找到「软件包」，在列表里找到 Node.js。这里注意：Gemini CLI 官方要求 Node.js 20 或更高版本，所以别选 18，直接选 20 LTS 或 22。点击安装，全程大概一分钟。

装完后，ServBay 会把 Node.js 的可执行文件放到它自己的 bin 目录下。你需要确认终端能找到它。打开终端，执行：

node -v npm -v npx -v

如果三个命令都能输出版本号，且node -v显示 v20.x 或更高，说明环境就绪。如果提示 command not found，说明 ServBay 的 bin 目录没进 PATH。你可以在 ServBay 界面里找到「终端」或「环境变量」相关设置，或者手动把路径加进去。macOS 下通常是：

export PATH="/Applications/ServBay/bin:$PATH"

把这行加到你的~/.zshrc或~/.bash_profile里，然后source一下。验证方式就是重新开一个终端窗口，再跑一次node -v。

2.2 VS Code 终端与 ServBay 环境的衔接

VS Code 内置终端默认继承系统 shell 的环境变量。如果你在系统终端里node -v正常，但 VS Code 终端里报错，多半是 VS Code 启动时没加载你的 shell 配置。解决办法：在 VS Code 里按Cmd+Shift+P，搜索「Terminal: Select Default Profile」，选 zsh 或 bash，然后重启 VS Code。

另一个常见坑是：ServBay 可能同时装了多个 Node 版本，你在系统终端里用的是 20，但 VS Code 终端里解析到的是另一个。验证方法是在 VS Code 终端里也跑一遍which node和node -v，确认路径和版本一致。

这一步做完，你的本地环境就具备了跑 Gemini CLI 的基础条件。接下来装 CLI 本身。

3. 安装 Gemini CLI 并写入可复制的 MCP 配置片段

3.1 安装 Gemini CLI 的两种方式

第一种是免安装直接跑：

npx https://github.com/google-gemini/gemini-cli

这条命令会从 GitHub 拉取最新代码并执行。首次运行会提示你选择主题颜色，然后走 Google 账户 OAuth 登录。登录完成后，你就进入了 Gemini CLI 的交互界面。免费套餐的额度是每分钟 60 次请求、每天 1000 次请求，模型是 Gemini 2.5 Pro，上下文窗口 1M token。对个人开发来说，这个额度相当够用。

第二种是全局安装，适合长期使用：

npm install -g @google/gemini-cli

装完后直接输入gemini就能启动。如果你要用 API Key 而不是 OAuth，可以设置环境变量：

export GEMINI_API_KEY="你的_API_KEY"

API Key 适合需要更高请求容量或指定模型的场景。OAuth 适合个人快速上手。

3.2 MCP 配置：让 Gemini CLI 挂载自定义工具

MCP 是 Gemini CLI 扩展能力的核心。它允许你把外部服务（比如数据库查询、文件系统操作、第三方 API）包装成工具，让 Gemini 在对话中按需调用。配置文件的位置和格式很关键，写错了就会报「MCP server failed to start」。

Gemini CLI 的 MCP 配置通常放在用户目录下的配置文件中。以 macOS 为例，路径是~/.gemini/settings.json。如果你用的是项目级配置，可以在项目根目录建.gemini/settings.json。下面是一个可复制的 JSON 片段，挂载一个本地文件系统 MCP 服务：

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects" ] } } }

注意几个点：command是启动 MCP 服务的可执行命令，args是参数数组。/Users/yourname/projects要换成你实际想暴露给 AI 的目录。别把整个根目录暴露出去，安全第一。

如果你要接入的是远程 MCP 服务，配置会多一个url字段：

{ "mcpServers": { "remote-tools": { "url": "https://your-mcp-server.example.com/sse", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

写完后保存，重启 Gemini CLI。在交互界面里输入/mcp或类似命令（不同版本命令可能略有差异），应该能看到已挂载的 MCP 服务列表。如果服务启动失败，CLI 会打印错误日志，通常是命令路径不对或依赖没装。

3.3 三件套：Base URL、Key、Model ID 的对应关系

如果你是通过兼容 OpenAI 协议的方式接入第三方模型服务，配置里需要明确三件套：Base URL、API Key、Model ID。以 TaoToken 为例，Base URL 是https://taotoken.net/api，Key 在控制台的 API Keys 页面生成，Model ID 则根据你选的模型填写。这三者必须匹配，否则会报 401 或 model not found。

在 Gemini CLI 里，如果你用的是原生 Gemini 模型，通常不需要手动填 Base URL，OAuth 或 GEMINI_API_KEY 就够了。但如果你要接入自定义模型端点，就需要在配置里显式指定。具体字段名参考官方文档，别凭感觉写。

4. 验证请求：从终端调用到 MCP 工具生效的完整链路

4.1 第一次对话验证

装好之后，在终端输入gemini启动。你会看到一个交互式提示符。先来个最简单的：

帮我列出当前目录下的所有文件，并说明每个文件的用途。

Gemini 会请求权限来执行ls或类似命令。你按提示允许后，它会读取目录内容并给出分析。这一步验证的是基础的文件操作和 shell 命令调用能力。

如果这一步就报错，比如「permission denied」或「command not found」，先检查你的终端权限和 PATH。macOS 下可能需要在「系统设置 → 隐私与安全性 → 完全磁盘访问权限」里给终端授权。

4.2 验证 MCP 工具调用

MCP 服务挂载成功后，你可以直接让 Gemini 使用它。比如你挂载了 filesystem MCP，可以问：

用 filesystem 工具读取 /Users/yourname/projects/demo/package.json，告诉我这个项目依赖了哪些包。

如果 MCP 生效，Gemini 会调用 filesystem 服务的 read 方法，返回文件内容并解析。如果没生效，它可能会尝试用 shell 命令cat来读，或者直接说「我没有这个工具」。这时候回去检查settings.json的路径和命令是否正确。

一个更直观的验证方式是看 CLI 的输出日志。Gemini CLI 在调用 MCP 工具时，通常会打印类似「Calling tool: filesystem.read」的信息。你看到这行，就说明 MCP 链路通了。

4.3 在 VS Code 里联动

VS Code 里搜索「Gemini CLI」扩展并安装。装完后，你可以在 VS Code 的终端里直接跑gemini，也可以利用扩展提供的快捷入口。实际开发中，我通常这样用：在终端里让 Gemini 生成代码或修改文件，然后在 VS Code 里审阅 diff，确认无误后保存。

比如让 Gemini 写一个贪吃蛇小游戏：

用 HTML、CSS、JavaScript 写一个贪吃蛇游戏，保存到 snake.html。

Gemini 会创建文件并写入代码。你在 VS Code 里打开snake.html，用 Live Server 预览。如果有 bug，直接在终端里描述现象，让它改。这个「终端下指令 → 文件被修改 → 编辑器里验收」的循环，就是 Vibe Coding 的核心节奏。

5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth

5.1 401 Unauthorized

这个错误通常出现在你用 API Key 接入自定义端点时。原因无非三个：Key 写错了、Key 过期了、Base URL 和 Key 不匹配。排查步骤：先在终端里用 curl 直接测一下你的 Key 和端点：

curl -H "Authorization: Bearer YOUR_KEY" https://taotoken.net/api/v1/models

如果返回 401，说明 Key 或端点有问题。如果返回模型列表，说明 Key 没问题，那就要检查 Gemini CLI 配置里的字段名是否写对。有些工具要求字段叫apiKey，有些叫api_key，大小写敏感。

5.2 local proxy failed

这个报错通常和网络环境有关。Gemini CLI 需要访问 Google 的服务，如果你的网络环境有代理设置，可能会导致连接失败。排查方向：检查终端里的http_proxy、https_proxy环境变量是否指向了一个不可用的地址。用env | grep -i proxy看一下。如果有，临时 unset 掉再试：

unset http_proxy unset https_proxy

然后重新启动 Gemini CLI。如果问题依旧，检查你的 DNS 解析是否正常，nslookup google.com看看能不能解析。

5.3 reading choices 相关报错

这个错误一般出现在 Gemini CLI 尝试解析模型返回的多个候选结果时。可能原因是模型返回格式和 CLI 预期的不一致，或者网络中断导致响应不完整。解决办法：先确认你的 CLI 是最新版本，npm update -g @google/gemini-cli。如果是最新版还报错，尝试换一个模型或降低请求复杂度。有时候是临时性的服务波动，等几分钟重试即可。

5.4 OAuth 登录失败

OAuth 流程需要浏览器跳转。如果你在无头环境或 SSH 终端里跑，浏览器打不开，就会卡住。解决办法：在本地有图形界面的终端里先完成一次 OAuth 登录，凭证会缓存到本地。之后在 SSH 环境里就能复用。如果缓存失效，可以手动删除~/.gemini/下的凭证文件，重新登录。

另外，OAuth 登录时如果提示「access blocked」，检查你的 Google 账户是否开启了双重验证，或者是否在受限制的组织策略下。个人 Gmail 账户一般没问题。

5.5 MCP 服务启动失败

报错信息通常是「MCP server failed to start」或「spawn npx ENOENT」。前者说明命令执行了但服务没起来，后者说明npx这个命令找不到。排查：在终端里手动执行你配置里的command和args，看能不能跑起来。比如：

npx -y @modelcontextprotocol/server-filesystem /Users/yourname/projects

如果这条命令报错，说明 MCP 服务本身有问题，和 Gemini CLI 无关。如果这条命令正常，但 Gemini CLI 里报错，那可能是配置文件路径不对，或者 JSON 格式有语法错误。用cat ~/.gemini/settings.json | python -m json.tool验证 JSON 合法性。

6. 把这条链路用起来：从模型对话到长期编码的接入选择

环境跑通之后，你面临的选择是怎么把这套工作流用得更顺手。如果你只是偶尔问几个问题、验证一下模型能力，直接用 Gemini CLI 的交互模式就够了，OAuth 登录后免费额度基本用不完。如果你想在编辑器里更深度地集成，VS Code 扩展加上终端里的 Gemini CLI 组合，已经能覆盖大部分日常编码场景。

但如果你要做的是长期项目、需要 Agent 式的自动化编码，或者团队协作，那就需要考虑更稳定的接入方式。这时候可以走 API Key 模式，把 Base URL、Key、Model ID 三件套配好，避免 OAuth 凭证过期带来的中断。TaoToken 的控制台里可以生成和管理 API Keys，接入文档里有各语言的调用示例，模型对话页面则适合快速验证某个模型的表现。

具体路径我建议这样分：排障和接入问题，先看接入文档和 API Keys 页面；想快速验证模型输出质量，用模型对话；如果是长期编码或 Agent 场景，考虑 Coding Plan 这类更稳定的方案。别一上来就追求全自动，先把「终端下指令 → AI 改文件 → 编辑器验收」这个最小闭环跑顺，再逐步加 MCP 工具、加自动化脚本。

最后说个实际经验：MCP 工具别一次挂太多。每挂一个服务，CLI 启动时就多一个进程，调试复杂度也上升。我自己的做法是，项目初期只挂 filesystem 和 shell 两个最基础的，等确实需要数据库查询或第三方 API 时再加。这样出问题时排查范围小，也更容易定位是哪个环节断了。