Gemini CLI

Gemini CLI는 Google의 오픈 소스 터미널 에이전트로, 터미널에서 프로젝트를 이해하고 파일을 분석하며 승인을 받은 뒤 명령과 도구를 사용할 수 있습니다. Gemini API 주소, API Key 및 모델 ID를 설정하면 AGTCloud의 Gemini Generate Content 호환 진입점을 사용할 수 있습니다.

이 튜토리얼은 Gemini CLI의 기본 연결 및 안전한 검증 과정만 설명합니다. 파일 수정, Shell 명령, 함수 호출 및 기타 에이전트 기능은 대상 모델과 해당 모델의 Gemini Parts, Function Call 등의 프로토콜 구조에 대한 실제 지원 여부에 따라 달라집니다.

준비 사항

시작하기 전에 다음 사항을 확인합니다.

• Node.js 20 이상을 설치합니다.
• Bash, Zsh 또는 PowerShell 터미널을 준비합니다.
• API Keys 페이지에서 AGTCloud API Key를 생성합니다.
• 모델 목록에서 현재 Key에 표시되며 Gemini Generate Content를 지원하는 모델 ID를 복사합니다.
• 민감한 코드와 운영 자격 증명이 없는 테스트 디렉터리를 준비합니다.

MODEL_ID는 교체해야 하는 자리표시자이며 실제 모델 이름이 아닙니다. 현재 API Key에 표시되며 Gemini Generate Content를 지원하는 모델 ID를 사용합니다.

Gemini CLI 설치

현재 안정 버전을 설치하는 것이 좋습니다. 설치 방식과 관계없이 같은 gemini 명령을 사용합니다.

npm install -g @google/gemini-cli

설치 후 버전을 확인합니다.

gemini --version

명령을 찾을 수 없다고 표시되면 터미널을 다시 열고 npm 전역 명령 디렉터리가 PATH에 추가되어 있는지 확인합니다.

AGTCloud 설정

Gemini CLI에는 API Key, 모델 ID, 사용자 정의 Gemini API 주소 및 Bearer 인증 방식의 네 가지 환경 변수가 필요합니다.

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

설정 항목 설명

이 튜토리얼은 GOOGLE_GENAI_API_VERSION을 설정하지 않고 Gemini CLI가 Gemini API의 기본 v1beta를 사용하도록 합니다. 전체 generateContent 요청 경로도 Base URL에 기록하지 않습니다.

사용자 수준 설정 저장

임시 설정이 작동하는지 확인한 뒤 Gemini CLI의 사용자 수준 .env 파일에 변수를 기록할 수 있습니다. 실제 API Key가 포함될 수 있으므로 이 파일을 코드 저장소에 커밋하지 않습니다.

~/.gemini/.env

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI는 현재 작업 디렉터리와 상위 디렉터리에서 환경 파일을 찾습니다. 프로젝트에 더 가까운 .env 또는 .gemini/.env가 사용자 수준 설정보다 우선할 수 있으므로 설정이 적용되지 않으면 이 파일들을 먼저 검사합니다.

API Key 인증 방식 고정

Gemini CLI는 여러 Google 인증 방식을 지원합니다. AGTCloud를 통해 사용할 때는 Google 로그인 또는 Vertex AI가 아닌 Gemini API Key를 선택합니다.

사용자 수준 settings.json에 다음 설정을 병합하고 파일의 기존 테마, 권한 또는 기타 설정을 덮어쓰지 않습니다.

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

설정 파일 위치입니다.

저장한 뒤 Gemini CLI를 완전히 종료하고 다시 시작합니다. selectedType은 API Key 인증 흐름을 선택하고 GEMINI_API_KEY_AUTH_MECHANISM=bearer는 AGTCloud 요구에 맞는 Bearer Header를 생성하며 서로 대체할 수 없습니다.

모델 선택

기본 모델은 GEMINI_MODEL로 결정합니다. 단일 세션에서 모델을 임시 지정하려면 다음을 실행할 수 있습니다.

gemini --model MODEL_ID

대화형 세션의 /model은 보조 진입점으로 사용할 수 있지만 현재 AGTCloud API Key가 반환하는 모든 모델을 자동으로 포함하지 않을 수 있습니다. 모델이 없거나 표시되지 않으면 모델 목록에서 전체 모델 ID를 다시 복사하고 우선 GEMINI_MODEL 또는 --model로 지정합니다.

연결 검증

gemini -p "AGTCloud 연결 성공이라고만 응답해 주세요." --output-format json

gemini -p "@README.md 프로젝트의 용도를 세 가지로 요약하고 어떤 파일도 수정하지 마세요." --output-format json

gemini

자주 묻는 질문

원인을 찾기 어려우면 요청 시각, API Base URL, 모델 ID, Gemini CLI 버전, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록하고 오류 및 문제 해결을 확인합니다. 전체 API Key 또는 자격 증명이 포함된 .env 파일을 제출하지 않습니다.

보안 권장 사항

• 실제 API Key를 저장소, 공유 스크립트, 스크린샷, 로그 또는 채팅 기록에 기록하지 않습니다.
• 임시 환경 변수로 먼저 검증하고 성공한 뒤 사용자 수준 설정을 저장하는 것이 좋습니다.
• .env 파일에 적절한 로컬 접근 권한을 설정하고 공개 클라우드 드라이브로 동기화하지 않습니다.
• 처음 도구 기능을 사용할 때는 수동 승인을 유지하고 비운영 프로젝트에서 검증합니다.
• 문제 해결 정보를 공유하기 전에 전체 Key, 사용자 이름, 로컬 경로 및 업무 소스 코드를 제거합니다.

다음 단계

• API Key, Base URL 및 인증
• Gemini Generate Content API Reference
• Gemini Stream Generate Content API Reference
• 프로토콜 선택
• 오류 및 문제 해결