Gemini CLI settings.json: 네 파일이 겹칠 때 어느 값이 이기나

Gemini CLI의 settings.json이 어떤 순서로 겹치는지 보려고, 사용자 파일과 프로젝트 파일에 MCP 서버를 하나씩 적고 gemini mcp list를 돌렸습니다. 아무 신뢰 설정 없이 실행하니 목록 위에 경고가 먼저 뜨더라고요. 이 폴더는 신뢰되지 않았으니 MCP 서버를 꺼 둔다는 것, 그리고 사용자 범위 서버까지 같이 꺼진다는 내용이었어요.

눈여겨볼 건 신뢰를 끄는 값입니다. 사용자 파일에 security.folderTrust.enabled를 false로 적으니 경고가 사라졌는데, 같은 값을 프로젝트 파일에만 적었을 때는 경고가 그대로 남았습니다.

우선순위로만 따지면 프로젝트 파일이 사용자 파일을 이겨야 하는데 말이죠. 신뢰받지 못한 폴더에서는 프로젝트 파일이 아예 읽히지 않기 때문입니다.

그래서 저는 이렇게 나눠 씁니다. 개인 설정과 신뢰 설정은 ~/.gemini/settings.json에, 팀과 나눌 설정은 프로젝트의 .gemini/settings.json에 둡니다.

같은 키가 겹치면 시스템 기본값 → 사용자 → 프로젝트 → 시스템 덮어쓰기 순으로 뒤 파일이 이기고, 명령줄 플래그와 환경 변수는 네 파일을 모두 이깁니다. 다만 배열은 이어 붙고 mcpServers는 이름 단위로 합쳐져요.

시작하기 전에 계정부터 확인하세요. 2026년 6월 18일부터 Gemini CLI는 무료로 쓰는 사용자와 Google AI Pro·Ultra 구독자의 요청을 처리하지 않습니다(메인테이너 Dmitry Lyalin, 2026년 5월 19일 공식 저장소 토론 글).

조직이 Gemini Code Assist Standard·Enterprise 라이선스나 Google Cloud로 쓰는 경우, 유료 Gemini API 키와 Gemini Enterprise Agent Platform API 키는 계속 쓸 수 있고, 이 글의 우선순위 설명도 그대로 적용됩니다.

개인 무료·AI Pro·Ultra 계정이라면 Windows에서 Antigravity CLI(agy)를 설치하고 Gemini CLI 설정·GEMINI.md를 옮기는 순서부터 보세요.

2026년 9월 27일 Ubuntu 24.04 · Gemini CLI 0.61.0(npm) 테스트 환경에서 직접 확인했고, 저장소의 v0.61.0 태그 문서를 같은 날 맞춰 봤습니다.

네 파일과 읽는 순서

사용자 파일과 프로젝트 파일 위아래로 시스템 파일이 하나씩 있습니다. 아래쪽 system-defaults.json은 누구나 덮을 수 있는 바닥이고, 위쪽 시스템 settings.json은 다른 세 파일이 덮을 수 없는 천장이에요.

순서	범위	Linux	Windows
1	시스템 기본값	/etc/gemini-cli/system-defaults.json	C:\ProgramData\gemini-cli\system-defaults.json
2	사용자	~/.gemini/settings.json	%USERPROFILE%\.gemini\settings.json
3	프로젝트	<프로젝트>/.gemini/settings.json	같음
4	시스템 덮어쓰기	/etc/gemini-cli/settings.json	C:\ProgramData\gemini-cli\settings.json

macOS의 시스템 파일은 /Library/Application Support/GeminiCli/ 아래 같은 이름입니다. 두 시스템 파일의 위치는 환경 변수 GEMINI_CLI_SYSTEM_DEFAULTS_PATH와 GEMINI_CLI_SYSTEM_SETTINGS_PATH로 바꿀 수 있어요. 시스템 파일은 보통 관리자가 조직 단위로 까는 자리입니다.

전체 우선순위는 일곱 단계입니다. 내장 기본값, 위 네 파일, 환경 변수, 명령줄 인자 순으로 뒤가 앞을 덮어요. 그러니 네 파일을 다 맞춰도 명령줄 플래그와 환경 변수가 마지막에 이깁니다. 설정과 같은 것을 가리키는 대표 플래그는 -m·--model(모델), -s·--sandbox(샌드박스), --approval-mode(승인 방식), --include-directories(작업 공간에 더할 폴더)입니다.

혼자 쓰는 설정이라면 사용자 파일 하나에 다 적어도 됩니다. 하지만 저장소마다 다른 MCP 서버나 작업 공간 폴더처럼 팀이 함께 써야 하는 값은 프로젝트 파일에 두고 커밋해야 모두에게 같은 결과가 나와요. 토큰처럼 사람마다 다른 값은 파일에 적지 말고 ${VAR_NAME}으로 환경 변수를 참조하게 두면 프로젝트 파일을 커밋해도 괜찮습니다.

인증 설정은 사용자 파일에 둡니다. 인증 없이 실행하면 0.61.0도 Please set an Auth method in your ~/.gemini/settings.json or specify one of the following environment variables before running: GEMINI_API_KEY, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA로 사용자 파일을 가리키거든요.

인증 오류는 Gemini CLI 인증 오류를 종료 코드로 가르는 글에서, 지시 파일 GEMINI.md를 어디에 두면 읽히는지는 Gemini CLI 컨텍스트 파일의 계층에서 따로 다뤘습니다.

키는 ui.theme처럼 묶음 아래에 넣는 중첩 구조로 적습니다. 이 구조는 v0.3.0에서 새로 들어왔으니, 오래된 글에서 옮겨 온 예제는 모양이 다를 수 있어요. 문자열 값 안에서는 $VAR_NAME, ${VAR_NAME}, ${VAR_NAME:-DEFAULT_VALUE}로 환경 변수를 불러 쓸 수 있습니다(gemini-extension.json도 같습니다).

덮이는 값, 합쳐지는 값

“뒤 파일이 이긴다”는 단일 값에만 그대로 맞습니다. 배열과 객체는 덮이지 않고 합쳐져요.

• 단일 값(ui.theme 등): 가장 높은 파일의 값 하나만 남습니다.
• 배열(context.includeDirectories): 시스템 기본값 → 사용자 → 프로젝트 → 시스템 덮어쓰기 순서로 네 파일의 항목이 이어 붙어 배열 하나가 됩니다. 위 파일의 배열이 아래 파일을 지우지 않습니다.
• 객체(mcpServers): 모든 파일의 서버가 한 목록으로 합쳐집니다. 이름이 같은 서버만 시스템 > 프로젝트 > 사용자 순으로 높은 쪽 정의가 쓰입니다.

마지막 규칙 덕분에 관리자가 시스템 파일에 정의한 서버를 사용자가 자기 파일로 바꿔치기할 수는 없고, 이름이 다른 서버를 더하는 것만 됩니다.

같은 이름의 서버를 겹쳐 보니

0.61.0에서 파일을 하나씩 얹어 가며 gemini mcp list로 합쳐진 결과를 봤습니다. 이 명령은 로그인 없이 돌고 합쳐진 뒤의 서버 이름과 명령을 보여 주니까, 자기 설정도 같은 방법으로 확인할 수 있어요.

사용자 파일과 프로젝트 파일에 shared라는 같은 이름을 하나씩 적고, 각자만의 서버도 하나씩 넣었습니다.

// ~/.gemini/settings.json
{ "mcpServers": { "shared": { "command": "user-level-command" }, "user-only": { "command": "user-tool" } } }

// <프로젝트>/.gemini/settings.json
{ "mcpServers": { "shared": { "command": "project-level-command" }, "project-only": { "command": "project-tool" } } }

gemini mcp list

Configured MCP servers:

✗ shared: project-level-command  (stdio) - Disconnected
✗ user-only: user-tool  (stdio) - Disconnected
✗ project-only: project-tool  (stdio) - Disconnected

명령은 실제로 없는 자리표시자라 Disconnected로 나오지만, shared가 어느 파일의 정의로 굳었는지는 그대로 보입니다. 시스템 파일까지 얹은 결과를 모으면 이렇습니다.

얹은 파일	shared가 가리킨 값	함께 남은 서버
사용자 + 프로젝트	프로젝트 쪽	user-only, project-only
사용자 + 프로젝트 + 시스템 덮어쓰기	시스템 쪽	user-only, project-only
시스템 기본값 + 사용자	사용자 쪽	defaults-only, user-only

이름이 겹친 서버는 높은 파일이 이겼고, 겹치지 않은 서버는 모두 살아남았습니다. 시스템 기본값은 아무도 그 이름을 적지 않았을 때만 쓰였고요. 문서의 설명과 같은 결과였어요.

설정 전체를 한 번에 보고 싶다면 대화형 화면의 /settings 편집기를 쓰면 됩니다. 파일을 직접 고치는 것과 같지만 검증과 안내가 붙어요. mcpServers처럼 전용 목록 명령이 있는 항목은 위처럼 gemini mcp list가 더 빠릅니다.

이 비교는 폴더 신뢰 경고가 나오지 않는 상태에서 한 것입니다. 경고가 나오면 목록이 Disabled로 바뀌어 비교가 되지 않거든요.

신뢰하지 않은 폴더에서는 프로젝트 파일이 빠진다

신뢰하지 않은 폴더에서는 프로젝트의 .gemini/settings.json을 아예 읽지 않습니다. 우선순위가 낮아지는 게 아니라 빠지는 거예요. 대화형 승인을 받을 수 없는 환경이라면 CLI가 FatalUntrustedWorkspaceError로 끝나며, --skip-trust 플래그나 GEMINI_CLI_TRUST_WORKSPACE=true 환경 변수로 넘어갈 수 있습니다.

글 처음에 말한 경고가 이겁니다. 신뢰 설정을 따로 하지 않고 같은 명령을 실행했을 때 나온 화면이에요.

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

Configured MCP servers:

○ shared: project-level-command  (stdio) - Disabled
○ user-only: user-tool  (stdio) - Disabled
○ project-only: project-tool  (stdio) - Disabled

목록에는 프로젝트 파일에만 있는 project-only까지 나오고 표시만 Disabled입니다. 관리 명령이 화면에 보여 주는 목록과 실제 세션이 적용하는 설정은 별개라서, 신뢰 상태에 따라 목록을 잘못 읽기 쉬워요.

경고 두 번째 줄처럼 사용자 범위 서버도 함께 꺼진다는 점도 눈여겨보세요. 사용자 파일에 적은 값이 어떤 프로젝트에서만 사라졌는데 프로젝트 파일에 같은 키가 없다면, 이 신뢰 상태부터 의심하면 됩니다.

헷갈리는 건 기본값입니다. 문서끼리 다르거든요.

설정 레퍼런스는 security.folderTrust.enabled의 기본값을 true로 적고, 폴더 신뢰 문서는 첫 문장에서 이 기능이 기본으로 꺼져 있다고 하면서 쓰려면 사용자 파일에 켜는 값을 넣으라고 안내합니다.

어느 쪽이 맞는지는 문서만으로 정해지지 않아요. 직접 확인한 사실은 이렇습니다.

• 아무 설정 없이 0.61.0을 실행하면 위 경고가 나왔습니다.
• 사용자 파일에 security.folderTrust.enabled를 false로 적자 경고가 사라졌습니다.
• 같은 값을 프로젝트 파일에만 적었을 때는 경고가 그대로 나왔습니다.

주의: 신뢰를 다루는 값은 신뢰 여부에 따라 읽힐지가 갈리는 프로젝트 파일이 아니라 사용자 파일에 두세요.

막혔던 오류들

Expected double-quoted property name in JSON at position …

어떤 명령도 실행되지 않고 아래 두 줄만 나옵니다. gemini --version조차 버전을 찍지 못해요.

Error in <프로젝트 경로>/.gemini/settings.json: Expected double-quoted property name in JSON at position 129 (line 6 column 1)
Please fix the configuration file(s) and try again.

그 파일의 JSON 문법 오류입니다. 직접 해 보니 마지막 항목 뒤에 쉼표를 하나 더 둔 것이 이 메시지를 냈습니다.

위치 숫자는 파일마다 다르니, 메시지가 알려 주는 파일과 줄·칸을 고치면 됩니다. // 주석은 0.61.0에서 문제가 되지 않았어요.

Warning: MCP servers are configured but disabled because this folder is untrusted.

서버 이름은 보이는데 전부 Disabled이고, 사용자 파일에 적은 서버까지 꺼지는 경우입니다. 현재 폴더가 신뢰되지 않아서 프로젝트 파일이 적용되지 않고 사용자 범위 서버도 함께 억제된 상태예요.

대화형 화면의 /permissions로 그 폴더를 신뢰하거나, 자동화라면 --skip-trust 또는 GEMINI_CLI_TRUST_WORKSPACE=true로 그 실행만 통과시키세요. 프로젝트 파일에만 신뢰 설정을 적는 것은 해결이 되지 않습니다.

Security Warning: Skipping system settings file …: Parent directory … is insecure

시스템 설정 파일을 가리켰는데 값이 하나도 반영되지 않고 이 경고가 나옵니다.

Security Warning: Skipping system settings file '<시스템 설정 경로>/settings.json': Parent directory '/tmp' is insecure: Directory '/tmp' is writable by group or others (mode: 41777). To fix this, run: sudo chmod g-w,o-w "/tmp"

시스템 설정 파일이 그룹이나 다른 사용자가 쓸 수 있는 폴더(이 경우 /tmp) 아래에 있으면 그 파일을 건너뜁니다. 위 세 문서에서는 이 검사의 설명을 찾지 못했고, 실행 중 나온 메시지로만 확인했어요.

경고가 안내하는 대로 상위 폴더의 쓰기 권한을 좁히거나, 아무나 쓸 수 없는 경로에 파일을 두면 됩니다. 경로를 바꿀 수 없다면 그 값을 사용자 파일로 옮기세요.

다른 사람들이 겪은 문제

각 보고가 밝힌 사실만 옮겼습니다.

• 신뢰하지 않은 폴더에서 gemini mcp add: lets-order-some-fries(2026-09-23, #29465)는 신뢰하지 않은 폴더에서 이 명령을 실행하면 프로젝트의 .gemini/settings.json이 방금 쓴 키만 남기고 지워지는데도 성공으로 보고된다고 적었습니다. 재현 버전은 0.60.0과 main의 d5b3e3acc이고, GEMINI_CLI_TRUST_WORKSPACE=true를 붙인 실행에서는 기존 값이 보존됐다고 밝혔습니다.
• 사용자 범위만 로드됨: fetchhacknslack-cmyk(2026-02-23, #19984)는 0.29.5에서 사용자·프로젝트 양쪽에 MCP 서버를 적었는데 사용자 쪽만 로드됐고, 이름 충돌은 없었다고 보고했습니다. 원인은 적혀 있지 않습니다. 0.61.0 확인에서는 양쪽이 모두 로드됐습니다.
• 우선순위 설계 지적: shicks(2025-08-18, #6517)는 시스템 설정이 관리자용 잠금에는 맞지만 사용자가 덮을 수 있는 기본값을 까는 데는 쓸 수 없다며, 시스템 설정 파일이 둘이어야 두 용도를 다 지원할 수 있다고 지적했습니다. v0.61.0 문서에는 시스템 파일이 기본값용과 덮어쓰기용 둘로 나뉘어 있지만, 그 변경이 이 이슈 때문인지는 적혀 있지 않습니다.
• type 키 검증 오류: Morriz(2026-01-11, #16359)는 사용자 파일의 mcpServers.teleclaude 안 type 키 때문에 Unrecognized key(s) in object: 'type'가 뜨며 CLI가 시작되지 않았다고 보고했습니다. CLI 버전은 적혀 있지 않습니다. 같은 모양을 0.61.0 프로젝트 파일에 넣어 보니 오류 없이 목록이 나왔습니다.

네 건 가운데 “어느 파일이 이기느냐”를 정면으로 다룬 건 설계 지적 한 건뿐이고, 나머지는 폴더 신뢰·키 검증이거나 원인이 적혀 있지 않았습니다. 그래서 저는 값이 안 먹히면 우선순위표보다 폴더 신뢰와 파일 파싱을 먼저 봅니다.

마치며

settings.json 우선순위는 표 한 장으로 외울 수 있지만, 실제로 값을 사라지게 만드는 건 순서보다 폴더 신뢰였습니다. 값 하나가 안 먹힌다면 명령줄 플래그와 환경 변수를 먼저 빼고 실행해 보고, 폴더 신뢰 경고가 뜨는지 본 다음, 시스템 덮어쓰기 → 프로젝트 → 사용자 파일 순으로 위에서부터 보세요.

Antigravity CLI로 옮겼다면 이 규칙은 그대로 가져가지 않습니다. Antigravity CLI는 설정을 ~/.gemini/antigravity-cli/settings.json에, MCP 서버를 mcp_config.json에 따로 두고, 이 글의 네 파일 순서는 Gemini CLI에만 해당해요.

MCP 서버가 목록에는 보이는데 연결되지 않는다면 우선순위가 아니라 연결 문제이니 MCP 서버가 안 붙을 때 점검 순서로 이어 가세요.