개발자 리소스

Gemini CLI

Gemini CLI를 RunAPI의 Gemini 네이티브 API로 설정하고, 요청을 확인한 뒤 이전 설정을 복원하세요.

개요

Gemini CLI는 터미널 에이전트입니다. 이 안내는 모델 제공자를 RunAPI의 Gemini 네이티브 API로 변경합니다. MCP를 통한 RunAPI 도구 추가는 별도 단계입니다.

시작하기 전에

공식 설치 안내를 따르세요. 인증 안내에 따라 전용 표준 API 키를 만들고 모델 카탈로그에서 Gemini 네이티브 모델 ID를 복사하세요. 키를 커밋하지 마세요.

SHELL

npm install -g @google/gemini-cli

RunAPI 구성

현재 셸에서 이 변수들을 설정하세요. 기본 URL은 /v1beta가 없는 HTTPS API 루트이며 SDK가 POST /v1beta/models/{model}:streamGenerateContent?alt=sse를 추가합니다. HTTP는 localhost에서만 허용됩니다.

SHELL

export GOOGLE_GEMINI_BASE_URL=https://runapi.ai
export GEMINI_API_KEY=YOUR_RUNAPI_API_KEY
export GEMINI_MODEL=YOUR_RUNAPI_MODEL_ID

계속 사용하려면 저장소 밖의 ~/.gemini/.env에 같은 세 변수를 저장하세요. chmod 600 ~/.gemini/.env으로 접근을 제한하세요. Gemini CLI는 현재 디렉터리에서 상위 디렉터리 방향으로 .env를 찾은 뒤 ~/.gemini/.env와 ~/.env를 확인합니다. 충돌하는 파일을 점검하세요.

다른 설정을 유지하면서 이 두 설정을 ~/.gemini/settings.json에 병합하세요. API 키 인증에는 gemini-api-key를 사용하고 캐시된 Google 로그인을 재사용하지 마세요. 키는 기본적으로 x-goog-api-key로 전송됩니다.

JSON

{
  "security": {
    "auth": {"selectedType": "gemini-api-key"}
  },
  "model": {"name": "YOUR_RUNAPI_MODEL_ID"}
}

모델 선택

대화형 세션에서 GEMINI_MODEL, --model YOUR_RUNAPI_MODEL_ID 또는 /model를 사용하세요. auto, pro, flash는 피하세요. 이 별칭들은 RunAPI에서 제공하지 않는 Google 모델 ID로 변환될 수 있습니다. 내부 선택, 분류 및 루프 감지도 flash 또는 flash-lite 보조 모델을 요청할 수 있으므로 가용성을 별도로 확인하세요.

확인

신뢰하는 저장소에서 실행하세요. 대화형 세션에서 /about 또는 /stats로 모델을 확인하고 RunAPI 사용 기록에서 해당 streamGenerateContent 요청을 확인하세요. CLI의 성공 응답만으로 어떤 엔드포인트가 요청을 받았는지 증명할 수는 없습니다.

SHELL

gemini --version
gemini -p "Describe this repository in one sentence."

RunAPI 도구 추가

MCP는 모델 제공자가 아닌 도구를 추가합니다. 이 명령은 로컬 서버를 등록합니다. 별도 인증과 검증은 Local MCP를 따르세요.

SHELL

gemini mcp add runapi npx -y @runapi.ai/mcp

문제 해결

요청이 여전히 Google로 향한다면 충돌하는 .env 파일, security.auth.selectedType, 캐시된 로그인과 Google/Vertex 인증 환경 변수를 확인하세요. Invalid auth method selected가 표시되면 설정에서 gateway 대신 gemini-api-key를 선택하고 다시 시작하세요.

401 오류라면 키와 GEMINI_API_KEY_AUTH_MECHANISM 재정의 설정을 확인하세요. 기본값은 x-goog-api-key입니다. 404 오류라면 기본 URL에서 /v1beta를 제거하고 지원되는 Gemini 네이티브 모델 ID를 다시 복사하세요. 보조 모델을 사용할 수 없다면 요청된 정확한 ID를 확인하세요. 주 모델을 선택했다고 모든 CLI 기능이 작동하는 것은 아닙니다.

RunAPI는 countTokens 또는 embedContent를 제공하지 않습니다. countTokens 실패 시 Gemini CLI는 로컬 토큰 추정으로 전환할 수 있으며 추정치는 사용 기록과 다를 수 있습니다. localhost를 제외하고 HTTPS를 사용하며 인증서 검증을 끄지 마세요.

RunAPI 제거

셸과 저장된 .env 파일에서 세 변수를 제거하고 이전 security.auth.selectedType 및 모델 설정을 복원한 뒤 RunAPI에서 전용 키를 폐기하세요. 별도로 추가한 MCP 서버는 도구가 더 이상 필요 없을 때만 제거하세요.

SHELL

unset GOOGLE_GEMINI_BASE_URL GEMINI_API_KEY GEMINI_MODEL

다음 단계

LLM API 빠른 시작, Gemini generateContent, streamGenerateContent, 모델 카탈로그 또는 Local MCP를 확인하세요.