Gemini CLI Trusted Folders 사용법: 폴더 신뢰와 MCP 서버 차단 확인하기

Gemini CLI를 프로젝트 폴더에서 실행하면 코드만 읽는 것이 아닙니다. 저장소 안의 .gemini/settings.json, .env, 사용자 정의 명령, Hook, Skill, MCP 서버 정의도 작업 방식에 영향을 줄 수 있습니다. 처음 내려받은 저장소라면 내용을 충분히 검토하기 전에 프로젝트 설정이 적용되거나 외부 프로세스가 시작되는 경계부터 확인해야 합니다.

Gemini CLI Trusted Folders는 이 문제를 다루는 폴더 신뢰 기능입니다. 폴더를 신뢰하기 전에는 프로젝트별 설정과 실행 가능한 확장 기능을 제한하고, 내용을 검토한 뒤에만 전체 기능을 엽니다. 공식 문서는 비신뢰 폴더를 선택하면 프로젝트 설정·.env·자동 승인·MCP 서버·사용자 정의 명령 등이 제한된다고 설명합니다.[1]

이 글은 2026년 9월 9일 기준 Gemini CLI v0.59.0을 격리된 임시 홈과 테스트 폴더에서 실행한 결과를 바탕으로 합니다. v0.59.0에는 신뢰 상태를 확인할 수 없을 때 기능을 열어 두지 않고, 제한 모드에서 mcpServers를 걸러내는 수정이 포함됐습니다.[2] 설치가 먼저라면 Gemini CLI 처음 설치하고 WSL에서 실행해보기부터 확인할 수 있습니다.

Trusted Folders가 필요한 이유

Trusted Folders는 “이 폴더의 파일을 읽어도 되는가?”만 묻는 목록이 아닙니다. 더 정확히는 이 폴더가 Gemini CLI의 동작을 바꾸는 로컬 설정과 코드를 제공해도 되는가를 결정합니다.

예를 들어 저장소에 다음 항목이 들어 있을 수 있습니다.

• .gemini/settings.json의 프로젝트별 설정
• .gemini/commands/*.toml 사용자 정의 명령
• 로컬 Hook과 Agent Skill
• 자동으로 실행될 수 있는 MCP 서버 명령
• 프로젝트 폴더의 .env 환경변수
• 자동 승인이나 샌드박스에 영향을 주는 설정

MCP 서버는 특히 주의가 필요합니다. 설정의 command와 args는 로컬 프로세스를 시작할 수 있습니다. 출처를 확인하지 않은 저장소를 열자마자 이 명령이 실행되면, 단순히 AI가 문서를 읽는 수준을 넘어 내 사용자 권한으로 코드가 동작할 수 있습니다. MCP 처음 연결하기에서 설명한 권한 문제도 결국 이 실행 경계와 이어집니다.

공식 문서에 따르면 Gemini CLI는 처음 보는 폴더에서 신뢰 여부를 묻기 전에 폴더 안의 확장 항목을 먼저 찾습니다. 확인창에는 Commands, MCP Servers, Hooks, Skills, Setting overrides가 표시되며, 위험한 설정이나 잘못된 구성 파일도 경고 대상으로 보여 줍니다.[1]

Gemini CLI Trusted Folders 켜기

기본값은 문서와 v0.59.0 구현이 서로 다릅니다. 공식 문서는 기본 비활성화라고 설명하지만, v0.59.0의 설정 스키마는 enabled 기본값을 true로 정의합니다.[1][3] 실제로 folderTrust 항목이 없는 깨끗한 테스트 홈에서 v0.59.0을 헤드리스로 실행했을 때도 미신뢰 폴더 오류와 함께 종료 코드 55가 나왔습니다.

따라서 v0.59.0에서는 기능이 이미 동작할 수 있습니다. 이 글의 실험은 버전이나 기존 설정에 따른 차이를 피하려고 사용자 범위 settings.json에 값을 명시했습니다.

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

일반적인 사용자 설정 경로는 다음과 같습니다.

~/.gemini/settings.json

기존 설정이 있다면 파일 전체를 덮어쓰지 말고 security.folderTrust.enabled 항목만 병합합니다. JSON 쉼표가 빠지거나 중괄호 위치가 어긋나면 Gemini CLI가 설정 오류로 시작하지 못할 수 있습니다.

설정을 저장한 뒤 처음 보는 프로젝트 폴더에서 Gemini CLI를 실행합니다.

cd ~/projects/example-repo
gemini

신뢰 확인창에는 세 가지 선택지가 나타납니다.

1. Trust folder: 현재 폴더와 그 아래 하위 경로를 신뢰
2. Trust parent folder: 부모 폴더와 그 아래 모든 하위 경로를 신뢰
3. Don’t trust: 현재 폴더를 비신뢰로 기록하고 제한 모드로 실행

Trust parent folder는 ~/projects처럼 관리가 잘 된 저장소 전용 상위 폴더에서 편리합니다. 하지만 다운로드 폴더나 홈 디렉터리를 부모로 신뢰하면 앞으로 생길 하위 폴더까지 범위에 들어갑니다. 처음에는 현재 프로젝트 폴더와 그 하위 경로만 신뢰하는 편이 판단하기 쉽습니다.[4]

선택 결과는 기본적으로 사용자 홈의 아래 파일에 저장됩니다.[1]

~/.gemini/trustedFolders.json

예를 들어 현재 테스트 폴더를 비신뢰로 지정하면 다음과 같은 규칙이 남습니다.

{
  "/tmp/gemini-trust-lab": "DO_NOT_TRUST"
}

파일의 값을 손으로 바꾸기보다 CLI의 권한 명령을 사용하는 편이 안전합니다. 경로 정규화와 부모 폴더 규칙이 함께 작동하기 때문입니다.

신뢰·비신뢰 폴더 차이

아래 표의 ‘차단’은 프로젝트가 제공한 항목을 적용하지 않는다는 뜻입니다. Gemini CLI 자체의 모든 파일 읽기와 대화를 막는다는 뜻은 아닙니다.

항목	신뢰 폴더	비신뢰 폴더
프로젝트 .gemini/settings.json	적용	무시
프로젝트 .env	로딩 가능	무시
MCP 서버	연결 시도	연결하지 않음
사용자 정의 명령	로딩	로딩하지 않음
프로젝트 Hook·Skill	로딩 가능	로딩하지 않음
도구 자동 승인	설정에 따라 가능	비활성화, 실행 전 확인
로컬 설정의 자동 메모리 로딩	설정에 따라 가능	비활성화
Extension 설치·수정	가능	제한

공식 문서는 비신뢰 폴더를 제한 모드(safe mode)로 설명합니다. 프로젝트 설정과 .env를 무시하고, MCP 서버에 연결하지 않으며, 프로젝트와 사용자 범위의 사용자 정의 명령도 로딩하지 않습니다. 전역에서 자동 승인을 켰더라도 비신뢰 폴더에서는 도구 실행 전 확인을 거칩니다.[1] Hook·Skill 행은 프로젝트가 제공한 항목을 기준으로 하며, 모든 사용자·시스템 범위 항목이 사라진다는 뜻은 아닙니다.

여기서 중요한 구분이 있습니다. Trusted Folders는 프로젝트가 CLI 동작을 확장하는 경계이고, 샌드박스는 실행된 명령이 시스템에서 어디까지 할 수 있는지 정하는 경계입니다. 폴더를 신뢰했다고 샌드박스까지 안전해지는 것은 아닙니다. 반대로 폴더를 비신뢰로 둬도 사용자가 직접 승인한 명령의 영향은 따로 검토해야 합니다. 이런 두 축의 차이는 OpenAI Codex 권한 설정: 샌드박스·승인 정책과 Full Access 차이와 같은 맥락입니다.

MCP 서버 차단 실험

Gemini CLI v0.59.0에서 프로젝트 MCP 프로세스의 실제 시작 여부를 비교합니다. 실험은 개인 설정과 인증 파일이 섞이지 않도록 /tmp 아래의 별도 홈과 테스트 폴더에서 진행합니다.

확인 환경은 다음과 같습니다.

항목	확인값
운영 환경	Linux 격리 테스트 홈
Node.js	v22.23.1
npm	10.9.8
Gemini CLI	0.59.0
테스트 프로젝트	/tmp/gemini-trust-lab
실제 사용자 홈·전역 설정	사용하지 않음

테스트 프로젝트에는 세 가지 발견 항목을 넣었습니다.

• 사용자 정의 명령 1개: trust-check
• MCP 서버 1개: trust-lab-marker
• 프로젝트 설정 재정의 1개: general

MCP 서버 명령은 시작 즉시 /tmp/gemini-trust-lab/mcp-started.log에 시간을 한 줄 남기고 종료하는 작은 Node.js 프로세스입니다. 이 테스트 로그 파일 외의 파일·네트워크·외부 서비스에는 접근하지 않습니다.

{
  "mcpServers": {
    "trust-lab-marker": {
      "command": "node",
      "args": ["/tmp/gemini-trust-lab/mcp-marker.mjs"]
    }
  }
}

처음 실행한 신뢰 확인창은 폴더 안의 항목을 다음처럼 발견했습니다.

This folder contains:
  • Commands (1):
    - trust-check
  • MCP Servers (1):
    - trust-lab-marker
  • Setting overrides (1):
    - general

이 단계가 중요한 이유는 아직 실행을 허용하기 전에 어떤 확장이 들어 있는지 먼저 볼 수 있기 때문입니다. 모르는 MCP 서버나 Hook이 보이면 바로 Trust folder를 누르지 말고 해당 설정 파일과 실행 명령부터 확인합니다.

비신뢰 폴더

Don't trust를 선택하고 새 세션을 시작하자 화면에 다음 안내가 나타났습니다.

This folder is untrusted, project settings, hooks, MCPs,
and GEMINI.md files will not be applied for this folder.
Use the /permissions command to change the trust level.

상태 영역도 workspace를 untrusted로 표시했습니다. 시작 전 지운 mcp-started.log는 세션이 열린 뒤에도 생성되지 않았습니다. 이 결과는 해당 실험에서 프로젝트의 trust-lab-marker 프로세스가 시작되지 않았다는 뜻입니다. 모든 버전과 모든 MCP 구현을 대신 증명하는 결과가 아니라, 공식 문서의 제한 동작을 v0.59.0에서 확인한 관찰입니다.

신뢰 폴더

같은 폴더를 TRUST_FOLDER로 바꾸고 새 세션을 시작하자 상태 영역에 1 MCP server가 표시됐습니다. 테스트 MCP는 의도적으로 바로 종료하므로 연결 오류 안내도 함께 나타났지만, 이번에는 mcp-started.log에 실제 시작 시각이 남았습니다.

MCP issues detected. Run /mcp list for status.
...
1 MCP server

started 2026-09-09T07:44:27.187Z

즉, 이 실험에서 비신뢰 상태에서는 MCP 시작 기록 없음 → 신뢰 후에는 시작 기록 생성이라는 차이를 확인했습니다. API 응답 단계는 일부러 유효하지 않은 테스트 키로 중단했습니다. MCP 로딩 여부만 보기 위한 실험이므로, 모델 답변 성공을 MCP 시작 증거로 섞지 않았습니다.

신뢰 수준 변경

공식 문서는 현재 폴더의 신뢰 결정을 바꿀 때 /permissions를 실행하라고 안내합니다.[1] 그러나 Gemini CLI v0.59.0에서는 /permissions만 입력하면 하위 명령이 필요하다는 메시지가 나타납니다.

Please provide a subcommand for /permissions.
Usage: /permissions trust [<directory-path>]

현재 폴더의 신뢰 설정 화면은 다음 명령으로 다시 엽니다.

/permissions trust

특정 디렉터리를 지정할 수도 있습니다.

/permissions trust /path/to/project

화면에는 현재 값과 세 가지 선택지가 다시 나타납니다.

Modify Trust Level

Folder: /tmp/gemini-trust-lab
Current Level: DO_NOT_TRUST

1. Trust this folder
2. Trust parent folder
3. Don't trust

신뢰 수준 변경을 적용하려면 Gemini CLI를 다시 시작해야 합니다. v0.59.0 화면은 r을 눌러 즉시 재시작하라고 안내합니다.[5] 또는 CLI를 종료하고 새 세션을 열 수 있습니다. 이번 실험도 새 세션에서 프로젝트 설정과 MCP 시작 기록을 확인했습니다.

trustedFolders.json 확인

전체 신뢰 규칙은 다음 파일에서 볼 수 있습니다.

cat ~/.gemini/trustedFolders.json

기본 값은 세 종류입니다.

• TRUST_FOLDER: 해당 폴더와 그 아래 경로를 신뢰
• TRUST_PARENT: 선택한 폴더의 부모를 기준으로 하위 경로를 신뢰
• DO_NOT_TRUST: 해당 경로를 비신뢰로 처리

부모의 신뢰 규칙과 더 구체적인 하위 폴더 규칙이 함께 있으면 경로 범위를 주의해서 봐야 합니다. “예전에 어디를 Trust parent로 눌렀는지”가 헷갈릴 때는 이 파일을 확인하되, 수정은 /permissions trust 화면에서 진행합니다.

신뢰 파일을 다른 위치에 두어야 하는 테스트 환경이라면 공식 문서가 안내하는 환경변수를 사용할 수 있습니다.[1]

export GEMINI_CLI_TRUSTED_FOLDERS_PATH=/absolute/path/trustedFolders.json

이 설정은 여러 실험을 분리할 때 유용하지만, 상대 경로가 아니라 절대 경로를 사용해야 합니다.

헤드리스와 CI 주의점

대화형 화면이 없는 헤드리스 실행에서는 신뢰 확인창을 띄울 수 없습니다. Trusted Folders가 켜져 있고 현재 경로가 신뢰되지 않았다면 Gemini CLI는 FatalUntrustedWorkspaceError로 종료합니다.[1]

v0.59.0의 -p 헤드리스 모드에서는 아직 결정하지 않은 폴더와 DO_NOT_TRUST로 지정한 폴더가 모두 종료 코드 55로 중단됐습니다. 다음은 미판정 폴더에서 확인한 메시지입니다.

Gemini CLI is not running in a trusted directory. To proceed,
either use `--skip-trust`, set the
`GEMINI_CLI_TRUST_WORKSPACE=true` environment variable,
or trust this directory in interactive mode.

공식 문서는 일시적으로 검사를 통과하는 두 방법을 안내합니다.[1]

gemini --skip-trust -p "테스트 실행"

GEMINI_CLI_TRUST_WORKSPACE=true gemini -p "테스트 실행"

둘 다 “저장소가 안전한지 자동으로 검사한다”는 옵션이 아닙니다. 현재 실행에서 신뢰 검사를 우회합니다. CI에서 편하다는 이유로 모든 저장소에 공통 적용하면 Trusted Folders를 켠 목적이 사라집니다.

자동화에서는 다음 순서를 권합니다.

1. 저장소 소유자와 브랜치·태그·커밋 같은 체크아웃 기준(ref)을 고정합니다.
2. .gemini/settings.json, .gemini/commands, Hook, Skill, MCP 정의를 검토합니다.
3. 외부에서 내려받은 PR 코드가 프로젝트 설정을 바꿀 수 있는지 확인합니다.
4. 별도 컨테이너나 일회용 러너에서 실행 범위를 제한합니다.
5. 검토한 저장소에서만 --skip-trust 또는 환경변수 사용을 결정합니다.
6. 실행 뒤 Git diff와 외부 변경 결과를 확인합니다.

Trusted Folders는 공급망 검토나 샌드박스를 대신하지 않습니다. v0.59.0은 신뢰 판정이 애매할 때 기능을 열어 두지 않도록 바뀌었지만, 사용자가 직접 우회 플래그를 지정하면 해당 실행의 신뢰 검사는 건너뜁니다.[1][2]

폴더 신뢰 체크리스트

안전하게 사용하는 순서

Gemini CLI Trusted Folders의 핵심은 폴더 이름에 ‘안전’ 표시를 붙이는 데 있지 않습니다. 프로젝트가 제공하는 설정과 실행 코드를 언제 로딩할지 결정하는 시작점입니다.

처음 보는 저장소에서는 발견 목록을 먼저 읽고, MCP 서버와 Hook의 실행 명령을 확인합니다. 확신이 없다면 Don't trust로 열어 구조부터 살펴볼 수 있습니다. 신뢰하기로 결정했다면 Trust folder로 현재 폴더와 그 하위 경로만 허용하고, 재시작한 세션에서 프로젝트 설정과 MCP 상태를 다시 확인합니다.

이번 v0.59.0 실험에서는 비신뢰 폴더의 프로젝트 MCP 프로세스가 시작되지 않았고, 신뢰 후에만 시작 기록이 남았습니다. 문서와 실제 버전의 명령 차이도 있었습니다. 공식 문서의 /permissions 안내와 달리 v0.59.0에서는 /permissions trust가 필요했습니다. 빠르게 바뀌는 CLI인 만큼, 버전과 화면에 표시되는 사용법을 함께 확인하는 것이 안전합니다.

Sources

[1] https://geminicli.com/docs/cli/trusted-folders — Trusted Folders | Gemini CLI [2] https://github.com/google-gemini/gemini-cli/releases/tag/v0.59.0 — Gemini CLI v0.59.0 release [3] https://github.com/google-gemini/gemini-cli/blob/v0.59.0/packages/cli/src/config/settingsSchema.ts — Gemini CLI v0.59.0 settings schema [4] https://github.com/google-gemini/gemini-cli/blob/v0.59.0/packages/core/src/utils/trust.ts — Gemini CLI v0.59.0 trust path matching [5] https://github.com/google-gemini/gemini-cli/blob/v0.59.0/packages/cli/src/ui/components/PermissionsModifyTrustDialog.tsx — Gemini CLI v0.59.0 trust restart dialog