Gemini CLI

Gemini CLI 是 Google Gemini 的命令行工具，可以在终端中调用 Gemini 模型完成对话、代码辅助和内容生成任务。

本文说明如何将 Gemini CLI 接入词元 API。

准备工作

使用前请先确认：

• Node.js 版本为 20 或更高。
• npm 可用。
• 已在词元 API 控制台创建可用 API Key。
• API Key 所在分组包含 Gemini CLI 要使用的模型。

控制台入口：

https://code.ciyuanapi.xyz

令牌管理：

https://code.ciyuanapi.xyz/token

Gemini 兼容 Endpoint：

https://code.ciyuanapi.xyz/v1beta

如果 v1beta 端点不可用，可以改用 OpenAI 兼容客户端或 /v1/chat/completions 端点。

检查环境：

node -v
npm -v

安装 Gemini CLI

推荐使用 npm 全局安装：

npm install -g @google/gemini-cli

也可以临时运行：

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

不建议优先使用 Homebrew 版本。部分环境下 Homebrew 版本可能无法正确读取环境变量。

Windows 如果安装或运行时报权限错误，请用管理员身份打开 PowerShell 或 CMD 后重试。

配置词元 API

可以在 Gemini CLI 中手动认证：

/auth

选择 API Key 方式，填入词元 API Key。

如果认证流程要求填写 endpoint，请使用：

https://code.ciyuanapi.xyz/v1beta

如果你使用环境变量方式，请确认当前项目目录和上级目录没有 .env 覆盖 Gemini CLI 的配置。

启动与使用

Gemini CLI 通常需要显式指定模型：

gemini -m <model_name>

示例：

gemini -m gemini-3-pro-preview
gemini -m gemini-2.5-flash

模型名称可能会调整，请以词元 API 控制台中当前可用模型为准。

常见问题

API key not valid

常见原因是当前目录或上级目录存在 .env，覆盖了全局 Gemini 配置。

处理方式：

• 检查当前目录及上级目录是否存在 .env。
• 删除冲突配置，或将用户目录下 .gemini 配置复制到当前项目目录。
• 重新运行 /auth 并填写词元 API Key。

Model is not allowed

通常是模型名不正确，或者启动时没有加 -m。

处理方式：

gemini -m <词元 API 控制台中的模型名>

RESOURCE_EXHAUSTED

通常表示上游额度或请求频率达到限制。可以稍后重试，或切换到同分组内其他可用模型。

SyntaxError / unsupported engine

通常是 Node.js 版本低于 20。升级 Node.js 后重试。

推荐排查顺序

1. 检查 Node.js 版本是否为 20 或更高。
2. 重新安装：npm install -g @google/gemini-cli。
3. 删除旧的 .gemini 配置后重新运行 /auth。
4. 检查模型名是否来自词元 API 控制台。
5. 仍无法解决时，保留终端报错、系统信息和操作步骤，联系词元 API 支持。