Gemini-cli安装避坑指南

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 项目来进行配额和计费管理。

解决方案:

  1. 获取您的 Project ID:

    • 访问 Google Cloud Console
    • 在顶部导航栏的项目选择器中,选择您要用于 Gemini-CLI 的项目。
    • 在项目仪表盘 (Dashboard) 的 "Project info" 卡片中,找到并复制您的 Project ID
  2. 设置环境变量:

    • 在您的终端中,执行以下命令来设置环境变量。请将 your-project-id 替换为您真实的 Project ID。
    bash 复制代码
    export GOOGLE_CLOUD_PROJECT=your-project-id
    • 提示: 为了让这个配置永久生效,建议将此命令添加到您的 shell 配置文件中(如 ~/.zshrc, ~/.bashrc~/.profile),然后执行 source ~/.zshrc (或相应文件) 使其立即生效。

4.2 鉴权超时 (Auth Timeout)

问题描述:

执行 gemini auth 后,终端长时间没有响应,或者在尝试连接到 Google 认证服务时最终显示超时错误。这通常是由于本地网络环境无法直接或稳定地访问 Google 的服务器。

解决方案:

您需要为终端设置 HTTP/HTTPS 代理来解决此问题。

  1. 获取您的代理地址和端口:

    • 确保您有一个可以正常工作的本地或远程代理服务。
    • 获取其 IP 地址(或域名)和端口号。常见的本地代理端口有 7890, 1080, 8889 等。
  2. 方案一:设置终端环境变量

    • 在终端中执行以下命令。请将 your-proxy-addressport 替换为您的实际代理信息。
    bash 复制代码
    export http_proxy=http://your-proxy-address:port
    export https_proxy=http://your-proxy-address:port
    • 示例 (如果您的代理在本地,端口为 7890):

      bash 复制代码
      export http_proxy=http://127.0.0.1:7890
      export https_proxy=http://127.0.0.1:7890
  3. 方案二:修改 CLI 源码

    • 如果您通过 nvm 管理 Node.js 版本,可以找到 Gemini-CLI 的安装目录并直接修改其启动文件来硬编码代理。

    • 示例路径 (您的版本和路径可能不同): ~/.nvm/versions/node/v20.18.1/lib/node_modules/@google/gemini-cli/dist/index.js

    • 修改内容: 在文件顶部添加以下代码来设置代理。

    javascript 复制代码
    import './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);
    });
  4. 重新鉴权:

    • 设置好代理后,再次运行 gemini 命令,此时它应该能通过代理成功连接到 Google 服务。

    • 提示:GOOGLE_CLOUD_PROJECT 类似,您也可以将 http_proxyhttps_proxyexport 命令添加到 shell 配置文件中,以便在需要时使用。在不需要代理时,可以使用 unset http_proxy https_proxy 命令来取消设置。

5. 总结

完成以上步骤后,您的 Gemini-CLI 应该已经配置完毕,可以正常使用了。如果在操作中遇到其他问题,建议查阅官方文档或使用 --help 参数查看命令帮助。

相关推荐
墨风如雪3 小时前
三十亿参数的小宇宙:Ovis-U1-3B,AI界的新晋“全能选手”!
aigc
精灵vector6 小时前
构建专家级SQL Agent交互
python·aigc·ai编程
星始流年9 小时前
前端视角下认识AI Agent
前端·agent·ai编程
程序员鱼皮9 小时前
用 AI 制作超长视频,保姆级教程!
google·程序员·aigc
PetterHillWater10 小时前
Trae中实现OOP原则工程重构
后端·aigc
程序员X小鹿11 小时前
字节扣子空间的这个新功能,又原地封神了!打工人从此告别通宵!(附实测体验)
aigc·agent
slowlybutsurely11 小时前
Cursor快速入门
java·ai编程·cursor
奕川11 小时前
Spring AI 实战指南:模型集成与调优
后端·aigc
程序员陆通13 小时前
Vibe Coding开发微信小程序实战案例
微信小程序·小程序·notepad++·ai编程