구글 제미니

Hermes Agent는 OpenAI 호환 엔드포인트가 아닌 Google AI Studio/Gemini API를 사용하여 Google Gemini를 기본 제공자로 지원합니다. 이를 통해 Hermes는 도구 호출, 스트리밍, 다중 모달 입력 및 Gemini 관련 응답 메타데이터를 보존하면서 내부 OpenAI 형태의 메시지 및 도구 루프를 Gemini의 기본 generateContent API로 변환할 수 있습니다.

Hermes는 Google의 Gemini CLI와 동일한 Cloud Code Assist 백엔드를 사용하는 별도의 Google Gemini(OAuth) 제공자도 지원합니다. 위험이 가장 낮은 공식 API 경로에는 API 키 제공자(gemini)를 사용하세요.

전제 조건

• Google AI Studio API 키 — aistudio.google.com/apikey에서 생성하세요.
• 결제 지원 Google Cloud 프로젝트 — 에이전트 사용에 권장됩니다. Gemini의 무료 계층은 Hermes가 사용자 차례마다 여러 모델 호출을 할 수 있기 때문에 장기 실행 에이전트 세션에 비해 너무 작습니다.
• Hermes 설치 — 기본 Gemini 제공자에는 추가 Python 패키지가 필요하지 않습니다.

API key path

GOOGLE_API_KEY 또는 GEMINI_API_KEY을 설정합니다. Hermes는 gemini 제공자의 두 이름을 모두 확인합니다.

빠른 시작

# Add your Gemini API key
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# Select Gemini as your provider
hermes model
# → Choose "More providers..." → "Google AI Studio"
# → Hermes checks your key tier and shows Gemini models
# → Select a model

# Start chatting
hermes chat

직접 구성 편집을 선호하는 경우 기본 Gemini API 기본 URL을 사용하세요.

model:
  default: gemini-3-flash-preview
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

구성

hermes model을 실행하면 ~/.hermes/config.yaml에 다음이 포함됩니다.

model:
  default: gemini-3-flash-preview
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

그리고 ~/.hermes/.env에서는:

GOOGLE_API_KEY=...

네이티브 Gemini API

권장되는 엔드포인트는 다음과 같습니다.

https://generativelanguage.googleapis.com/v1beta

Hermes는 이 엔드포인트를 감지하고 기본 Gemini 어댑터를 생성합니다. 내부적으로 Hermes는 여전히 OpenAI 모양의 메시지에 에이전트 루프를 유지한 다음 각 요청을 Gemini의 기본 스키마로 변환합니다.

• messages → 쌍둥이자리 contents
• 시스템 프롬프트 → Gemini systemInstruction
• 도구 스키마 → Gemini functionDeclarations
• 도구 결과 → Gemini functionResponse 부품
• 스트리밍 응답 → Hermes 루프용 OpenAI 모양의 스트림 청크

Gemini 3 thought signatures

Gemini 3 도구 사용의 경우 Hermes는 함수 호출 부분에 연결된 thoughtSignature 값을 유지하고 다음 도구 회전에서 이를 재생합니다. 이는 다단계 에이전트 워크플로의 검증에 중요한 경로를 다룹니다.

Gemini 3는 또한 다른 응답 부분에 생각 서명을 첨부할 수도 있습니다. Hermes의 기본 어댑터는 현재 에이전트 도구 루프에 최적화되어 있으므로 아직 도구 호출이 아닌 모든 서명을 완전한 부분 수준 충실도로 재생하지는 않습니다.

네이티브 엔드포인트를 선호하세요

Google은 또한 OpenAI 호환 엔드포인트를 공개합니다.

https://generativelanguage.googleapis.com/v1beta/openai/

Hermes 에이전트 세션의 경우 위의 기본 Gemini 엔드포인트를 선호하세요. Hermes에는 기본 Gemini 어댑터가 포함되어 있어 다중 회전 도구 사용, 도구 호출 결과, 스트리밍, 다중 모드 입력 및 Gemini 응답 메타데이터를 Gemini의 generateContent API에 직접 매핑할 수 있습니다. OpenAI 호환 엔드포인트는 특별히 OpenAI API 호환성이 필요할 때 여전히 유용합니다.

이전에 GEMINI_BASE_URL을 /openai URL로 설정한 경우 이를 제거하거나 변경하세요.

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

OAuth 제공자

Hermes에는 google-gemini-cli 제공자도 있습니다.

hermes model
# → Choose "Google Gemini (OAuth)"

이는 브라우저 PKCE 로그인 및 Cloud Code Assist 백엔드를 사용합니다. Gemini CLI 스타일 OAuth를 원하는 사용자에게 유용할 수 있지만 Google이 타사 소프트웨어의 Gemini CLI OAuth 클라이언트 사용을 정책 위반으로 처리할 수 있으므로 Hermes에서는 명시적인 경고를 표시합니다. 프로덕션 또는 위험도가 가장 낮은 사용을 위해서는 위의 API 키 제공자를 선호하세요.

사용 가능한 모델

hermes model 선택기는 Hermes의 제공자 레지스트리에서 유지 관리되는 Gemini 모델을 보여줍니다. 일반적인 선택 사항은 다음과 같습니다.

모델	ID	메모
Gemini 3.1 Pro 미리보기	gemini-3.1-pro-preview	가능한 경우 가장 유능한 미리보기 모델
Gemini 3 Pro 미리보기	gemini-3-pro-preview	강력한 추론 및 코딩 모델
Gemini 3 플래시 미리보기	gemini-3-flash-preview	속도와 기능의 권장 기본 균형
Gemini 3.1 Flash Lite 미리보기	gemini-3.1-flash-lite-preview	가능한 경우 가장 빠르고 가장 저렴한 옵션

모델 가용성은 시간이 지남에 따라 변경됩니다. 모델이 사라지거나 키에 대해 활성화되지 않은 경우 hermes model을 다시 실행하고 현재 목록에서 하나를 선택하세요.

Model IDs

provider: gemini인 경우 google/gemini-3-flash-preview과 같은 OpenRouter 스타일 ID가 아닌 gemini-3-flash-preview과 같은 Gemini의 기본 모델 ID를 사용하세요.

최신 별칭

Google은 Pro 및 Flash Gemini 제품군에 대한 이동 별칭을 게시합니다. gemini-pro-latest 및 gemini-flash-latest은 Hermes 구성을 변경하지 않고 Google이 자동으로 모델을 발전시키도록 할 때 유용합니다.

별칭	현재 트랙	메모
gemini-pro-latest	최신 Gemini Pro 모델	Google의 현재 Pro 기본값을 원할 때 가장 좋습니다.
gemini-flash-latest	최신 Gemini 플래시 모델	Google의 현재 Flash 기본값을 원할 때 가장 좋습니다.

model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

엄격한 재현성이 필요한 경우 gemini-3.1-pro-preview 또는 gemini-3-flash-preview과 같은 명시적인 모델 ID를 선호합니다.

Gemini API를 통한 Gemma

Google은 또한 Gemini API를 통해 Gemma 모델을 공개합니다. Hermes는 이를 Google 모델로 인식하지만 처리량이 매우 낮은 Gemma 항목을 기본 모델 선택기에서 숨겨 신규 사용자가 실수로 장기 실행 에이전트 세션에 대한 평가 계층 모델을 선택하지 않도록 합니다.

유용한 평가 ID는 다음과 같습니다.

모델	ID	메모
젬마 4 IT	gemma-4-31b-it	더 큰 Gemma 모델; 호환성 및 품질 평가에 유용
젬마 4 IT	gemma-4-26b-a4b-it	가능한 경우 더 작은 활성 매개변수 변형

이러한 모델은 Gemini API 키에 대한 평가 옵션으로 가장 잘 처리됩니다. Google의 Gemma API 가격은 무료 등급으로만 제공되며 프로덕션 Gemini 모델에 비해 사용 한도가 낮습니다. 따라서 지속적인 Hermes 에이전트 사용은 일반적으로 유료 Gemini 모델, 자체 호스팅 배포 또는 적절한 할당량이 있는 다른 제공업체로 이동해야 합니다.

선택기에서 숨겨진 Gemma 모델을 사용하려면 직접 설정하세요.

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

세션 중간에 모델 전환

대화 중에 /model 명령을 사용하세요.

/model gemini-3-flash-preview
/model gemini-flash-latest
/model gemini-3-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

아직 Gemini를 구성하지 않은 경우 세션을 종료하고 hermes model을 먼저 실행하세요. /model 이미 구성된 제공자와 모델 간을 전환합니다. 새 API 키를 수집하지 않습니다.

진단

hermes doctor

의사는 다음을 확인합니다.

• GOOGLE_API_KEY 또는 GEMINI_API_KEY 사용 가능 여부
• google-gemini-cli에 대한 Gemini OAuth 자격 증명이 존재하는지 여부
• 구성된 제공자 자격 증명을 확인할 수 있는지 여부

OAuth 할당량을 사용하려면 Hermes 세션 내에서 다음을 실행하세요.

/gquota
``/gquota`은 AI Studio API 키 제공자가 아닌 `google-gemini-cli` OAuth 제공자에 적용됩니다.

## 게이트웨이(메시징 플랫폼) \{#gateway-messaging-platforms}

Gemini는 모든 Hermes 게이트웨이 플랫폼(Telegram, Discord, Slack, WhatsApp, LINE, Feishu 등)과 작동합니다. Gemini를 공급자로 구성한 후 정상적으로 게이트웨이를 시작합니다.

```bash
hermes gateway setup
hermes gateway start

게이트웨이는 config.yaml을 읽고 동일한 Gemini 공급자 구성을 사용합니다.

문제 해결

"Gemini 기본 클라이언트에는 API 키가 필요합니다"

헤르메스가 사용 가능한 API 키를 찾을 수 없습니다. ~/.hermes/.env에 다음 중 하나를 추가하세요.

GOOGLE_API_KEY=...
# or
GEMINI_API_KEY=...

그런 다음 hermes model을 다시 실행하세요.

"이 Google API 키는 무료 등급에 있습니다."

Hermes는 설정 중에 Gemini API 키를 조사합니다. 도구 사용, 재시도, 압축 및 보조 작업에는 여러 모델 호출이 필요할 수 있으므로 무료 계층 할당량은 몇 번의 에이전트 전환 후에 소진될 수 있습니다.

키에 연결된 Google Cloud 프로젝트에서 결제를 사용 설정하고 필요한 경우 키를 다시 생성한 후 다음을 실행하세요.

hermes model

"404 모델을 찾을 수 없습니다"

선택한 모델은 귀하의 계정, 지역 또는 키에 사용할 수 없습니다. hermes model을 다시 실행하고 현재 목록에서 다른 Gemini 모델을 선택하세요.

Gemma 모델은 hermes model에 표시되지 않습니다.

Hermes는 기본적으로 선택기에서 처리량이 낮은 Gemma 모델을 숨길 수 있습니다. 의도적으로 평가하려는 경우 ~/.hermes/config.yaml에서 모델 ID를 직접 설정하세요.

Gemma에서 "429 할당량 초과"

Gemini API를 통해 노출된 Gemma 모델은 평가에 유용하지만 Gemini API 무료 계층 한도가 낮습니다. 호환성 테스트에 사용한 다음 유료 Gemini 모델이나 지속적인 에이전트 세션을 위한 다른 제공업체로 전환하세요.

OpenAI 호환 엔드포인트가 구성되었습니다.

~/.hermes/.env에서 다음을 확인하세요.

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

기본 엔드포인트로 변경하거나 재정의를 제거합니다.

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

OAuth 로그인 경고

google-gemini-cli 공급자는 Gemini CLI/Cloud Code Assist OAuth 흐름을 사용합니다. Hermes는 공식 AI Studio API 키 경로와 다르기 때문에 시작하기 전에 경고합니다. 공식 API 키 통합을 위해 provider: gemini을 GOOGLE_API_KEY과 함께 사용하세요.

스키마 오류로 인해 도구 호출이 실패함

Hermes를 업그레이드하고 hermes model을 다시 실행하세요. 기본 Gemini 어댑터는 Gemini의 보다 엄격한 함수 선언 형식에 대한 도구 스키마를 삭제합니다. 이전 빌드나 사용자 지정 엔드포인트는 그렇지 않을 수 있습니다.

관련

• AI 제공업체
• 구성
• 대체 공급자
• AWS Bedrock — AWS 자격 증명을 사용한 기본 클라우드 공급자 통합