外观

Gemini CLI 接入 ​

5 分钟配置 Gemini 命令行工具，避开常见认证陷阱。通过 MoaCode 中转使用 Gemini CLI，支持 macOS / Linux / Windows。

一、环境准备 ​

Gemini CLI 依赖 Node.js，版本必须 ≥ 20：

bash
node -v
显示结果判断下一步
v20.x.x 或更高✅ 通过直接安装 Gemini CLI
v18.x.x 或更低❌ 未通过前往 nodejs.org 升级
命令不存在❌ 未通过前往 nodejs.org 下载

二、安装 Gemini CLI ​

方式 1：npm 全局安装（推荐）

bash
npm install -g @google/gemini-cli

稳定性高、配置读取正确、全局可用，易于更新卸载。

方式 2：npx 临时运行（只想测试一次时用，每次启动都要重新下载）

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

不要用 Homebrew 安装

经测试 Homebrew 版本存在环境变量读取问题（无法正确读取全局环境变量、配置文件路径识别错误），官方尚未修复，请勿使用 brew install gemini-cli。

验证安装：

bash
gemini --version

三、一键配置 MoaCode 接入 ​

MoaCode 提供一键配置脚本，自动创建 ~/.gemini 配置目录、写入 API 密钥与端点、设置模型映射。

获取脚本：

  • 个人用户：Dashboard → Quick setup → 选择 Gemini CLI
  • 团队用户：Team 页 → API 密钥 → 选择工具下拉框选 Gemini CLI

按系统复制对应命令（macOS/Linux 复制 Unix 命令到终端；Windows 复制 PowerShell 命令）粘贴执行即可。

Windows 用户必读：PowerShell 版本与 BOM 问题 ​

先看你的 PowerShell 版本：

powershell
$PSVersionTable.PSVersion
主版本号怎么做
7 及以上直接原样跑安装命令，没有 BOM 问题
5推荐升级到 PowerShell 7（下方方案 A）；或留在 5.1 打补丁（方案 B）

问题根源：Windows PowerShell 5.1 默认的 UTF-8 编码带 BOM（文件开头 3 个不可见字节 EF BB BF），会导致生成的配置文件出问题：

  • settings.json 带 BOM → CLI 直接报错 Unexpected token '' ... is not valid JSON
  • .env 带 BOM → 不报错但静默失效：第一行变量名被解析成 GOOGLE_GEMINI_BASE_URL，中转地址不生效，CLI 拿着中转 Key 去连 Google 官方端点然后鉴权失败——很容易误判成"key 不对"

方案 A：升级到 PowerShell 7（推荐） ​

powershell
# 1. 安装 PowerShell 7（一次性，5.1 仍保留，互不影响）
winget install --id Microsoft.PowerShell --source winget

# 2. 切到 pwsh
pwsh

# 3. 原样运行 Dashboard 复制的安装命令

建议把 Windows Terminal 的默认配置文件切到 pwsh，避免下次又用 5.1 重新踩坑。

方案 B：留在 5.1，装完打补丁 ​

把安装命令和 BOM 修复合并成一条执行（$base / $url / $key 按 Dashboard 复制的实际值填写）：

powershell
& {
    $base = 'https://moacode.org'
    $url  = 'https://moacode.org/gemini'
    $key  = '你的_cr_开头的key'

    # 1. 跑官方安装脚本
    iwr -useb $base/setup_gemini.ps1 | iex

    # 2. 立刻剥掉 BOM（settings.json 和 .env 都要处理）
    foreach ($f in @('settings.json', '.env')) {
        $p = Join-Path $env:USERPROFILE ".gemini\$f"
        if (Test-Path $p) {
            $t = [IO.File]::ReadAllText($p).TrimStart([char]0xFEFF)
            [IO.File]::WriteAllText($p, $t, (New-Object Text.UTF8Encoding $false))
            Write-Host "[FIXED] $p" -ForegroundColor Green
        }
    }
}

两个文件必须一起修

只修 settings.json 会漏掉 .env——后者带 BOM 不报错但静默失效，更难查。且每次重跑安装脚本 BOM 都会回来，补丁要跟着重跑。

验证是否有 BOM：

powershell
Format-Hex "$env:USERPROFILE\.gemini\settings.json" | Select-Object -First 1

输出开头是 EF BB BF 就是有 BOM；是 7B（即 {）就是干净的。.env 同理，干净的开头应为 47 4F 4F 47 4C（GOOGL）。

四、配置文件说明 ​

安装脚本在 ~/.gemini/（Windows：%USERPROFILE%\.gemini\）下生成两个文件：

.env — 凭据和端点：

env
GOOGLE_GEMINI_BASE_URL="https://moacode.org/gemini"
GEMINI_API_KEY="cr_xxxxxxxxxxxxxxxxxxxxxxxx"
变量作用
GOOGLE_GEMINI_BASE_URL中转地址，替换 Google 官方端点
GEMINI_API_KEYMoaCode 的 Key（cr_ 开头，不是 Google 官方 key）

settings.json — CLI 行为：

json
{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "general": {
    "previewFeatures": true
  }
}
字段作用
security.auth.selectedType用 API key 鉴权，跳过 Google 账号 OAuth 登录
general.previewFeatures开启预览功能。使用 gemini-3-pro-preview 这类 preview 模型必须为 true

安装脚本每次运行会自动备份旧配置（形如 settings.json.backup.20260831_095632），确认新配置可用后可清理。

五、启动与验证 ​

必须用 -m 指定模型

MoaCode 使用了特定的模型映射，直接运行 gemini 会报 Model is not allowed。启动时必须加 -m 参数。

bash
# ❌ 错误
gemini

# ✅ 正确
gemini -m gemini-3-pro-preview

验证三步（第 2 条最有诊断价值——配置错误、鉴权失败、模型名不对都会直接打在标准输出上）：

bash
# 1. CLI 本身能跑
gemini --version

# 2. 非交互模式发一次真实请求（报错不会被 TUI 吞掉）
gemini -p "hi" -m gemini-3-pro-preview

# 3. 进交互模式
gemini -m gemini-3-pro-preview

正常启动后 .gemini/ 下会新生成 history/ 目录和 projects.json，可作为初始化成功的旁证。

常用模型速查（完整清单见站内 Model catalog）：

模型名称适用场景成本
gemini-3-pro-preview复杂推理、代码生成、长上下文较高
gemini-3-pro-high高性能任务中等
gemini-2.5-flash快速响应、日常问答较低

六、常见错误排查 ​

错误 1：API key not valid（最常见） ​

json
{ "code": 400, "message": "API key not valid. Please pass a valid API key." }

根本原因（.env 文件陷阱）：Gemini CLI 会自动检测当前目录及上级目录的 .env 文件并强制优先使用，覆盖全局配置。

bash
# 1. 检查当前/上级目录是否有干扰的 .env
ls -la | grep .env
ls -la ../ | grep .env

# 2a. 方案 A（推荐）：删除干扰的 .env 后重启
rm .env

# 2b. 方案 B（需保留 .env 时）：把正确配置复制到当前目录
cp -r ~/.gemini ./

Windows 用户另需排查 BOM 问题（见第三节）。

错误 2：Model is not allowed ​

原因解决
忘记加 -m 参数加上 -m gemini-3-pro-preview
用了官方模型名（如 gemini-pro）换成 MoaCode 映射名（下表）
模型名拼写错误对照 Model catalog 核对
官方模型名MoaCode 映射名
gemini-progemini-3-pro-preview
gemini-flashgemini-2.5-flash

错误 3：RESOURCE_EXHAUSTED ​

json
{ "code": 400, "status": "RESOURCE_EXHAUSTED" }

Google 官方调用额度达到上限（官方速率限制，非 MoaCode 问题）。处理：等 1–5 分钟重试；或在接口管理开启自动渠道切换；或升级订阅套餐。

错误 4：SyntaxError / unsupported engine ​

Node.js 版本低于 20。升级：

bash
nvm install --lts && nvm use --lts
node -v   # 应显示 v20+

错误 5：命令瞬间返回，一个字都没有 ​

Gemini CLI 是 TUI 程序，初始化崩溃时报错会随屏幕缓冲区一起被擦掉。排查：

bash
# 非交互模式绕开 TUI，错误不会被吞
gemini -p "hi" -m gemini-3-pro-preview

# 看退出码（0 = 正常，非 0 = 崩溃）
echo $LASTEXITCODE   # PowerShell；bash 用 echo $?

常见诱因：.env 带 BOM（Windows）、Node 版本过低、previewFeatures 未开启。

错误 6：Request cancelled / This request failed ​

CLI 默认折叠了错误详情，先打开：

  • /settings → 把 Error Verbosity 调到最高
  • F12 → 打开 diagnostics 面板看实际状态码

429 = 排队限流（与配置无关）；401/403 = 鉴权问题，回查 .env；404 = 中转未代理该端点。

七、终极排查流程（3 步） ​

  1. 先看服务状态：moacode.org/provider-status——🔴 服务异常时等待修复即可，不要继续排查自己的配置
  2. 彻底重置环境：
bash
rm -rf ~/.gemini
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli
# 重新运行一键配置脚本，然后测试：
gemini -p "hi" -m gemini-2.5-flash
powershell
Remove-Item -Recurse -Force $env:USERPROFILE\.gemini
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli
# 重新运行一键配置脚本（注意 BOM，见第三节），然后测试
  1. 仍未解决则提交工单，附上三样信息：终端报错截图（含完整命令）、F12 diagnostics 面板的红色报错截图（Ctrl+S 激活交互后滚动查找）、文字描述（系统 / 工作目录 / 操作过程 / 已做过哪些排查）

相关页面 ​

MoaCode — One key. Every coding agent.

© 2026 MoaCode