Gemini CLI를 계속 쓰다 보면, 매번 같은 옵션을 다시 맞추는 것이 번거롭게 느껴질 때가 있습니다. 어떤 모델을 기본으로 쓸지, 어떤 디렉터리를 더 포함할지, 어떤 컨텍스트 파일을 읽게 할지처럼 자주 반복되는 부분은 설정 파일에서 미리 정리하는 편이 훨씬 편합니다.
이 글은 Gemini CLI settings.json 설정 방법을 처음 보는 기준으로 정리한 글입니다. 설정 파일이 어디에 있는지, 어떤 종류의 항목을 넣을 수 있는지, 처음에는 무엇부터 손보면 좋은지 순서대로 설명합니다.
Table of Contents
settings.json은 어디에 두나
공식 저장소와 문서 흐름 기준으로 Gemini CLI는 ~/.gemini/settings.json 같은 사용자 설정 파일과, 프로젝트 안의 .gemini/settings.json 흐름을 사용합니다. 즉 전역 설정과 프로젝트 설정을 나눠서 가져갈 수 있다는 뜻입니다.
개인 취향에 가까운 값은 전역 설정에 두고, 프로젝트에 묶여야 하는 값은 프로젝트 폴더 안에 두는 편이 자연스럽습니다.
처음에 가장 자주 건드리게 되는 설정
- 기본 모델
- 컨텍스트 파일 또는 디렉터리 포함 범위
- MCP 서버 연결 정보
- 체크포인팅이나 기타 동작 옵션
처음에는 모든 값을 다 만지기보다, 내가 실제로 반복해서 바꾸는 값이 무엇인지부터 보는 편이 좋습니다.
모델 설정은 왜 중요한가
공식 저장소에는 명령행에서 -m 옵션으로 모델을 바꾸는 예시가 나오고, 설정 파일 관련 이슈와 문서 흐름에서도 기본 모델 구성 이야기가 계속 나옵니다. 즉 자주 같은 모델을 쓴다면 매번 명령으로 넘기기보다 설정 파일에서 기본값을 잡아두는 편이 편합니다.
다만 실제 버전에 따라 동작 차이가 있었던 이슈도 있었기 때문에, 설정만 믿기보다 한 번 실제로 원하는 모델이 적용되는지 확인하는 편이 좋습니다.
includeDirectories 같은 컨텍스트 설정은 언제 쓰나
현재 작업 폴더 밖의 문서나 라이브러리를 함께 봐야 할 때는 컨텍스트에 추가 디렉터리를 포함하는 흐름이 필요할 수 있습니다. 공식 저장소 이슈에서도 이 부분이 자주 언급됩니다.
예를 들어 공용 라이브러리나 문서 디렉터리를 같이 읽게 하고 싶다면, 매번 커맨드 옵션으로 넘기기보다 프로젝트 설정에서 관리하는 편이 더 안정적입니다.
MCP 서버도 settings.json에서 관리한다
Gemini CLI는 MCP 서버를 통해 기능을 확장할 수 있고, 공식 저장소 README에도 ~/.gemini/settings.json에 MCP 서버를 설정하는 흐름이 나옵니다. 따라서 GitHub, Slack, 데이터베이스 같은 외부 도구를 붙일 계획이라면 설정 파일 구조를 이해하는 것이 먼저입니다.
처음에는 이렇게 정리하면 덜 헷갈린다
- 전역 설정과 프로젝트 설정을 구분하기
- 기본 모델처럼 자주 바꾸는 값부터 설정하기
- 필요한 디렉터리 포함 여부를 확인하기
- MCP 연결은 하나씩만 추가하기
이 순서로 가면 설정이 많아져도 어디서 문제가 났는지 추적하기가 수월합니다.
자주 헷갈리는 부분
설정 파일에 넣었는데 반영이 안 되는 것 같아요
버전 차이나 우선순위 문제일 수 있습니다. 따라서 바꾼 뒤에는 실제 명령으로 한 번 확인하는 편이 좋습니다.
전역 설정과 프로젝트 설정을 같이 쓰면 헷갈리지 않나요?
처음에는 헷갈릴 수 있지만, 개인 취향과 프로젝트 규칙을 분리할 수 있다는 장점이 더 큽니다.
함께 보면 좋은 글
정리
Gemini CLI settings.json은 단순한 옵션 저장소가 아니라, 반복해서 같은 환경을 맞춰야 하는 불편을 줄여주는 기준점에 가깝습니다. 처음에는 기본 모델, 디렉터리 포함 범위, MCP 연결처럼 실제로 자주 건드리는 것부터 정리하는 편이 가장 현실적입니다.
참고한 공식 문서
- Google Gemini CLI GitHub repository
- Gemini CLI 관련 공식 이슈/문서 흐름