Google 的开源 Gemini CLI——将 Gemini 带入你的 Shell 的基于终端的 AI 代理——自发布以来快速成熟，现在已支持丰富的配置、项目上下文文件（GEMINI.md / .gemini）、自定义斜杠命令，以及工作区目录控制。该项目在 GitHub（官方仓库）上持续活跃演进，已进入公开预览并提供宽松配额，同时正与其他开发者工具集成（编辑器集成与 CI/Actions）。但当团队扩张，或者你跨磁盘或受限环境（容器、公司管理的笔记本、Cloud Shell、Windows 系统）工作时，你会很快遇到一个实际问题：Gemini 会把它的文件存在哪里？以及如何更改 Gemini 读取和写入的目录？
什么是 Gemini CLI？
Gemini CLI 是 Google 的开源命令行 AI 代理，将 Gemini 模型的能力直接带到你的终端。它提供交互式代理能力，用于代码辅助、文件与项目检查、执行 Shell 命令（带有安全防护），并可集成 Google Search、Model Context Protocol（MCP）扩展，以及随 Gemini 提供的媒体生成工具。该 CLI 旨在轻量、可编排、可扩展；可从官方仓库获取，并已打包便于安装。
为什么目录很重要
Gemini CLI 会在 .gemini 目录中存储配置（例如 settings.json）、系统提示或上下文（GEMINI.md）、缓存的凭据、遥测标识以及其他持久化状态。该目录的位置决定了：
- CLI 加载哪些设置（全局 vs 项目级），
- 代理会读取哪些“记忆”文件，
- 凭据缓存位置（影响登录行为），
- 当你希望提供自定义配置仓库时的跨机器或 CI 可复现性。
理解并（如有需要）更改该目录，有助于多项目工作流、CI、容器化部署以及拥有集中配置存储的团队。
Gemini CLI 默认将配置存储在哪里？
默认情况下，CLI 使用 .gemini 目录。对大多数用户安装而言，这会解析为 ~/.gemini（即主目录中的 .gemini 文件夹）。CLI 也支持项目级 .gemini 文件（例如项目根目录中的 .gemini/settings.json），当你在该项目文件夹中操作时，它们会覆盖用户设置。系统级设置会在适用时从特定于操作系统的位置读取（例如 Linux 的 /etc/ 或 Windows 的 %PROGRAMDATA%）。常见路径：
- Linux / macOS:
~/.gemini/（例如/home/alice/.gemini或/Users/alice/.gemini）。 - Windows:
%USERPROFILE%\.gemini（例如C:\Users\Alice\.gemini）。
在.gemini中，你通常会发现settings.json、GEMINI.md、commands/以及本地缓存。CLI 也会读取项目根目录中的.gemini/文件夹（项目级设置）。
该默认很重要：历史上配置目录被硬编码为主目录中的 .gemini
我如何更改或重定向 Gemini CLI 的配置目录？
有多种实用方式——从最简单的（在目标文件夹中工作）到更健壮的（环境变量或文件系统重定向）。根据你是否控制运行环境（本地开发机器 vs CI）、所使用的操作系统，以及你偏好临时或永久更改来选择方法。
1) 使用项目级 .gemini（针对每个项目的设置，推荐）
如果你想要每个项目的设置，请在项目根目录创建一个 .gemini 子目录，并将 settings.json、GEMINI.md 以及其他项目文件放入其中。Gemini CLI 会在你从该项目目录运行时优先使用项目设置：
your-project/├─ .gemini/│ ├─ settings.json│ └─ GEMINI.md└─ src/
在你的 Shell 当前位于 your-project/ 时启动 gemini，CLI 会从该目录树中拾取 .gemini 文件（它会向上搜索以找到项目上下文）。这是进行项目级配置最安全、最明确的方法。
2) 使用已文档化的环境变量（在支持时）
Gemini CLI 的代码库与文档提到了用于改变行为的多个环境变量。其中一些用于系统设置或特殊文件覆盖：
GEMINI_API_KEY、GEMINI_MODEL等常用于认证和模型选择。- 代码库与文档中提到诸如
GEMINI_CLI_SYSTEM_SETTINGS_PATH（用于覆盖系统设置路径）以及像GEMINI_CONFIG_DIR这样的常量（代码中默认的.gemini名称）。一些社区请求与 PR 提议添加或遵循GEMINI_CONFIG_DIR环境变量，以允许用户迁移整个配置目录。
示例（bash / macOS / Linux）：
# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"# Then rungemini
PowerShell（Windows）：
$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini
重要警告：根据最新的社区讨论与问题反馈，
GEMINI_CONFIG_DIR在部分位置已被请求并在代码中引用——但已报告平台特定的 Bug 和不一致行为（尤其在 Windows 上）。这意味着基于环境变量的重定向在所有平台或发行版本上可能并不完全可靠。如果你依赖该方式，请针对已安装版本查看 Gemini CLI 的发行说明与仓库问题。
3) 在会话内将目录添加到 Gemini 的工作区
如果你希望 Gemini 感知其他目录（以便读取文件作为上下文），可以使用交互式的 /directory 命令集。例如：
/directory add path/to/another/project/directory list
这不会移动配置目录，但允许代理在其工作区上下文中包含其他目录的文件。当你希望代理引用其他仓库而不更改全局配置时，这很有用。
4) 创建符号链接或文件系统绑定（实用变通）
如果 CLI 不接受环境覆盖，或你需要跨进程的可靠方案，请使用文件系统重定向：
在 Unix/macOS 上：
# move the original config foldermv ~/.gemini ~/gemini_backup# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini
在 Windows（提升的 PowerShell 提示符）上：
# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig
该方法会强制 CLI 从你期望的位置读取，而无需 CLI 的原生支持。注意：符号链接/联接需要适当的文件系统权限，并且在容器或 Windows 环境中可能行为不同。谨慎使用。（参见下文“Windows 专用注意事项”。）
5) 更改进程的有效主目录（容器/CI 小技巧）
在 CI、容器或短暂环境中运行时，你可以为 gemini 进程更改 $HOME（Unix）或 %USERPROFILE%（Windows）环境变量，使其默认的 ~/.gemini 解析到你控制的路径：
# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini
这对 CI 的可复现性很有用，但需注意：更改 HOME 可能影响其他工具和认证流程（例如 Google OAuth 缓存），因此将该技术限定在隔离的容器或进程级包装器中使用。
我如何通过 CometAPI 安装并使用 Gemini CLI？
简短回答：有两条实用路径——（A）通过 CometAPI 直接调用 Gemini 模型（推荐且最简单），或（B）让官方 Gemini CLI 与 CometAPI 通话：使用支持自定义基础 URL 的某个 Gemini-CLI 发行版（部分版本/PR 添加了该能力），或运行一个小型本地代理，将 Gemini-CLI 请求转换为 CometAPI/OpenAI 风格调用。
什么是 CometAPI？
CometAPI 是一个 API 聚合/网关，采用 OpenAI 风格的 HTTP API，在一个接口后暴露数百个第三方模型（包括 Google 的 Gemini 系列）。你注册并获取一个 Bearer API Key，然后调用诸如 https://api.cometapi.com/v1/chat/completions 的端点。CometAPI 在 Authorization 头中使用标准 Bearer 令牌。
为什么使用 CometAPI？它提供比官方 API 更低的价格以便于集成。Gemini CLI 安装与使用指南:
我如何通过 CometAPI 直接调用 Gemini 模型？（推荐）
如果你的目标仅是使用 Gemini 模型且并不严格需要 Gemini CLI 的特性，直接调用 CometAPI 简单且可靠。
export COMET_KEY="sk-xxxx"curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \ -H "Authorization: Bearer $COMET_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-2.5-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the 3 key benefits of unit tests."} ], "max_tokens": 300 }' | jq .
这些直接调用允许你将 CometAPI 集成到脚本、应用或 CI，而无需依赖 Gemini CLI。
我能让 Gemini CLI 使用 CometAPI 吗？
部分 Gemini CLI 版本/PR 添加了用于覆盖 Gemini API 基础 URL 的环境变量。如果你安装的 gemini 支持配置自定义 Gemini 基础 URL + 使用 CometAPI Key，你可以将其指向 CometAPI，并将 CometAPI Key 设置为 GEMINI_API_KEY（CLI 期望以 GEMINI_API_KEY 命名的 Key 变量用于 Gemini API Key 认证）。
示例：
# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx" # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1" # if supportedgemini # run the CLI; it will use the configured base URL
故障排除：常见问题与修复
问题：Gemini 无法看到另一个仓库中的文件
- 启动时尝试
gemini --include-directories /path/to/repo。或在会话中使用：/directory add /path/to/repo。 - 如果仓库位于网络挂载上，检查权限并确认 CLI 进程用户可读取这些文件。
- 如果你使用符号链接移动了
.gemini，请验证 CLI 是否会跟随GEMINI.md与settings.json的符号链接（某些版本出于安全原因不跟随特定符号链接）。
问题：gemini 在 Windows 上无法创建 ~/.gemini（EPERM）
这通常意味着你的进程缺少写入 %USERPROFILE% 的权限。解决方法：
- 以管理员身份运行终端或调整文件夹权限。
- 通过符号链接设置自定义配置位置，或在支持时通过环境变量（关注未来对
GEMINI_CONFIG_DIR的支持）。
问题：在 Shell 模式内 cd 不会更改工作目录
这是在某些平台上的已知问题。建议：切换为在 Gemini CLI 进程之外运行 Shell 命令，或通过 /directory add 添加目录。
问题：CometAPI 模型名称与预期不匹配
调用 /v1/models 端点并检查 JSON。模型 ID 通常包含精确的变体字符串（例如 gemini-2.5-flash-preview-04-17）。在请求中使用该精确字符串。
结论
Gemini CLI 的默认设计偏向合理且易发现的行为：用户级默认使用全局 ~/.gemini，项目级使用项目中的 .gemini 作为每仓库覆盖。社区一直在推动更强的原生可配置性（显式环境变量或标志），以使该工具更适合多用户、容器化和企业环境。
如何更改 Gemini CLI 目录：
概览：Gemini CLI 在 .gemini 目录（通常是 ~/.gemini）中存储用户范围的配置与上下文文件。你可以通过以下方式影响 CLI 使用的目录：（1）依赖当前工作目录中的项目级 .gemini，（2）在支持时使用环境变量或 CLI 选项，（3）在交互会话中添加工作区目录，或（4）在缺少原生选项时使用文件系统技术（符号链接、绑定挂载，或更改主目录/用户配置路径变量）。
开始使用前，探索 Gemini 3 Pro 等 Gemini 模型在 Playground 中的能力，并查阅 API 指南 获取详细说明。访问前，请确保已登录 CometAPI 并获取 API Key。CometAPI 提供远低于官方价格的服务以助你集成。
Ready to Go?→ Gemini 模型免费试用 !