자주 묻는 질문 (FAQ)
이 페이지에서는 Gemini CLI를 사용하는 동안 자주 발생하는 문제에 대한 해결 방법과 일반적인 질문에 대한 답변을 제공합니다.
일반적인 문제 (General issues)
API error: 429 - Resource exhausted 오류가 발생하는 이유는 무엇인가요?
이 오류는 API 요청 한도를 초과했음을 나타냅니다. Gemini API는 남용을 방지하고 공정한 사용을 보장하기 위해 속도 제한(rate limits)을 두고 있습니다.
이 문제를 해결하려면 다음을 시도해 보세요:
- 사용량 확인: Google AI Studio 또는 Google Cloud 프로젝트 대시보드에서 API 사용량을 검토하세요.
- 프롬프트 최적화: 짧은 시간 내에 많은 요청을 보내는 경우, 프롬프트를 일괄 처리하거나 요청 사이에 지연을 추가해 보세요.
- 할당량 증가 요청: 지속적으로 더 높은 한도가 필요한 경우 Google에 할당량 증가를 요청할 수 있습니다.
npm run start 실행 시 ERR_REQUIRE_ESM 오류가 발생하는 이유는 무엇인가요?
이 오류는 일반적으로 Node.js 프로젝트에서 CommonJS와 ES 모듈 간에 불일치가 있을 때 발생합니다.
이는 종종 package.json 또는 tsconfig.json의 구성 오류로 인해 발생합니다. 다음 사항을 확인하세요:
package.json에"type": "module"이 포함되어 있는지 확인합니다.tsconfig.json의compilerOptions에"module": "NodeNext"또는 호환되는 설정이 있는지 확인합니다.
문제가 지속되면 node_modules 디렉터리와 package-lock.json 파일을 삭제한 후 npm install을 다시 실행해 보세요.
stats 출력에서 캐시된 토큰 수가 보이지 않는 이유는 무엇인가요?
캐시된 토큰 정보는 캐시된 토큰이 실제로 사용되고 있을 때만 표시됩니다. 이 기능은 API 키 사용자(Gemini API 키 또는 Google Cloud Vertex AI)에게 제공되지만, OAuth 사용자(Google Gmail과 같은 구글 개인 계정 또는 Google Workspace와 같은 엔터프라이즈 계정)에게는 제공되지 않습니다. 이는 Gemini Code Assist API가 캐시된 콘텐츠 생성을 지원하지 않기 때문입니다. Gemini CLI에서 /stats 명령을 사용하여 총 토큰 사용량은 계속 확인할 수 있습니다.
설치 및 업데이트 (Installation and updates)
Gemini CLI를 최신 버전으로 업데이트하려면 어떻게 하나요?
npm을 통해 전역으로 설치한 경우 다음 명령을 사용하여 업데이트하세요:
npm install -g @google/gemini-cli@latest소스에서 컴파일한 경우 리포지토리에서 최신 변경 사항을 가져온(pull) 후 npm run build 명령을 사용하여 다시 빌드하세요.
플랫폼별 문제 (Platform-specific issues)
chmod +x와 같은 명령을 실행할 때 Windows에서 CLI가 종료되는 이유는 무엇인가요?
chmod와 같은 명령은 Unix 계열 운영 체제(Linux, macOS)에만 해당합니다. Windows에서는 기본적으로 사용할 수 없습니다.
이 문제를 해결하려면 다음을 시도해 보세요:
- Windows 해당 명령 사용: Windows에서 파일 권한을 수정하려면
chmod대신icacls를 사용할 수 있습니다. - 호환성 레이어 사용: Git Bash 또는 Linux용 Windows 하위 시스템(WSL)과 같은 도구는 이러한 명령이 작동하는 Unix와 유사한 환경을 Windows에서 제공합니다.
구성 (Configuration)
GOOGLE_CLOUD_PROJECT는 어떻게 구성하나요?
환경 변수를 사용하여 Google Cloud 프로젝트 ID를 구성할 수 있습니다.
셸에서 GOOGLE_CLOUD_PROJECT 환경 변수를 설정하세요:
export GOOGLE_CLOUD_PROJECT="your-project-id"이 설정을 영구적으로 유지하려면 셸의 시작 파일(예: ~/.bashrc, ~/.zshrc)에 이 줄을 추가하세요.
API 키를 안전하게 저장하는 가장 좋은 방법은 무엇인가요?
스크립트에 API 키를 노출하거나 소스 제어에 커밋하는 것은 보안 위험이 있습니다.
API 키를 안전하게 저장하려면 다음을 시도해 보세요:
.env파일 사용: 프로젝트의.gemini디렉터리에.env파일(.gemini/.env)을 생성하고 키를 저장하세요. Gemini CLI는 자동으로 이 변수들을 로드합니다.- 시스템 키링 사용: 가장 안전한 저장을 위해 운영 체제의 비밀 관리 도구(macOS Keychain, Windows 자격 증명 관리자 또는 Linux의 secrets manager)를 사용하세요. 그런 다음 스크립트나 환경이 런타임에 보안 저장소에서 키를 로드하도록 설정할 수 있습니다.
Gemini CLI 구성 및 설정 파일은 어디에 저장되나요?
Gemini CLI 구성은 두 곳의 settings.json 파일에 저장됩니다:
- 홈 디렉터리:
~/.gemini/settings.json - 프로젝트 루트 디렉터리:
./.gemini/settings.json
자세한 내용은 Gemini CLI 구성을 참조하세요.
Google AI Pro/Ultra 및 구독 FAQ
Google AI Pro 또는 Google AI Ultra 구독에 대한 자세한 내용은 어디에서 확인할 수 있나요?
Google AI Pro 또는 Google AI Ultra 구독에 대해 자세히 알아보려면 구독 설정 (opens in a new tab)의 구독 관리를 방문하세요.
Google AI Pro 또는 Ultra에 대한 더 높은 한도가 적용되었는지 어떻게 알 수 있나요?
Google AI Pro 또는 Ultra를 구독하는 경우 Gemini Code Assist 및 Gemini CLI에 대해 자동으로 더 높은 한도가 적용됩니다. 이는 Gemini CLI와 IDE의 에이전트 모드 간에 공유됩니다. 구독 설정 (opens in a new tab)에서 Google AI Pro 또는 Ultra를 여전히 구독 중인지 확인하여 더 높은 한도가 적용되는지 확인할 수 있습니다.
Google AI Pro 또는 Ultra를 구독한 경우 Gemini Code Assist 또는 Gemini CLI 사용에 대한 개인정보처리방침은 무엇인가요?
구독에 적용되는 개인정보처리방침 및 서비스 약관에 대해 자세히 알아보려면 Gemini Code Assist: 서비스 약관 및 개인정보처리방침 공지 (opens in a new tab)를 방문하세요.
Google AI Pro 또는 Ultra로 업그레이드했지만 여전히 할당량 한도에 도달했다는 메시지가 나타납니다. 버그인가요?
Google AI Pro 또는 Ultra 구독의 더 높은 한도는 Gemini 2.5 Pro 및 Flash 모두를 포함한 Gemini 2.5에 적용됩니다. 이는 Gemini CLI와 Gemini Code Assist IDE 확장의 에이전트 모드 간에 공유되는 할당량입니다. Gemini CLI, Gemini Code Assist 및 Gemini Code Assist의 에이전트 모드에 대한 할당량 한도에 대한 자세한 내용은 할당량 및 한도 (opens in a new tab)에서 확인할 수 있습니다.
Google AI Pro 또는 Ultra 구독을 구매하여 Gemini CLI 및 Gemini Code Assist에 대한 더 높은 한도로 업그레이드하면 Gemini가 내 데이터를 사용하여 머신러닝 모델을 개선하기 시작하나요?
유료 요금제를 구매하면 Google은 Google의 머신러닝 모델을 개선하기 위해 귀하의 데이터를 사용하지 않습니다. 참고: 무료 버전인 개인용 Gemini Code Assist를 계속 사용하는 경우에도 Google의 머신러닝 모델을 개선하기 위해 데이터를 사용하지 않도록 선택(opt out)할 수 있습니다. 자세한 내용은 개인용 Gemini Code Assist 개인정보처리방침 공지 (opens in a new tab)를 참조하세요.
질문이 보이지 않나요?
GitHub의 Gemini CLI Q&A 토론 (opens in a new tab)을 검색하거나 GitHub에서 새로운 토론을 시작 (opens in a new tab)하세요.