工具、Shell 和权限边界
理解 Gemini CLI 的工具系统、Shell 执行、文件写入、web 工具、sandbox 和人工确认边界。
Gemini CLI 的能力边界主要由工具决定。工具能读文件、写文件、跑 shell、访问 web、接 MCP，也能让任务从“建议”变成“执行”。
工具权限不是体验细节，而是项目安全边界。能跑命令、能写文件、能访问外部服务，就必须有确认、日志和验证。
先分三类工具
只读工具 读文件、列目录、搜索、查看状态
本地副作用工具 写文件、改配置、运行测试、安装依赖
外部副作用工具 发布、删除远端资源、改账号、触发 CI、调用付费 API第一次进入项目，只给只读任务。确认计划后，再允许本地副作用。外部副作用工具必须单独确认。
| 工具类型 | 可以默认放宽吗 | 推荐控制 |
|---|---|---|
| 只读文件 / 搜索 | 可以较宽松 | 限定目录，避免读密钥和大文件 |
| 写当前任务文件 | 按批次放行 | 每批看 diff 和验证 |
| Shell 测试 / 构建 | 看命令风险 | 先说明命令、目录和副作用 |
| 安装依赖 / 全局配置 | 不建议默认放行 | 单独确认，并记录影响范围 |
| 发布 / 删除 / 远程写入 | 不能默认放行 | 逐次确认，必要时先 dry-run |
Shell 为什么危险
Shell 工具强在通用，危险也在通用。它可以跑测试，也可以删除文件、上传数据、修改系统配置。
高风险命令包括：
- 删除、移动、覆盖大量文件。
- 改全局配置。
- 安装或升级全局依赖。
- 执行从网络下载的脚本。
- 发布、部署、推送、改远端。
推荐执行顺序
读目录 -> 读规则 -> 读相关文件 -> 提计划 -> 小范围修改 -> 只读 diff -> 跑验证 -> 总结影响不要直接从"读需求"跳到"执行复杂命令"。
新手快速入口：会话里直接 /permissions 看当前 folder trust 状态和工具批准模式；/tools 看本次会话有哪些工具可用；/policies 看 policy 规则。三条命令构成"权限自检"三件套，比翻配置文件直观。
Sandbox 的位置
Sandbox 用来降低陌生代码和不可信命令的风险。它适合：
- 探索新仓库。
- 跑未知测试。
- 执行可能写临时文件的命令。
- 分析来自外部的项目。
它不适合替代安全判断。涉及密钥、账单、部署和生产数据时，sandbox 也不能让操作自动安全。
人工确认怎么设
人工确认应该围绕风险，不是围绕工具名：
- 只读命令可以宽松。
- 写当前任务文件可以按批次确认。
- 改共享配置要单独确认。
- 远程、账号、发布、删除要逐次确认。
并发协作时的额外规则
如果多个 agent 同时改一个仓库，Gemini CLI 应该：
- 只改明确归属的目录。
- 每个批次前检查
git status。 - 不运行自动格式化全仓库命令。
- 不改别人正在改的文件。
- 发现冲突立即停，不做覆盖。
验收标准
允许工具执行前，至少能回答四个问题：
- 这个工具会读写哪些路径。
- 命令失败会留下什么中间状态。
- 怎么确认它没有越界。
- 如果结果不对，怎么回退或停止。
答不出来时，先回到只读分析或 Plan mode，不要把权限开大。
官方工具边界
官方工具页把文件系统、Shell、Web、MCP resources、todos/planning 分得很清楚。读者要先能区分只读工具、写文件工具、shell 执行和外部服务调用，再谈自动化。否则最容易把“能做”误解成“应该做”。
上线项目里，工具权限至少要和 sandbox、policy、trusted folders 一起看。单独开放 shell 或 MCP 写工具，不算完整权限设计。
权限设计示例
一个较稳的默认策略可以是：
- 允许只读文件搜索和目录探索。
- 写文件前必须展示目标路径和 diff。
- Shell 只默认允许只读诊断和项目验证命令。
- 安装依赖、迁移、发布、删除、推送必须单独确认。
- MCP 先开放 resources，再开放只读 tools，最后才开放写 tools。
这套策略不是为了降低效率，而是让任务失败时能知道边界在哪里。权限越宽，失败后的排查面越大。
多 agent 并发时还要加一条：每次写入前检查目标目录的 git status。如果同一文件被别人改动，先停下来协调，不要让模型自动合并。
失败时怎么收口
工具任务失败后，不要扩大权限。先缩小到只读事实：当前目录是什么、哪些文件被改、命令 exit code 是多少、stderr 说了什么、是否有未提交并发改动。确认这些事实后，再决定是继续、回滚还是交给人工。
权限收口比继续尝试更重要。越是高风险工具，失败后越要回到计划和证据。
失败后不要用 sudo、强制覆盖、全仓格式化或批量删除来“修一下”。这些动作会把原本局部的问题放大成环境问题或协作问题。正确做法是先保存失败证据，再只针对本次任务文件做最小修复。
如果失败原因来自权限、依赖或远程服务，应该先把它写成明确阻塞项。让模型继续猜命令，通常只会制造更多副作用。
官方资料
- Tools reference：docs/reference/tools.md
- Sandbox：docs/cli/sandbox.md
- Trusted folders：docs/cli/trusted-folders.md
- Policy engine：docs/reference/policy-engine.md