1. 引言

在前面的博客中，博主已经对 Gemini 做了一些简单的总结，有兴趣的同学可以阅读：

• 《Gemini 3 完整指南（一）：免费订阅、CLI 安装到 Agent 开发一次搞懂》
• 《Gemini 3 完整指南（二）：CLI 官方文档导航与速查索引》
• 《Gemini 3 完整指南（三）：CLI 功能特性及架构解密》
• 《Gemini 3 完整指南（四）：彻底拆解CLI 配置》
• 《Gemini 3 完整指南（五）：CLI 命令、无头模式、主题与快捷键》

本文是进阶篇”，重点整理 Gemini CLI 中更偏工程/企业落地的能力：

• Checkpointing（检查点）：AI 写文件前自动快照，随时回滚
• 企业级集中式配置：系统默认值/覆盖项/用户/工作区的合并与优先级
• 安全治理：工具白名单/黑名单、禁用 YOLO、MCP 工具治理、网络代理、审计遥测
• Sandbox（沙箱）：Docker/Podman/macOS Seatbelt 隔离执行
• OpenTelemetry：日志/指标/Trace 可观测性，成本与治理更透明

---

2. Checkpointing（检查点）

原文地址：https://geminicli.com/docs/cli/checkpointing/

一句话解释： 当你允许 Gemini CLI 调用会“改文件”的工具（比如写文件、替换内容）时，它会先自动做一次项目快照，确保你随时能恢复到“改之前”的状态。

这让你可以更大胆地让 AI 做重构/批量修改，因为你知道——随时可撤销。

---

2.1 工作原理

当你批准一个会修改文件系统的工具（例如 write_file 或 replace）时，CLI 会自动创建一个“检查点”。检查点包含：

1. Git 快照（影子仓库提交）

   • CLI 会在一个特殊的影子 Git 仓库中创建一次提交
   • 影子仓库位置：~/.gemini/history/<project_hash>
   • 这不会干扰你自己项目的 Git 仓库（你的 .git 不会被动）

2. 对话历史 ：与 agent 的整个对话会被保存（方便恢复上下文）

3. 工具调用信息 ：即将执行的工具调用细节也会被记录（恢复后可重新执行/修改/忽略）

---

2.2 数据存放在哪？

所有检查点数据都会存储在本机：

• Git 快照（影子仓库）：~/.gemini/history/<project_hash>
• 对话历史与工具调用 JSON：通常在
  ~/.gemini/tmp/<project_hash>/checkpoints

这也意味着它适合企业环境：不会把你的项目快照上传到远程仓库。

---

2.3 启用 Checkpointing

注意：--checkpointing 这个命令行标志已在 0.11.0 移除，现在只能通过 settings.json 开启。

在你的 settings.json 里添加：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

---

2.4 使用 /restore 管理检查点

启用后，检查点会自动创建。管理它们用 /restore。

---

1）列出当前项目所有检查点：

/restore

CLI 会列出检查点文件，一般命名类似：

• 2025-06-22T10-00-00_000Z-my-file.txt-write_file

含义通常是：时间戳 + 文件名 + 工具名

---

2）恢复到某个检查点：

/restore <checkpoint_file>

例子：

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

恢复后会发生三件事：

• 项目文件回滚到快照状态
• CLI 内对话历史恢复
• 原始工具调用会再次出现（你可以重新运行/修改/忽略）

---

3. 面向企业的 Gemini CLI（集中式配置 + 安全治理最佳实践）

企业里最常见的痛点是：

• 大家配置不一致
• 工具权限不可控
• 网络、审计、合规无法统一管理

Gemini CLI 提供了 系统级配置 来解决这些问题。

---

3.1 系统设置文件

企业管理中最强大的工具是全局系统设置文件：

• system-defaults.json：系统默认基线（最低优先级）
• settings.json：系统覆盖项（最高优先级，最终裁决）

CLI 会从 4 个文件合并配置（单值设置优先级如下）：

1. 系统默认值（system-defaults.json）
2. 用户设置（~/.gemini/settings.json）
3. 工作区设置（<project>/.gemini/settings.json）
4. 系统覆盖项（settings.json）最高

对数组/对象类型（如 includeDirectories、mcpServers），是“合并”而不是直接覆盖。

---

3.2 合并示例

系统默认值（system-defaults.json）：

{
  "ui": {
    "theme": "default-corporate-theme"
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/common-context"]
  }
}

用户设置（~/.gemini/settings.json）：

{
  "ui": {
    "theme": "user-preferred-dark-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-dev"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    }
  },
  "context": {
    "includeDirectories": ["~/gemini-context"]
  }
}

工作区设置（/.gemini/settings.json）：

{
  "ui": {
    "theme": "project-specific-light-theme"
  },
  "mcpServers": {
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": ["./project-context"]
  }
}

系统覆盖项（/etc/…/settings.json）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    }
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/global-context"]
  }
}

最终合并结果（最终真正生效的配置）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    },
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": [
      "/etc/gemini-cli/common-context",
      "~/gemini-context",
      "./project-context",
      "/etc/gemini-cli/global-context"
    ]
  }
}

结论：

• theme：系统覆盖项最高优先级，强制生效
• mcpServers：对象合并，同名 corp-server 以系统覆盖项为准
• includeDirectories：数组拼接（系统默认 → 用户 → 工作区 → 系统覆盖）

---

3.3 系统配置文件的位置（不同系统）

• Linux：/etc/gemini-cli/settings.json
• Windows：C:\ProgramData\gemini-cli\settings.json
• macOS：/Library/Application Support/GeminiCli/settings.json
• 可用环境变量覆盖：GEMINI_CLI_SYSTEM_SETTINGS_PATH

---

3.4 企业常用技巧

问题：用户可以自己 export GEMINI_CLI_SYSTEM_SETTINGS_PATH=... 指向别的配置，从而绕开公司策略。

解决：用一个 wrapper 脚本把环境变量写死。

把下面脚本保存为 /usr/local/bin/gemini（并确保它在 PATH 中优先于真实 gemini）：

#!/bin/bash

# Enforce the path to the corporate system settings file.
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

# Find the original gemini executable.
REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)

if [ -z "$REAL_GEMINI_PATH" ]; then
  echo "Error: The original 'gemini' executable was not found." >&2
  exit 1
fi

# Pass all arguments to the real Gemini CLI executable.
exec "$REAL_GEMINI_PATH" "$@"

---

3.5 工具访问控制（白名单优先 + 禁用 YOLO 模式）

企业安全治理的核心目标：最小权限原则（Least Privilege）。

---

3.5.1 coreTools（允许列表）

只允许安全的只读工具（示例：读文件 + 列目录）：

{
  "tools": {
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
  }
}

---

3.5.2 excludeTools（阻止列表）

例如阻止删除命令：

{
  "tools": {
    "exclude": ["ShellTool(rm -rf)"]
  }
}

风险：黑名单是字符串匹配思路，聪明用户可能绕过。生产环境建议优先使用白名单。

---

3.5.3 禁用 YOLO 模式

目的：防止模型在没有明确批准的情况下执行工具。

{
  "security": {
    "disableYoloMode": true
  }
}

---

3.6. MCP（自定义工具）治理

如果你们用 MCP server（Model-Context Protocol）接入内部工具，就一定要理解：

• mcpServers 会合并
• 同名 server 的优先级：System > Workspace > User
• 用户无法覆盖 system 定义，但可以新增“新名字”的 server（除非你用 allowed 限制）

---

3.6.1 限制 MCP 服务器暴露的工具（includeTools / excludeTools）

推荐 includeTools（只开放必要能力）：

{
  "mcp": {
    "allowed": ["third-party-analyzer"]
  },
  "mcpServers": {
    "third-party-analyzer": {
      "command": "/usr/local/bin/start-3p-analyzer.sh",
      "includeTools": ["code-search", "get-ticket-details"]
    }
  }
}

---

3.6.2 更安全的企业模式（system 中同时定义 + 加 allowed 白名单）

system settings.json 示例（强治理）：

{
  "mcp": {
    "allowed": ["corp-data-api", "source-code-analyzer"]
  },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh",
      "timeout": 5000
    },
    "source-code-analyzer": {
      "command": "/usr/local/bin/start-analyzer.sh"
    }
  }
}

效果：

• 用户新增的 server 名字不在 mcp.allowed → 直接被阻止
• 同名 server 即使用户定义 → system 会覆盖

---

3.6.3 不安全模式（只定义 server 但不加 allowed）

{
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

风险：用户可以在自己 settings 里新增任意 server，最终会合并进可用工具列表。

---

4. Sandbox（沙箱）

原文地址：https://geminicli.com/docs/cli/sandbox/

沙箱的定位：在 AI 工具执行与宿主机之间加一道隔离层，避免误操作造成系统损坏。

沙箱方式有如下两种：

• macOS Seatbelt（仅 macOS）：sandbox-exec，轻量
• Docker/Podman 容器沙箱：跨平台、隔离更强（推荐企业）

---

安装与验证方式如下：

npm install -g @google/gemini-cli
gemini --version

---

快速开启沙箱（3 种方式）

方式 1：命令行 flag

gemini -s -p "analyze the code structure"

方式 2：环境变量

export GEMINI_SANDBOX=true
gemini -p "run the test suite"

方式 3：settings.json（长期配置）

{
  "tools": {
    "sandbox": "docker"
  }
}

---

启用优先级（从高到低）：

1. 命令行：-s/--sandbox
2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
3. settings：{"tools":{"sandbox":true}}（或指定 docker/podman）

---

macOS Seatbelt Profiles（常用）：

通过 SEATBELT_PROFILE 环境变量设置：

• permissive-open（默认）：限制写入外部目录，允许网络
• permissive-closed：限制写入外部目录，不允许网络
• restrictive-open：更严格，允许网络
• restrictive-closed：最严格

---

自定义容器沙箱参数（SANDBOX_FLAGS）

例如 Podman 禁用 SELinux label：

export SANDBOX_FLAGS="--security-opt label=disable"

多个参数：

export SANDBOX_FLAGS="--flag1 --flag2=value"

---

调试沙箱（DEBUG）：

DEBUG=1 gemini -s -p "debug command"

注意：项目 .env 的 DEBUG=true 不会影响 gemini-cli，因为会被自动排除，需要调试请用 .gemini/.env

5. OpenTelemetry 可观测性

原文地址：https://geminicli.com/docs/cli/telemetry/

为什么需要可观测性？

• 统计团队使用情况与功能采用率
• 监控 token、延迟、失败率
• 审计工具调用（谁在用什么工具做什么）
• 成本优化（缓存 token、模型路由、重试行为）

---

5.1 核心配置项（settings.json / 环境变量）

所有遥测行为都由 .gemini/settings.json 控制，也可以用环境变量覆盖。

常见配置示例：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

企业建议：

• enabled: true（开启）
• logPrompts: false（不要采集 prompt 文本，避免敏感信息泄露）
• target: gcp 或 local 看你们的后端

---

5.2 Google Cloud 遥测（推荐 Direct Export）

1）启用遥测：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}

2）运行 CLI 并产生数据：

正常使用 gemini 即可。

3）查看（Console）：

• Logs / Metrics / Traces：在 Google Cloud Console 中查看

---

5.3 本地遥测

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "",
    "outfile": ".gemini/telemetry.log"
  }
}

---

5.4 典型企业 system settings 汇总示例

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "mcp": {
    "allowed": ["corp-tools"]
  },
  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
    "logPrompts": false
  },
  "advanced": {
    "bugCommand": {
      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
    }
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

---

6. 文末

到这里，Gemini CLI 的企业级与工程化能力就基本梳理完了。可以看到，Gemini CLI 的设计目标并不只是“提升个人编码效率”，而是从一开始就围绕 可控性、安全性与可运维性 来构建，这也是它能进入真实工程与企业环境的关键。

---

回顾一下本文涉及的几个关键能力：

• Checkpointing：让 AI 的“写文件 / 重构 / 批量修改”变成一件可回滚、可恢复、可审计的事情 → 这是 AI 能真正进入生产仓库的前提

• 集中式配置与优先级合并：系统 / 用户 / 工作区 / 覆盖项的多层合并 → 让“统一策略 + 灵活使用”不再是二选一

• 工具治理 + MCP 安全模型：白名单优先、禁用 YOLO、MCP allowed + includeTools → 把 AI 的能力牢牢限制在“你允许的边界内”

• Sandbox（沙箱执行）：Docker / Podman / macOS Seatbelt → 即使 AI 出错，也被关在笼子里

• OpenTelemetry 可观测性：日志、指标、Trace、成本、审计 → 让 AI 使用情况像任何一个后端服务一样“看得见、管得住”

感谢阅读，希望能帮助到大家，本文完！