Skip to main content

gemini-cli

brew install gemini-cli
npm install -g @google/gemini-cli@latest

gemini
gemini -r # 恢复会话

# 支持修改 Provider
export GEMINI_API_KEY=""
export GOOGLE_GEMINI_BASE_URL=""
# 只能通过 ENV 配置主要模型，无法修改 Flash 模型，Flash 模型需要通过 settings.json 修改
export GEMINI_MODEL=""
gemini "Hello"

配置​

变量名默认值用途说明
GEMINI_API_KEYGemini API 的 API Key。可作为多种认证方法之一。请设置在你的 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）或 .env 文件中。需保密。
GEMINI_MODEL指定 Gemini 默认使用的模型，覆盖内置默认模型。
GOOGLE_API_KEY你的 Google Cloud API Key，用于 express 模式的 Vertex AI。需要相应权限。
GOOGLE_CLOUD_PROJECT你的 Google Cloud 项目 ID。用于 Code Assist 或 Vertex AI。Vertex AI 需此项并具有必要权限。在 Cloud Shell 环境中默认会被自动分配的项目覆盖。若需指定项目，需在 .env 中定义。
GOOGLE_APPLICATION_CREDENTIALS指向 Google Application Credentials JSON 文件的路径。
OTLP_GOOGLE_CLOUD_PROJECT用于 Google Cloud Telemetry 的项目 ID。
GEMINI_TELEMETRY_ENABLED是否启用 telemetry。设为 true/1 启用，其他值为关闭，覆盖 telemetry.enabled 配置。
GEMINI_TELEMETRY_TARGET设置 telemetry 目标（如 local 或 gcp），覆盖 telemetry.target 配置。
GEMINI_TELEMETRY_OTLP_ENDPOINT设置 telemetry 的 OTLP 端点地址，覆盖 telemetry.otlpEndpoint 配置。
GEMINI_TELEMETRY_OTLP_PROTOCOL设置 OTLP 协议（grpc 或 http），覆盖 telemetry.otlpProtocol 配置。
GEMINI_TELEMETRY_LOG_PROMPTS是否日志记录用户 prompt，true/1 启用，其他禁用，覆盖 telemetry.logPrompts 配置。
GEMINI_TELEMETRY_OUTFILEtelemetry target 为 local 时，写入 telemetry 的文件路径，覆盖 telemetry.outfile 配置。
GEMINI_TELEMETRY_USE_COLLECTOR启用/禁用外部 OTLP collector，true/1 启用，其他禁用，覆盖 telemetry.useCollector 配置。
GOOGLE_CLOUD_LOCATION你的 Google Cloud 项目地域，用于非 express 模式下的 Vertex AI。
GEMINI_CLI1Shell 检测 CLI 运行环境（1 表示由 CLI 启动）
GEMINI_CONFIG_DIR.gemini配置目录名。
GEMINI_SYSTEM_MD.gemini/system.md替换内置 system prompt 的 Markdown 文件路径。true/1 使用项目默认路径（./.gemini/system.md），填写其他字符串为自定义路径（支持相对/绝对路径和 ~），false/0 或未设置则用内置 prompt。
GEMINI_WRITE_SYSTEM_MD是否写入当前内置 system prompt 到文件。true/1 写入 ./.gemini/system.md，如填其他则作为目标路径。建议首次运行时设置以生成模板。
GEMINI_CLI_NO_RELAUNCH禁用自动重启。
GEMINI_CLI_SYSTEM_SETTINGS_PATH覆盖默认 settings.json 路径。
GEMINI_CLI_DISABLE_AUTOUPDATER禁用自动更新。
SANDBOX安全隔离与沙箱配置。除 settings.json 的 sandbox 外，也可通过此变量指定沙箱方式（支持 true, false, docker, podman 或自定义命令行字符串）。
GEMINI_SANDBOX作为 sandbox 配置的替代项，语法同 SANDBOX。
SEATBELT_PROFILE (仅 macOS)macOS 沙箱 seatbelt（sandbox-exec）profile。permissive-open（默认）允许写操作在项目等目录，strict 更严格，或提供自定义 profile（如项目目录下 .gemini/sandbox-macos-<profile>.sb）。
TERM_PROGRAM终端程序环境变量用于检测 IDE 类型等。
GOOGLE_GENAI_USE_VERTEXAI为启用 Vertex AI，需设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 或 GOOGLE_API_KEY。
DEBUG DEBUG_MODE启用详细调试日志，true/1 启用（用于底层库/cli）。此变量默认不会从项目 .env 加载，否则可能影响 gemini-cli，请用 .gemini/.env 指定。
NO_COLOR设任意值禁用 CLI 彩色输出。
CLI_TITLE自定义 CLI 窗口标题。
CODE_ASSIST_ENDPOINT指定代码辅助 server endpoint，适用于开发/测试等场景。

说明：

  • 支持多配置文件优先级（如 ~/.gemini/settings.json、.gemini/settings.json、/etc/gemini-cli/settings.json 等）
  • .env 文件中可用 shell 变量（如 "$MY_API_TOKEN"）进行变量展开

自定义模型​

  • 例如修改 gemini-3-pro-preview -> google/gemini-3-pro-preview
    • 用于第三方 Provider 场景
{
  "model": {
    "name": "google/gemini-3-pro-preview"
  },
  "modelConfigs": {
    "customAliases": {
      "gemini-2.5-pro": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      },
      "gemini-3-pro-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      },
      "gemini-2.5-flash": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "gemini-2.5-flash-lite": {
        "extends": "chat-base-2.5",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "gemini-3-flash-preview": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "gemini-2.5-flash-base": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "classifier": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview",
          "generateContentConfig": {
            "maxOutputTokens": 1024,
            "thinkingConfig": {
              "thinkingBudget": 512
            }
          }
        }
      },
      "prompt-completion": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview",
          "generateContentConfig": {
            "temperature": 0.3,
            "maxOutputTokens": 16000,
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "edit-corrector": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview",
          "generateContentConfig": {
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }
      },
      "summarizer-default": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "summarizer-shell": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-flash-preview",
          "generateContentConfig": {
            "maxOutputTokens": 2000
          }
        }
      },
      "web-search": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [{ "googleSearch": {} }]
          }
        }
      },
      "web-fetch": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {
          "generateContentConfig": {
            "tools": [{ "urlContext": {} }]
          }
        }
      },
      "web-fetch-fallback": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "loop-detection-double-check": {
        "extends": "base",
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      },
      "llm-edit-fixer": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "next-speaker-checker": {
        "extends": "gemini-2.5-flash-base",
        "modelConfig": {}
      },
      "chat-compression-3-pro": {
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      },
      "chat-compression-3-flash": {
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "chat-compression-2.5-pro": {
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      },
      "chat-compression-2.5-flash": {
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "chat-compression-2.5-flash-lite": {
        "modelConfig": {
          "model": "google/gemini-3-flash-preview"
        }
      },
      "chat-compression-default": {
        "modelConfig": {
          "model": "google/gemini-3-pro-preview"
        }
      }
    }
  }
}

commands​

commandfornotes
/about显示版本信息
/auth更换认证方式
/bug提交 Gemini CLI 问题/bug <标题>
/chat保存/恢复会话历史save <tag>
resume <tag>
list
/clear清屏，清除可见历史Ctrl+L
/compress用摘要替换全部上下文
/copy复制上次输出到剪贴板
/corgi切换 Corgi 模式（AI 角色）
/editor选择支持的编辑器
/extensions列出当前会话扩展
/help /？显示帮助信息
/ide/ide status, /ide install
/mcp管理 MCP 服务器和工具desc/descriptions
nodesc/nodescriptions
schema
/memory管理 AI 指令上下文add <内容>
show
refresh
/privacy显示隐私声明及同意设置
/quit /exit退出 CLI
/restore恢复文件到工具执行前状态/restore [tool_call_id]
/stats显示会话统计信息
/theme更换 CLI 主题
/tools列出可用工具desc/descriptions
nodesc/nodescriptions
!<shell命令>执行 shell 命令!ls -la
!git status
!切换 shell 模式
@<路径>注入指定文件/目录内容到 prompt@README.md
@src/
@单独 @ 传递原始查询

⚠️ Shell 模式下命令拥有与终端同等权限，请谨慎操作。

settings.json​

{
  "contextFileName": "GEMINI.md",
  "bugCommand": {
    "urlTemplate": "https://bug.example.com/new?title={title}&info={info}"
  },
  "fileFiltering": {
    "respectGitIgnore": true,
    "enableRecursiveFileSearch": false
  },
  // https://github.com/google-gemini/gemini-cli/blob/main/docs/core/tools-api.md#built-in-tools
  "coreTools": [],
  "excludeTools": [],
  "allowMCPServers": [],
  "excludeMCPServers": [],
  "autoAccept": false,
  "sandbox": false, // docker
  "toolDiscoveryCommand": "",
  "toolCallCommand": "",
  "mcpServers": {
    "myPythonServer": {
      "command": "python",
      "args": ["mcp_server.py", "--port", "8080"],
      "cwd": "./mcp_tools/python",
      "timeout": 5000
    }
  },
  "checkpointing": { "enabled": false },
  "preferredEditor": "vscode",
  "telemetry": {
    "enabled": false,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "usageStatisticsEnabled": false,
  "hideTips": false,
  "hideBanner": false,
  "summarizeToolOutput": {
    "run_shell_command": {
      "tokenBudget": 2000
    }
  },
  "maxSessionTurns": -1,
  "theme": "Atom One",
  "selectedAuthType": "oauth-personal"
}
toolfor
FS文件系统工具
LSTool列出目录内容
ReadFileTool读取单个文件内容
WriteFileTool写入内容到文件
GrepTool在文件中搜索模式
GlobTool查找匹配 glob 模式的文件
EditTool对文件进行原地修改
ReadManyFilesTool读取并拼接多个文件或 glob 内容
Execution执行工具
ShellTool执行 shell 命令
WebWeb 工具
WebFetchTool获取指定 URL 内容
WebSearchTool执行网页搜索
Memory内存工具
MemoryTool与 AI 的记忆交互
envfor
GEMINI_MODELgemini-2.5-pro
GEMINI_FLASH_MODELgemini-2.5-flash
GEMINI_EMBEDDING_MODELgemini-embedding-001
GOOGLE_GEMINI_BASE_URL
GEMINI_API_KEY

extensions​

gemini-extension.json
{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}
.gemini/extensions/gcp/
├── gemini-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

conductor​

  • https://github.com/gemini-cli-extensions/conductor
  • CDD - Context Driven Development - 上下文驱动开发
  • 不依赖聊天记录，而是将项目的上下文（Context）、技术栈（Tech Stack）、代码规范（Style Guide）等信息以 Markdown 文件的形式存储在代码仓库中。AI 会始终遵循这些文件，确保开发的一致性。
  • 相比于 SpecIt 或 OpenSpec 等类似工具，Conductor 与 Gemini CLI 集成更紧密
gemini extensions install https://github.com/gemini-cli-extensions/conductor

# CONTEXT.md
gemini /conductor:setup

# spec, plan
gemini /conductor:newTrack
/conductor setup
# tracks/
/conductor newTrack

/conductor implement
/conductor status
/conductor revert
  • .conductor/tracks/

GEMINI.md​

  • 现在支持 AGENTS.md
  • 使用 @file.md 可注入指定文件内容到 prompt