Gemini-CLI 安装与使用教程
本文由Gemini-CLI生成,分享在鉴权过程中可能遇到的常见问题。
1. 安装
您可以使用 npm
(或 yarn
, pnpm
) 全局安装 Gemini-CLI:
bash
npm install -g @google/gemini-cli
安装完成后,您可以通过以下命令验证安装是否成功:
bash
gemini --version
2. 基础使用
安装并完成鉴权后,您可以开始使用 Gemini-CLI。一个简单的测试是:
bash
gemini hi
3. 鉴权 (gemini auth
)
在使用 Gemini-CLI 的大部分功能之前,您需要进行鉴权,将 CLI 工具与您的 Google 账号关联。
执行以下命令启动鉴权流程:
bash
gemini auth
该命令会生成一个 URL,请在浏览器中打开它,登录您的 Google 账号,并授权 Gemini-CLI 访问。成功后,将授权码复制回终端即可完成鉴权。
4. 鉴权常见问题与解决方案
在鉴权的过程中,您可能会遇到以下问题。
4.1 缺少 GOOGLE_CLOUD_PROJECT
环境变量
问题描述:
在登录成功后,终端可能会提示错误,指出 GOOGLE_CLOUD_PROJECT
环境变量未设置。这是因为 Gemini-CLI 需要关联一个 Google Cloud 项目来进行配额和计费管理。
解决方案:
-
获取您的 Project ID:
- 访问 Google Cloud Console。
- 在顶部导航栏的项目选择器中,选择您要用于 Gemini-CLI 的项目。
- 在项目仪表盘 (Dashboard) 的 "Project info" 卡片中,找到并复制您的 Project ID。
-
设置环境变量:
- 在您的终端中,执行以下命令来设置环境变量。请将
your-project-id
替换为您真实的 Project ID。
bashexport GOOGLE_CLOUD_PROJECT=your-project-id
- 提示: 为了让这个配置永久生效,建议将此命令添加到您的 shell 配置文件中(如
~/.zshrc
,~/.bashrc
或~/.profile
),然后执行source ~/.zshrc
(或相应文件) 使其立即生效。
- 在您的终端中,执行以下命令来设置环境变量。请将
4.2 鉴权超时 (Auth Timeout)
问题描述:
执行 gemini auth
后,终端长时间没有响应,或者在尝试连接到 Google 认证服务时最终显示超时错误。这通常是由于本地网络环境无法直接或稳定地访问 Google 的服务器。
解决方案:
您需要为终端设置 HTTP/HTTPS 代理来解决此问题。
-
获取您的代理地址和端口:
- 确保您有一个可以正常工作的本地或远程代理服务。
- 获取其 IP 地址(或域名)和端口号。常见的本地代理端口有
7890
,1080
,8889
等。
-
方案一:设置终端环境变量
- 在终端中执行以下命令。请将
your-proxy-address
和port
替换为您的实际代理信息。
bashexport http_proxy=http://your-proxy-address:port export https_proxy=http://your-proxy-address:port
-
示例 (如果您的代理在本地,端口为 7890):
bashexport http_proxy=http://127.0.0.1:7890 export https_proxy=http://127.0.0.1:7890
- 在终端中执行以下命令。请将
-
方案二:修改 CLI 源码
-
如果您通过
nvm
管理 Node.js 版本,可以找到 Gemini-CLI 的安装目录并直接修改其启动文件来硬编码代理。 -
示例路径 (您的版本和路径可能不同):
~/.nvm/versions/node/v20.18.1/lib/node_modules/@google/gemini-cli/dist/index.js
-
修改内容: 在文件顶部添加以下代码来设置代理。
javascriptimport './src/gemini.js'; import { main } from './src/gemini.js'; // --- Start of proxy configuration --- process.env.HTTPS_PROXY = 'http://127.0.0.1:7890'; process.env.HTTP_PROXY = 'http://127.0.0.1:7890'; process.env.ALL_PROXY = 'socks5://127.0.0.1:7890'; // --- End of proxy configuration --- main().catch((error) => { console.error('An unexpected critical error occurred:'); if (error instanceof Error) { console.error(error.stack); } else { console.error(String(error)); } process.exit(1); });
-
-
重新鉴权:
-
设置好代理后,再次运行
gemini
命令,此时它应该能通过代理成功连接到 Google 服务。 -
提示: 与
GOOGLE_CLOUD_PROJECT
类似,您也可以将http_proxy
和https_proxy
的export
命令添加到 shell 配置文件中,以便在需要时使用。在不需要代理时,可以使用unset http_proxy https_proxy
命令来取消设置。
-
5. 总结
完成以上步骤后,您的 Gemini-CLI 应该已经配置完毕,可以正常使用了。如果在操作中遇到其他问题,建议查阅官方文档或使用 --help
参数查看命令帮助。