VitePress

Appearance

入门指南安装和配置

Google Gemini CLI 安装和配置指南 ​

本指南将帮助你手动安装和配置 Google Gemini CLI。无论你是 macOS、Windows 还是 Linux 用户，只要配置好 Node.js 环境，即可轻松使用。

1. 环境准备：安装 Node.js ​

Gemini CLI 基于 Node.js 开发，因此你需要先确保系统中安装了 Node.js 环境。

版本要求： Node.js 版本需 v18.0.0 或更高。

检查现有环境 ​

打开终端（Terminal 或 PowerShell），输入以下命令检查是否已安装：

node --version

如果显示版本号且高于 v18，可直接跳到下一步。

安装 Node.js ​

如果未安装，请根据你的操作系统选择安装方式：

macOSWindowsLinux

推荐使用 Homebrew 安装：

brew install node

或者访问 Node.js 官网 下载 macOS 安装包 (.pkg)。

推荐使用官网安装包：

  1. 访问 Node.js 官网
  2. 下载 LTS 版本 的 Windows 安装包 (.msi)
  3. 运行安装程序并按提示完成安装

Ubuntu/Debian 系统：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

2. 安装 Gemini CLI ​

环境准备好后，使用 npm 包管理器进行全局安装。

在终端中执行以下命令：

npm install -g @google/gemini-cli

⚠️

macOS/Linux 用户注意：
如果遇到权限错误（EACCES），请在命令前加上 sudo：

sudo npm install -g @google/gemini-cli

3. 配置环境变量 ​

opcx.ai AI API 系统支持通过 GEMINI_API_KEY 方式访问 Google Gemini CLI。请按照以下步骤配置环境变量。

配置方式：使用 Gemini API Key (推荐) ​

macOS / LinuxWindows (PowerShell)Windows (CMD)

临时生效（当前窗口）：

export GOOGLE_GEMINI_BASE_URL="https://opcx.ai/gemini"
export GEMINI_API_KEY="替换你的api key"
export GEMINI_MODEL="gemini-2.5-flash"

永久生效（推荐）：

对于 zsh（macOS 默认）：

echo 'export GOOGLE_GEMINI_BASE_URL="https://opcx.ai/gemini"' >> ~/.zshrc
echo 'export GEMINI_API_KEY="替换你的api key"' >> ~/.zshrc
echo 'export GEMINI_MODEL="gemini-2.5-flash"' >> ~/.zshrc
source ~/.zshrc

对于 bash：

echo 'export GOOGLE_GEMINI_BASE_URL="https://opcx.ai/gemini"' >> ~/.bashrc
echo 'export GEMINI_API_KEY="替换你的api key"' >> ~/.bashrc
echo 'export GEMINI_MODEL="gemini-2.5-flash"' >> ~/.bashrc
source ~/.bashrc

注意： 设置后，你可能需要重新打开终端窗口，或者手动执行 source ~/.zshrc (zsh) / source ~/.bashrc (bash) 使配置生效。

当前会话生效：

$env:GOOGLE_GEMINI_BASE_URL="https://opcx.ai/gemini"
$env:GEMINI_API_KEY="替换你的api key"
$env:GEMINI_MODEL="gemini-2.5-flash"

永久生效：

[System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://opcx.ai/gemini', 'User')
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '替换你的api key', 'User')
[System.Environment]::SetEnvironmentVariable('GEMINI_MODEL', 'gemini-2.5-flash', 'User')

设置后需要重启 PowerShell 窗口。

永久生效：

setx GOOGLE_GEMINI_BASE_URL "https://opcx.ai/gemini"
setx GEMINI_API_KEY "替换你的api key"
setx GEMINI_MODEL "gemini-2.5-flash"

设置后需要重启 CMD 窗口。

清除旧版 Token 认证配置 ​

如果你之前使用过旧版的 Token 认证方式（CODE_ASSIST_ENDPOINT + GOOGLE_CLOUD_ACCESS_TOKEN），需要先清除这些配置，否则会与新配置冲突。

macOS / LinuxWindows (PowerShell)Windows (CMD)

取消当前会话的配置：

unset CODE_ASSIST_ENDPOINT GOOGLE_CLOUD_ACCESS_TOKEN GOOGLE_GENAI_USE_GCA

取消永久配置：

请编辑 ~/.zshrc 或 ~/.bashrc，删除包含这些变量的行，然后重新加载：

source ~/.zshrc  # 或 source ~/.bashrc

取消当前会话的配置：

Remove-Item Env:CODE_ASSIST_ENDPOINT -ErrorAction SilentlyContinue
Remove-Item Env:GOOGLE_CLOUD_ACCESS_TOKEN -ErrorAction SilentlyContinue
Remove-Item Env:GOOGLE_GENAI_USE_GCA -ErrorAction SilentlyContinue

取消永久配置：

[System.Environment]::SetEnvironmentVariable('CODE_ASSIST_ENDPOINT', $null, 'User')
[System.Environment]::SetEnvironmentVariable('GOOGLE_CLOUD_ACCESS_TOKEN', $null, 'User')
[System.Environment]::SetEnvironmentVariable('GOOGLE_GENAI_USE_GCA', $null, 'User')

设置后需要重启 PowerShell 窗口。

取消永久配置：

请在系统环境变量设置中手动删除 CODE_ASSIST_ENDPOINT、GOOGLE_CLOUD_ACCESS_TOKEN、GOOGLE_GENAI_USE_GCA 这三个变量，然后重启 CMD 窗口。

检查环境变量设置 ​

配置完成后，可执行以下命令验证变量是否正确设置：

Bash/Zsh： ​

echo $GOOGLE_GEMINI_BASE_URL $GEMINI_API_KEY $GEMINI_MODEL

Windows PowerShell： ​

Write-Host $env:GOOGLE_GEMINI_BASE_URL $env:GEMINI_API_KEY $env:GEMINI_MODEL

4. 验证安装 ​

配置完成后，让我们验证一下 Gemini CLI 是否安装成功并能正常运行。

检查版本 ​

在终端输入：

gemini --version

如果输出了版本号（例如 1.0.0），说明工具已安装。

首次运行 ​

输入 gemini 启动工具：

gemini

如果是首次运行，你可能会看到欢迎信息或被要求进行简单的初始化设置。
如果提示认证，请选择 2. Use Gemini API Key，工具将自动使用 GEMINI_API_KEY 和 GOOGLE_GEMINI_BASE_URL 连接至我们的服务。

🎉 恭喜！
你已经成功安装并配置了 Google Gemini CLI。现在可以开始体验 AI 辅助编码的强大功能了。

要启用 Gemini 3 Pro，请在 Gemini CLI 中使用 /settings 命令并将预览功能设置为 true。
更多信息，请参阅 Gemini CLI 设置

常见问题 ​

Q: 运行 gemini 提示 “command not found”？
A: 请检查 Node.js 的全局 bin 目录是否在系统的 PATH 环境变量中。重新安装 Node.js 通常能解决此问题。

Q: 提示 API Key 无效？
A: 请检查环境变量是否配置正确。在终端输入 echo $GEMINI_API_KEY (macOS/Linux) 或 $env:GEMINI_API_KEY (Windows) 查看当前值。

Q: 如何在 Gemini CLI 中粘贴截图？ A: 在 Gemini CLI 聊天界面中，macOS 用户可以使用 Control + V 直接粘贴截图，Windows 用户可以使用 Alt + V 粘贴截图。

核心介绍快速体验