---
title: "工具、Shell 和权限边界"
description: "理解 Gemini CLI 的工具系统、Shell 执行、文件写入、web 工具、sandbox 和人工确认边界。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的能力边界主要由工具决定。工具能读文件、写文件、跑 shell、访问 web、接 MCP，也能让任务从“建议”变成“执行”。

> [!WARNING]
> 工具权限不是体验细节，而是项目安全边界。能跑命令、能写文件、能访问外部服务，就必须有确认、日志和验证。

## 先分三类工具

```text
只读工具        读文件、列目录、搜索、查看状态
本地副作用工具  写文件、改配置、运行测试、安装依赖
外部副作用工具  发布、删除远端资源、改账号、触发 CI、调用付费 API
```

第一次进入项目，只给只读任务。确认计划后，再允许本地副作用。外部副作用工具必须单独确认。

| 工具类型 | 可以默认放宽吗 | 推荐控制 |
| --- | --- | --- |
| 只读文件 / 搜索 | 可以较宽松 | 限定目录，避免读密钥和大文件 |
| 写当前任务文件 | 按批次放行 | 每批看 diff 和验证 |
| Shell 测试 / 构建 | 看命令风险 | 先说明命令、目录和副作用 |
| 安装依赖 / 全局配置 | 不建议默认放行 | 单独确认，并记录影响范围 |
| 发布 / 删除 / 远程写入 | 不能默认放行 | 逐次确认，必要时先 dry-run |

## Shell 为什么危险

Shell 工具强在通用，危险也在通用。它可以跑测试，也可以删除文件、上传数据、修改系统配置。

高风险命令包括：

- 删除、移动、覆盖大量文件。
- 改全局配置。
- 安装或升级全局依赖。
- 执行从网络下载的脚本。
- 发布、部署、推送、改远端。

## 推荐执行顺序

```text
读目录 -> 读规则 -> 读相关文件 -> 提计划 -> 小范围修改 -> 只读 diff -> 跑验证 -> 总结影响
```

不要直接从"读需求"跳到"执行复杂命令"。

> [!TIP]
> **新手快速入口**：会话里直接 `/permissions` 看当前 folder trust 状态和工具批准模式；`/tools` 看本次会话有哪些工具可用；`/policies` 看 policy 规则。三条命令构成"权限自检"三件套，比翻配置文件直观。

## Sandbox 的位置

Sandbox 用来降低陌生代码和不可信命令的风险。它适合：

- 探索新仓库。
- 跑未知测试。
- 执行可能写临时文件的命令。
- 分析来自外部的项目。

它不适合替代安全判断。涉及密钥、账单、部署和生产数据时，sandbox 也不能让操作自动安全。

## 人工确认怎么设

人工确认应该围绕风险，不是围绕工具名：

- 只读命令可以宽松。
- 写当前任务文件可以按批次确认。
- 改共享配置要单独确认。
- 远程、账号、发布、删除要逐次确认。

## 并发协作时的额外规则

如果多个 agent 同时改一个仓库，Gemini CLI 应该：

- 只改明确归属的目录。
- 每个批次前检查 `git status`。
- 不运行自动格式化全仓库命令。
- 不改别人正在改的文件。
- 发现冲突立即停，不做覆盖。

## 验收标准

允许工具执行前，至少能回答四个问题：

1. 这个工具会读写哪些路径。
2. 命令失败会留下什么中间状态。
3. 怎么确认它没有越界。
4. 如果结果不对，怎么回退或停止。

答不出来时，先回到只读分析或 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](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/tools.md)
- Sandbox：[docs/cli/sandbox.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/sandbox.md)
- Trusted folders：[docs/cli/trusted-folders.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/trusted-folders.md)
- Policy engine：[docs/reference/policy-engine.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/policy-engine.md)

## 下一篇

<Cards>
  <Card title="MCP 和 Extensions" description="本地工具边界清楚后，再把外部系统接进来。" href="/docs/gemini-cli/understanding/06-mcp-extensions" />
  <Card title="Shell tool" description="需要查 shell 工具细节、确认和风险时，回到官方 Shell tool 页。" href="/docs/gemini-cli/official/03-tools-mcp/32-shell-tool" />
  <Card title="Sandbox" description="需要隔离未知命令和陌生项目时，回到 sandbox 页面。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>
