Gemini CLI settings.json 위치와 우선순위 확인
Gemini CLI 가 settings.json 을 어디서 읽는지, 사용자·프로젝트·시스템 파일이 어떤 순서로 덮어쓰는지 mcpServers 로 확인하고 프로젝트 설정이 무시되는 경우를 짚습니다.
프로젝트의 .gemini/settings.json 을 고쳤는데 반영되지 않거나, 사용자 설정과 값이 섞여 보일 때 어느 파일이 이기는지 확인합니다.
[1] 버전을 확인합니다. 설정 키와 동작은 버전마다 달라질 수 있어, 아래는 이 버전 기준입니다.
$ gemini --version0.64.0[2] 파일 위치와 순서를 봅니다. 설치된 패키지에 문서가 들어 있고(공식 문서와 같은 내용), 아래 번호가 클수록 앞 번호를 덮어씁니다.
| 순서 | 파일 | 위치 (Linux) |
|---|---|---|
| 1 | 기본값 | 프로그램 내부 |
| 2 | 시스템 기본 | /etc/gemini-cli/system-defaults.json |
| 3 | 사용자 | ~/.gemini/settings.json |
| 4 | 프로젝트 | <프로젝트>/.gemini/settings.json |
| 5 | 시스템 덮어쓰기 | /etc/gemini-cli/settings.json |
| 6 | 환경 변수 | 셸·.env |
| 7 | 명령행 옵션 | gemini -m … 등 |
2번과 5번 경로는 GEMINI_CLI_SYSTEM_DEFAULTS_PATH · GEMINI_CLI_SYSTEM_SETTINGS_PATH 환경 변수로 바꿀 수 있습니다. 시스템 덮어쓰기(5번)는 프로젝트 설정보다도 강해서, 관리자가 정한 값은 프로젝트에서 되돌릴 수 없습니다.
[3] 같은 이름의 MCP 서버를 사용자·프로젝트 파일에 하나씩 둡니다. gemini mcp list 는 로그인 없이 병합된 목록을 보여 주므로 확인용으로 편합니다.
{ "mcpServers": { "shared": { "command": "echo", "args": ["user"], "env": { "A": "1" } }, "user-only": { "command": "echo" } }}{ "mcpServers": { "shared": { "command": "printf" }, "proj-only": { "command": "ls" } }}[4] /srv/app 에서 목록을 봅니다.
$ cd /srv/app$ gemini mcp listConfigured MCP servers: ✗ shared: printf (stdio) - Disconnected✗ user-only: echo (stdio) - Disconnected✗ proj-only: ls (stdio) - DisconnectedmcpServers 는 서버 이름 단위로 합쳐집니다. 세 서버가 모두 보이고, 이름이 겹친 shared 는 프로젝트 쪽 정의가 이겼습니다. 사용자 쪽의 args 와 env 는 남지 않았습니다. 서버 정의 안쪽까지 섞이지 않고 통째로 바뀝니다. (Disconnected 는 시험용 명령이 MCP 서버가 아니라서입니다.)
[5] 배열은 설정마다 다릅니다. 설치된 번들의 설정 정의를 보면 다음과 같이 나뉩니다.
| 병합 방식 | 설정 |
|---|---|
concat (이어 붙임) | context.includeDirectories · hooks 아래의 이벤트별 목록(BeforeTool 등) |
union (중복 없이 합침) | context.fileFiltering.customIgnoreFilePaths · tools.exclude · 비활성 확장·스킬 목록 등 |
replace (덮어씀) | 위에 없는 나머지 |
공식 엔터프라이즈 문서에도 「includeDirectories 는 System Defaults → User → Workspace → System Overrides 순으로 이어 붙는다」고 적혀 있습니다. 배열 합침은 이 시험에서 화면으로 확인하지 못했고 문서와 소스 정의 기준입니다.
[6] 프로젝트 설정이 통째로 무시되는 경우를 봅니다. 폴더를 신뢰하지 않으면 .gemini/settings.json 을 읽지 않습니다. 이 버전은 security.folderTrust.enabled 기본값이 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.신뢰는 대화형 화면에서 폴더를 고르면 ~/.gemini/trustedFolders.json 에 저장됩니다. 이 시험에서는 그 파일에 {"/srv/app":"TRUST_FOLDER"} 를 직접 써서 넘어갔고, 비대화형(CI)에서는 --skip-trust 또는 GEMINI_CLI_TRUST_WORKSPACE=true 를 씁니다(신뢰 폴더 문서).
[7] JSON 문법 오류는 시작 단계에서 파일 경로와 함께 나옵니다.
Error in /srv/app/.gemini/settings.json: Expected property name or '}' in JSON at position 16 (line 2 column 1)Please fix the configuration file(s) and try again.[8] 컨텍스트 파일 이름 키는 settings.json 안에서 context.fileName 입니다(문자열 또는 배열).
{ "context": { "fileName": ["GEMINI.md", "CONTEXT.md"] }}contextFileName 은 확장(gemini-extension.json)의 키입니다. 설정 파일에 contextFileName 이라고 쓴 글을 따라 하면 이 버전 문서에는 없는 키라 쓸모가 없습니다. 메모리 파일이 읽히지 않는 문제는 GEMINI.md 가 로드되지 않을 때를 봅니다.