← Coding

模型与开放条件Model & openness

用 Google 自家的 Gemini 系列，模型可以换。 上下文上限明确标了 1M token。

README 首屏原文：「Powerful Gemini 3 models: Access to improved reasoning and 1M token context window」

换模型：命令行用 gemini -m gemini-2.5-flash 指定。 用 Gemini API Key 登录时，官方描述是：

"Model selection: Choose specific Gemini models"

三种接入方式（README「Authentication Options」）：

• Google 账号 OAuth 登录 —— 免费层用这个，60 请求/分、1,000 请求/日，不用管 key
• Gemini API Key —— 在 AI Studio 取 key，按量计费
• Vertex AI —— 企业用，需要项目和区域

模型路由：Plan Mode 可用 general.plan.modelRouting。 它在 Pro（规划）与 Flash（实现）之间自动切换。 另有实验性的 Local Model Routing（Gemma）。

CLI 侧可切换模型的具体清单与版本映射：官方未给出完整列表。 （已查仓库文档与 reference/configuration 两页。）

Uses Google's own Gemini family; models can be switched. The context ceiling is explicitly stated as 1M tokens.

README first-screen wording: "Powerful Gemini 3 models: Access to improved reasoning and 1M token context window"

Switching models: specify via gemini -m gemini-2.5-flash on the command line. When signing in with a Gemini API Key, the official description is:

"Model selection: Choose specific Gemini models"

Three access modes (README "Authentication Options"):

• Google account OAuth login — the free tier uses this: 60 requests/min, 1,000 requests/day, no key to manage
• Gemini API Key — get a key in AI Studio, pay per usage
• Vertex AI — for enterprises, requires a project and region

Model routing: Plan Mode can use general.plan.modelRouting. It switches automatically between Pro (planning) and Flash (implementation). There is also experimental Local Model Routing (Gemma).

The exact list of switchable models on the CLI side and their version mapping: the official docs do not give a complete list. (Repository docs and the reference/configuration page both checked.)

运行位置Where it runs

本地进程，在终端里跑，靠 npx 免安装启动。

官方把「免安装」写成仓库首屏的卖点，这是它降低上手门槛的地方。

README 原文：「Using npx (no installation required)」

A local process, running in the terminal, launchable without installation via npx.

The official docs make "no installation" a first-screen selling point of the repository — this is how it lowers the entry barrier.

README wording: "Using npx (no installation required)"

本地文件Local files

内置文件工具默认以工作区为根，边界明确。

官方「File system tools」页原文：All file system tools operate within a rootDirectory (the current working directory or workspace root) for security

工具集：

• list_directory
• read_file —— 支持文本 / 图片 / 音频 / PDF
• write_file
• replace
• glob
• grep_search

哪些要你点头才能动：

• write_file 与 replace —— 官方标注 "Requires manual user approval"

扩目录：启动加参数 gemini --include-directories ../lib,../docs。 会话内用 /directory add <path>（受限沙箱配置下禁用）。

忽略边界：遵守 .gitignore，也支持同语法的 .geminiignore。

改动可回退：批准改文件的工具时，CLI 会提交一次快照。 它落在 shadow Git 仓库里，不干扰你自己的项目仓库。 可用 /restore 回退。

checkpointing 页记的仓库位置：~/.gemini/history/<project_hash>

原文：「It does not interfere with your own project's Git repository」

语义索引（Code Customization / RAG）的算法与大仓库耗时官方未说明。 （已查 file-system 与 configuration 两页，只有 general.logRagSnippets 这类调试开关。）

Built-in file tools default to the workspace as root, with a clear boundary.

Official "File system tools" page wording: All file system tools operate within a rootDirectory (the current working directory or workspace root) for security

Tool set:

• list_directory
• read_file — supports text / images / audio / PDF
• write_file
• replace
• glob
• grep_search

Which ones need your nod to act:

• write_file and replace — officially marked "Requires manual user approval"

Extending directories: launch with gemini --include-directories ../lib,../docs. Within a session use /directory add <path> (disabled under restricted sandbox configs).

Ignore boundary: respects .gitignore, and supports .geminiignore with the same syntax.

Changes are revertible: when you approve a file-changing tool, the CLI commits a snapshot. It lands in a shadow Git repository, not interfering with your own project repo. /restore reverts.

The repo location recorded on the checkpointing page: ~/.gemini/history/<project_hash>

Original wording: "It does not interfere with your own project's Git repository"

The semantic-indexing (Code Customization / RAG) algorithm and large-repo time cost are not stated officially. (file-system and configuration pages checked; only debug switches like general.logRagSnippets exist.)

关机后的任务Tasks after shutdown

本地 CLI，不支持关机续跑。

非交互 / headless 是脚本化，不是后台。 它仍跑在你自己的机器上。

官方「Headless mode」页原文："Headless mode provides a programmatic interface to Gemini CLI... without an interactive terminal UI"

触发方式是：

• 非 TTY 环境
• -p/--prompt

输出可选 JSON 或 stream-json，供 CI 与自动化调用。

执行环境归你：官方未提供厂商托管的常驻执行环境。 仓库里的 GitHub Action 也跑在你仓库的 CI runner 上。

中断可恢复：checkpointing 与 /chat save / /resume 可以保存和恢复会话。 开关是 general.checkpointing.enabled。 general.sessionRetention 默认保留 30 天。 超期自动清理。

额度就是官方用量口径里的每日请求上限。 官方未另设云端额度。

A local CLI; it cannot keep running after shutdown.

Non-interactive / headless is scripting, not background. It still runs on your own machine.

Official "Headless mode" page wording: "Headless mode provides a programmatic interface to Gemini CLI... without an interactive terminal UI"

Triggers:

• non-TTY environments
• -p/--prompt

Output can be JSON or stream-json for CI and automation to consume.

The execution environment is yours: the official docs provide no vendor-hosted resident execution environment. The GitHub Action in the repository also runs on your repo's CI runners.

Interruption is recoverable: checkpointing and /chat save / /resume can save and restore sessions. The switch is general.checkpointing.enabled. general.sessionRetention defaults to 30 days. Expired sessions are cleaned up automatically.

Quota is exactly the daily request ceilings in the official usage policy. The official docs set no separate cloud quota.

工具与扩展Tools & extensions

明确支持 MCP，而且是它标注的核心特性。

README 原文：「🔌 Extensible: MCP (Model Context Protocol) support for custom capabilities」

MCP 另有独立文档页：/docs/tools/mcp-server。 它举的例子是把 MCP 用来接多模态生成：

「Use MCP servers to connect new capabilities, including media generation with Imagen, Veo or Lyria」

这条例子值得单独记：MCP 在这里不只是接工具， 还能接 Google 的多模态生成能力（图像 / 视频 / 音频）。 这个用法在其它 CLI 工具的仓库首屏里没被强调。

内置工具清单：

• Google Search grounding（搜索接地）
• shell

另有非交互模式做脚本自动化。官方有独立章节 「Non-interactive mode for scripts」。

MCP is explicitly supported and is one of its headline features.

README wording: "🔌 Extensible: MCP (Model Context Protocol) support for custom capabilities"

MCP has its own docs page: /docs/tools/mcp-server. The example it gives is using MCP to connect multimodal generation:

"Use MCP servers to connect new capabilities, including media generation with Imagen, Veo or Lyria"

This example deserves its own note: here MCP is not just connecting tools, it can also connect Google's multimodal generation capabilities (image / video / audio). This usage is not emphasized on the first screen of other CLI tools' repositories.

Built-in tool list:

• Google Search grounding
• shell

There is also non-interactive mode for script automation. The official docs have a dedicated section "Non-interactive mode for scripts".

上下文与记忆Context & memory

1M token 上下文 + GEMINI.md 分层上下文 + 自动历史压缩，三项都有官方专页。

上下文窗口：README 首屏写 Gemini 3 models with 1M token context window。

上下文层级（官方「GEMINI.md」页）：

• ① 全局 ~/.gemini/GEMINI.md
• ② 工作区目录及其父目录的 GEMINI.md
• ③ JIT —— 工具访问某目录时，扫描它和祖先目录的 GEMINI.md（至 trusted root）

文件名可由 context.fileName 改（如 AGENTS.md / CONTEXT.md）。

GEMINI.md 页：支持用 @file.md 语法导入。 /memory show 与 /memory reload 可查看与重载。

压缩策略已核到（官方 core 页）：

"When a conversation approaches the token limit... the core automatically compresses the conversation history"

阈值由 model.compressionThreshold 控制。 默认值是 0.5。 也可以 /compress 手动把整个上下文替换为摘要。

跨会话记忆：官方 Memory 工具把持久事实写进 GEMINI.md（项目 / 全局两级）， 随分层上下文注入后续会话。token caching 仅 API key / Vertex 用户可用。

1M-token context + layered GEMINI.md context + automatic history compression — all three have dedicated official pages.

Context window: the README first screen says Gemini 3 models with 1M token context window.

Context layers (official "GEMINI.md" page):

• ① global ~/.gemini/GEMINI.md
• ② GEMINI.md in workspace directories and their parents
• ③ JIT — when a tool accesses a directory, it scans that directory's and its ancestors' GEMINI.md (up to the trusted root)

The file name can be changed via context.fileName (e.g. AGENTS.md / CONTEXT.md).

GEMINI.md page: supports imports via @file.md syntax. /memory show and /memory reload inspect and reload.

Compaction strategy verified (official core page):

"When a conversation approaches the token limit... the core automatically compresses the conversation history"

The threshold is controlled by model.compressionThreshold. The default is 0.5. You can also /compress to manually replace the whole context with a summary.

Cross-session memory: the official Memory tool writes durable facts into GEMINI.md (project / global two levels), injected into later sessions via the layered context. Token caching is only available to API key / Vertex users.

权限与限制Permissions & limits

沙箱、审批、信任目录三层官方都有专页，是本分区里权限面写得最细的一条。

沙箱：官方「Sandboxing」页给了这些方式。

• macOS Seatbelt —— 默认档 permissive-open：默认拒绝、写限项目目录，但允许读与网络
• Docker / Podman
• Windows 原生
• gVisor / runsc
• LXC / LXD（实验）

启用方式：

• -s/--sandbox
• GEMINI_SANDBOX
• tools.sandbox

工具级另有 security.toolSandboxing。

沙箱扩张：命令因权限受限失败时，会弹 "Sandbox Expansion Request"。逐次批准可临时放宽。 越界目录可用 SANDBOX_MOUNTS 挂载。

审批模式（configuration 页）：general.defaultApprovalMode 有三个值：

• default —— 逐次询问
• auto_edit
• plan —— 只读

--yolo（全部自动批准）只能在命令行开。

策略引擎（「Policy engine」页）：~/.gemini/policies/*.toml 用规则定义 allow / deny / ask_user。 匹配条件可按工具名、参数、审批模式与交互 / 非交互环境。 规则分 Default / Extension / User / Admin 四级。 Admin 可强制覆盖。

Trusted Folders：默认关闭。 开关是 security.folderTrust.enabled。 未信任时进 safe mode —— 忽略工作区 .gemini/settings.json 与 .env、 禁用工具自动接受、不连 MCP、不加载自定义命令。 CI 想绕过的话，有两条路：

• --skip-trust
• GEMINI_CLI_TRUST_WORKSPACE=true

configuration 页另有环境变量脱敏一节。

Sandbox, approvals and trusted folders each have dedicated official pages — the most finely documented permission surface in this section.

Sandbox: the official "Sandboxing" page gives these mechanisms.

• macOS Seatbelt — default profile permissive-open: deny by default, writes limited to the project directory, but reads and network allowed
• Docker / Podman
• native Windows
• gVisor / runsc
• LXC / LXD (experimental)

Enabling:

• -s/--sandbox
• GEMINI_SANDBOX
• tools.sandbox

Tool-level additionally has security.toolSandboxing.

Sandbox expansion: when a command fails due to permission limits, a "Sandbox Expansion Request" pops up. Approving case by case relaxes it temporarily. Out-of-bounds directories can be mounted via SANDBOX_MOUNTS.

Approval modes (configuration page): general.defaultApprovalMode has three values:

• default — ask each time
• auto_edit
• plan — read-only

--yolo (auto-approve everything) can only be enabled on the command line.

Policy engine ("Policy engine" page): ~/.gemini/policies/*.toml defines allow / deny / ask_user via rules. Match conditions can key on tool name, arguments, approval mode, and interactive / non-interactive environment. Rules have four tiers: Default / Extension / User / Admin. Admin can force-override.

Trusted Folders: off by default. The switch is security.folderTrust.enabled. When untrusted it enters safe mode — ignoring workspace .gemini/settings.json and .env, disabling tool auto-accept, not connecting MCP, not loading custom commands. To bypass in CI there are two routes:

• --skip-trust
• GEMINI_CLI_TRUST_WORKSPACE=true

The configuration page also has an environment-variable redaction section.

适合什么任务Best for

适合三类场景：

• 想免安装快速试用（npx，不留安装痕迹）
• 需要 MCP 扩展，尤其是把 Gemini 的多模态生成能力（Imagen / Veo / Lyria）接进 Agent 工作流
• 需要脚本化非交互运行，比如接进 CI

另外三类人也合适：

• 需要大上下文窗口的人 —— 1M token，是本分区里明确写出上限的少数
• 需要「改动可回退」保证的人 —— shadow Git 检查点加 /restore
• 需要项目级长期指令文件的人 —— GEMINI.md

不适合把额度当成无限用的场景。 免费层有明确日额度，数字是 6,000 代码请求 + 240 对话/日。 而且 CLI 与代理模式额度合并计算。

Fits three scenarios:

• wanting an install-free quick trial (npx, leaving no installation trace)
• needing MCP extensions, especially wiring Gemini's multimodal generation (Imagen / Veo / Lyria) into an agent workflow
• needing scripted non-interactive runs, e.g. wiring into CI

Three more kinds of people also fit:

• those needing a large context window — 1M tokens, one of the few in this section with an explicit ceiling stated
• those needing a "changes are revertible" guarantee — shadow-Git checkpoints plus /restore
• those needing a project-level standing instruction file — GEMINI.md

Not a fit for treating the quota as unlimited. The free tier has explicit daily ceilings: 6,000 code requests + 240 chats/day. And CLI and proxy-mode quotas are counted together.

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.