Gemini CLI settings.json 설정 방법을 먼저 정리하면, 개인 취향에 가까운 값은 전역 설정에 두고, 특정 프로젝트에서만 필요한 값은 프로젝트 설정에 두는 편이 가장 깔끔합니다. 그리고 처음에는 모든 옵션을 다 건드리기보다 기본 모델, 디렉터리 포함 범위, MCP 연결 정보처럼 자주 반복해서 바꾸는 것부터 정리하는 편이 좋습니다.
Gemini CLI를 계속 쓰다 보면 매번 같은 옵션을 다시 맞추는 것이 생각보다 번거롭게 느껴집니다. 어떤 모델을 기본으로 쓸지, 어떤 문서나 라이브러리를 함께 읽게 할지, 어떤 외부 도구를 붙일지처럼 반복되는 설정이 생기기 때문입니다. 그래서 settings.json은 단순한 옵션 파일이 아니라, 같은 환경을 계속 다시 맞춰야 하는 피로를 줄여주는 기준점에 가깝습니다.
Table of Contents
Gemini CLI settings.json 설정 방법 한눈에 정리
settings.json은 어디에 두는가
공식 저장소와 문서 흐름 기준으로 Gemini CLI는 사용자 설정 파일과 프로젝트 설정 파일을 나눠서 가져갈 수 있습니다. 보통 전역 설정은 ~/.gemini/settings.json 같은 위치에서 관리하고, 프로젝트에 묶이는 값은 작업 폴더 안의 .gemini/settings.json으로 나누는 흐름을 씁니다.
이 구조를 이해하면 설정이 많아져도 덜 헷갈립니다. 개인 취향에 가까운 값은 전역에 두고, 팀과 공유해야 하는 값은 프로젝트 쪽에 두면 되기 때문입니다. 처음에는 이 구분만 잘 잡아도 이후 관리가 훨씬 편해집니다.
처음에 가장 자주 건드리게 되는 설정은 무엇인가
실제로 많이 바꾸게 되는 항목은 어느 정도 정해져 있습니다. 처음에는 아래 항목부터 눈에 들어오는 경우가 많습니다.
- 기본 모델
- 컨텍스트 파일 또는 디렉터리 포함 범위
- MCP 서버 연결 정보
- 기타 동작 옵션과 체크포인트 관련 설정
중요한 점은 모든 항목을 다 알기 전부터 설정 파일을 과하게 키우지 않는 것입니다. 내가 실제로 반복해서 바꾸는 값이 무엇인지부터 보는 편이 훨씬 현실적입니다.
기본 모델 설정은 왜 먼저 정리하는 편이 좋은가
공식 저장소에는 명령행에서 -m 옵션으로 모델을 바꾸는 예시가 나오고, 설정 파일 관련 이슈와 문서 흐름에서도 기본 모델 구성 이야기가 반복해서 등장합니다. 즉 자주 같은 모델을 쓴다면, 매번 명령에서 다시 지정하는 것보다 settings.json에서 기본값을 정리해두는 편이 훨씬 편합니다.
다만 설정만 넣어두고 끝내기보다, 실제로 원하는 모델이 반영되는지 한 번 확인하는 편이 좋습니다. 버전 차이나 우선순위 문제 때문에 생각과 다르게 동작하는 경우도 있기 때문입니다.
이럴 때 기본 모델 설정이 특히 체감된다
- 항상 같은 모델로 시작할 때
- 매번 긴 명령어를 다시 치기 싫을 때
- 프로젝트별로 다른 기본값이 필요할 때
includeDirectories 같은 컨텍스트 설정은 언제 쓰나
현재 작업 폴더 밖의 문서나 공용 라이브러리를 함께 읽어야 할 때는 컨텍스트에 디렉터리를 포함하는 흐름이 필요할 수 있습니다. 공식 저장소 이슈에서도 이 부분은 자주 언급됩니다. 특히 실제 프로젝트에서는 코드만 보는 것이 아니라 문서와 공유 라이브러리까지 같이 봐야 하는 경우가 많기 때문에, 이 설정의 체감이 꽤 큽니다.
예를 들어 공용 라이브러리나 문서 디렉터리를 같이 읽게 하고 싶다면, 매번 커맨드 옵션으로 넘기기보다 프로젝트 설정에서 관리하는 편이 더 안정적입니다. 그래야 같은 저장소를 다시 열었을 때도 흐름이 덜 흔들립니다.
이럴 때는 프로젝트 설정 쪽이 더 잘 맞는다
- 특정 저장소에서만 필요한 디렉터리가 있을 때
- 팀이 같은 문서/라이브러리를 같이 보게 해야 할 때
- 개인 전역 설정에 프로젝트 규칙을 섞고 싶지 않을 때
MCP 서버도 settings.json에서 같이 관리한다
Gemini CLI는 MCP 서버를 통해 기능을 확장할 수 있고, 공식 저장소 README에도 ~/.gemini/settings.json에 MCP 서버를 설정하는 흐름이 나옵니다. 따라서 GitHub, Slack, 데이터베이스 같은 외부 도구를 붙일 계획이라면, settings.json 구조를 이해하는 것이 먼저입니다.
이 부분은 처음부터 한꺼번에 많이 붙이기보다 하나씩 추가하는 편이 낫습니다. 외부 도구는 인증, 서버 실행, 설정 경로가 한 번에 얽히는 경우가 많아서, 어디가 문제인지 추적하기 어려워질 수 있기 때문입니다.
처음에는 어떤 순서로 정리하면 덜 헷갈릴까
- 전역 설정과 프로젝트 설정의 역할을 먼저 구분하기
- 기본 모델처럼 자주 바꾸는 값부터 정하기
- 필요한 디렉터리 포함 범위를 확인하기
- MCP 연결은 하나씩만 추가하기
이 순서로 가면 설정이 많아져도 어디서 문제가 났는지 다시 좁히기가 수월합니다. 처음부터 모든 옵션을 완성하려고 하면 오히려 흐름이 더 복잡해집니다.
자주 헷갈리는 부분
설정 파일에 넣었는데 반영이 안 되는 것처럼 보일 때
버전 차이나 우선순위 문제일 수 있습니다. 설정만 넣어두고 끝내지 말고, 실제로 명령을 실행해서 원하는 값이 반영되는지 확인하는 편이 좋습니다.
전역 설정과 프로젝트 설정을 같이 쓰면 더 헷갈리지 않나
처음에는 헷갈릴 수 있습니다. 하지만 개인 취향과 프로젝트 규칙을 분리할 수 있다는 장점이 더 큽니다. 오히려 둘을 한 파일에 다 넣어두면 나중에 더 복잡해질 수 있습니다.
함께 보면 좋은 글
정리하면, Gemini CLI settings.json 설정 방법의 핵심은 옵션을 많이 아는 것이 아니라 반복해서 바꾸는 설정을 어디에 두면 덜 번거로운지를 먼저 이해하는 데 있습니다. 전역 설정과 프로젝트 설정을 구분하고, 기본 모델, 디렉터리 포함 범위, MCP 연결처럼 실제로 자주 건드리는 항목부터 정리하면 사용감이 훨씬 안정됩니다.