---
title: "Trusted folders"
description: "Gemini CLI trusted folders 的用途：信任当前 workspace、跳过 folder trust check 的风险，以及真实项目如何设置边界。"
verifiedAt: "2026-05-09"
---

Trusted folders 用来处理 Gemini CLI 对当前 workspace 的信任判断。CLI 参数里也有 `--skip-trust`，可跳过当前 workspace 的 trust check。

> [!WARNING]
> **不要为了省一步确认就默认跳过 trust**。信任目录意味着你愿意让 Gemini CLI 在这个目录里读取、分析并可能执行工具。

## 启用方式

Trusted folders 默认关闭。要启用，在用户级 `settings.json` 中加入：

```json
{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}
```

启用后，第一次进入目录会出现 trust dialog。可选项通常包括信任当前目录、信任父目录，或不信任。决定会写入 `~/.gemini/trustedFolders.json`。

如果使用 IDE integration，IDE 的 trust signal 会优先于本地 trust 文件。这意味着 VS Code 工作区的信任状态可能影响 Gemini CLI 是否进入受限模式。教程里同时讲 IDE 和 CLI 时，要把这条边界写清楚。

## Discovery 会显示什么

在你做信任决定前，Gemini CLI 会扫描当前 workspace 的潜在配置，并在 dialog 中提示：

- custom commands。
- MCP servers。
- hooks。
- local skills。
- workspace settings overrides。
- 高风险配置警告，例如自动批准工具或关闭 sandbox。
- 配置解析错误，例如 malformed `settings.json`。

这一步的价值是让你知道“信任后会加载什么”，而不是盲目点确认。

## 适合信任的目录

- 你自己的项目仓库。
- 已经清楚文件结构和敏感边界的目录。
- 已经配置 `.geminiignore` 的项目。
- 低风险 demo 项目。

## 不适合直接信任

- 下载来的陌生代码。
- 含生产密钥或客户数据的目录。
- 大量未知脚本目录。
- 不受版本控制的临时文件夹。

## 建议

第一次进入新项目时，先只读分析。确认目录边界后，再考虑信任和更高权限。

| 目录状态 | 建议选择 | 原因 |
| --- | --- | --- |
| 自己维护的长期项目 | 信任当前项目目录 | 可加载项目配置和命令 |
| monorepo 根目录 | 谨慎，必要时信任子目录 | 根目录权限影响面更大 |
| 下载的陌生代码 | 先不信任 | 先看脚本、MCP、hooks 和配置 |
| CI workspace | 只在受控环境跳过 trust | 无交互弹窗，但风险要前置控制 |
| 含敏感数据目录 | 不信任或移出敏感数据 | trust 不是数据脱敏 |

## 不信任时的限制

不信任目录时，Gemini CLI 会进入受限 safe mode：不会加载项目 `.gemini/settings.json`，不会加载项目 `.env`，不会连接项目 MCP server，不加载自定义命令，extension 管理受限，自动 memory loading 关闭，并且工具 auto-acceptance 不生效。

这也是 trusted folders 的核心价值：它不是“允许 Gemini 读当前文件夹”这么简单，而是决定是否加载工作区提供的可执行能力。陌生仓库里最危险的往往不是 Markdown，而是 hooks、MCP server、自动批准工具和项目级 settings。

## CI 和 headless

CI 没法弹出 trust dialog。如果启用了 Folder Trust 而 workspace 未被信任，CLI 会退出。自动化环境可以临时使用：

```bash
gemini --skip-trust
```

或设置：

```text
GEMINI_CLI_TRUST_WORKSPACE=true
```

这类跳过只应该用于你已经控制的 CI workspace，不应该出现在普通本地教程的默认命令里。

## 验收方式

先在一个 demo 目录启用 trust，确认 `~/.gemini/trustedFolders.json` 出现记录。再在一个未信任目录放入测试 MCP 或 custom command，确认 Gemini CLI 不加载它。最后通过 `/permissions` 修改当前目录 trust 决策，验证团队文档中的恢复路径可用。

如果团队文档建议信任父目录，要额外列出影响面。信任 monorepo 根目录会覆盖多个 package；信任某个 app 子目录则只影响当前 app。商业项目里默认优先信任最小目录，除非你明确需要根层 commands、MCP 或 settings。

## 接下来去哪

<Cards>
  <Card title="工具与 MCP" description="上下文和信任边界完成后，进入工具、MCP 和 extensions。" href="/docs/gemini-cli/official/03-tools-mcp" />
  <Card title="Sandbox" description="trust 只决定是否加载项目能力，命令和文件边界继续看 sandbox。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title=".geminiignore" description="信任项目之前，先确认敏感文件没有进入 AI 上下文。" href="/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
</Cards>

## 官方来源

- [Gemini CLI trusted folders](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/trusted-folders.md)
