---
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="/zh-Hant/docs/gemini-cli/official/03-tools-mcp" />
  <Card title="Sandbox" description="trust 只決定是否載入專案能力，命令和檔案邊界繼續看 sandbox。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title=".geminiignore" description="信任專案之前，先確認敏感檔案沒有進入 AI 上下文。" href="/zh-Hant/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)
