Gemini CLI 配置指南与常用命令中文翻译 | API Key、MCP、代理设置

Gemini CLI 配置指南与常用命令

本指南详细介绍了如何配置Gemini CLI的API Key、API URL、网络代理，并提供了常用命令的中文翻译，帮助您快速上手和定制化使用Gemini CLI工具。

1. 配置 API Key

• 方法一：环境变量 (Shell Environment Variable)

  这是最推荐和最安全的方式。将API Key设置为一个环境变量，CLI会自动读取。

  • 在macOS/Linux的Bash或Zsh终端中，执行以下命令：

    export GEMINI_MODEL="gemini-2.5-flash"
    export GOOGLE_GEMINI_BASE_URL="https://gemini-balance.XXX.xyz"
    export GEMINI_API_KEY="sk-"
    

  • 为了让此配置在每次启动新终端时都生效，可以将此行添加到你的shell配置文件中，例如 ~/.bashrc, ~/.zshrc 或 ~/.bash_profile。

• 方法二：配置文件 (.env file)

  你可以在项目或全局范围内创建一个.env文件来存储API Key。

  • 全局配置：在 ~ 目录下创建 .env 文件，并添加如下内容：

    GEMINI_API_KEY="YOUR_API_KEY"
    
    OPENROUTER_BASE_URL="XXX"
    OPENROUTER_API_KEY="your_bigmodel_api_key"
    

  • 项目配置：在项目根目录创建一个 .gemini/.env 文件。

• 方法三：显式传递 (–api-key flag)

  在命令行中直接通过参数传递API Key。

  gemini --api-key "YOUR_API_KEY" -p "Write me a haiku about a cat."
  
  

2. Model Context Protocol (MCP) 配置

Gemini CLI通过Model Context Protocol (MCP) 扩展其功能。配置MCP允许你使用自定义的API URL，通常用于代理或使用非官方的API端点。

• 主要配置方式：settings.json 文件

  这是配置MCP服务器的主要方式。Gemini CLI的配置文件位于 ~/.gemini/settings.json（用户级别）或 .gemini/settings.json（项目级别）。

  • 打开 ~/.gemini/settings.json。

  • 在文件中添加或修改mcpServers配置块，如下所示：

    {
      "mcpServers": {
        "my-custom-server": {
          "api_url": "YOUR_CUSTOM_API_URL",
          "api_key": "YOUR_API_KEY_FOR_CUSTOM_SERVER",
          "description": "Custom API server for Gemini CLI"
        }
      }
    }
    
    

    • "my-custom-server": 你自定义的服务器名称。
    • "api_url": 你的自定义API端点URL。
    • "api_key": 该自定义服务器所需的API Key。
    • "description": 对该服务器的描述。

3. 配置网络代理 (Configure Network Proxy)

Gemini CLI支持标准的HTTP/HTTPS代理配置，通常通过环境变量实现。

• 使用环境变量

  CLI 可以自动识别并使用以下环境变量来配置网络代理：

  • http_proxy / HTTP_PROXY: 用于HTTP请求。
  • https_proxy / HTTPS_PROXY: 用于HTTPS请求。
  • no_proxy / NO_PROXY: 指定不需要通过代理访问的主机或域名列表。

  例如，在Linux/macOS上，你可以这样设置：

  export HTTPS_PROXY="http://proxy.example.com:8080"
  export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
  
  

• 使用 –use-env-proxy 标志

  在某些情况下，你可能需要显式地使用 –use-env-proxy 标志来启用环境变量代理设置，但通常情况下CLI会默认识别。

  gemini --use-env-proxy -p "What's the weather like in New York?"
  
  

4. 常用命令与选项中文翻译 (Common Commands & Options)

英文命令/选项 (English Command/Option)	中文翻译 (Chinese Translation)	功能描述 (Description)
gemini	gemini	启动交互式会话。
gemini mcp	gemini mcp	管理MCP服务器。
-p, --prompt	-p, --提示词	在非交互模式下直接发送一个提示词。
-i, --prompt-interactive	-i, --交互式提示词	执行提供的提示词并继续进入交互模式。
-m, --model	-m, --模型	指定要使用的模型。
-s, --sandbox	-s, --沙盒	在沙盒环境中运行。
-d, --debug	-d, --调试	在调试模式下运行，显示更多详细信息。
-a, --all-files	-a, --所有文件	将工作区内的所有文件作为上下文。
-y, --yolo	-y, --自由模式	自动批准所有工具操作（即“自由模式”），禁用大部分安全限制。
--approval-mode	--批准模式	设置工具操作的批准模式（default, auto_edit, yolo）。
--show-memory-usage	--显示内存使用	在状态栏显示内存使用情况。
--proxy	--代理	为客户端指定代理，如 schema://user:password@host:port。
-v, --version	-v, --版本	显示当前CLI的版本号。
-h, --help	-h, --帮助	显示帮助信息。
/memory	/内存	显示当前会话的记忆（上下文）。
/stats	/统计	显示模型使用情况和统计数据。
/tools	/工具	列出所有可用的内置和自定义工具。
/mcp	/mcp	列出所有已配置的MCP服务器及其工具。
/auth	/认证	管理CLI的认证方式（API Key或OAuth）。

5. 配置优先级

Gemini CLI会按照以下优先级顺序加载配置：

1. 命令行参数 (Command-line arguments)
2. 项目级配置文件 (.gemini/settings.json)
3. 用户级配置文件 (~/.gemini/settings.json)
4. 系统级配置文件 (/etc/gemini-cli/settings.json)
5. 环境变量 (Environment variables)

优先级高的配置会覆盖优先级低的配置。

---

欢迎指出任何有错误或不够清晰的表达，可以在下面评论区评论。