2026-04-25 Gemini → Ollama Cloud gemma4:31b 전환 트러블슈팅

환경: 맥미니 M4 Pro / 메인컴 WSL2 / 보조컴 WSL2 작업일: 2026-04-25 최종 결과: ✅ 3대 전부 Ollama Cloud gemma4:31b 구동

에러 1: unknown provider ‘ollama’

에러 메시지:

WARNING agent.auxiliary_client: resolve_provider_client: unknown provider 'ollama'

시도 방법:

hermes config set model.provider ollama 로 설정
YAML 직접 수정으로 provider를 ollama로 변경

해결 방법:

Hermes는 ollama 프로바이더를 내장 지원하지 않음
provider: custom 으로 설정 + base_url 직접 지정

hermes config set model.provider custom
hermes config set model.base_url https://ollama.com/v1

에러 2: context window below minimum 64,000

에러 메시지:

ValueError: Model gemma4:31b has a context window of 8,192 tokens, which is below the minimum 64,000 required by Hermes Agent. Choose a model with at least 64K context, or set model.context_length in config.yaml to override.

시도 방법:

YAML 직접 수정으로 context_length 추가 → python yaml이 키 순서 재배치하여 설정 꼬임

해결 방법:

hermes config set model.context_length 128000

⚠️ Ollama Cloud가 자동 감지하는 컨텍스트 크기가 8K로 잘못 보고됨. 반드시 수동 override 필요.

에러 3: gemma4:31b is not a valid model ID (OpenRouter)

에러 메시지:

❌ Non-retryable client error (HTTP 400): HTTP 400: gemma4:31b is not a valid model ID
🔌 Provider: openrouter  Model: gemma4:31b

시도 방법:

provider: openrouter + model.default: gemma4:31b 설정
OpenRouter 모델명 형식(google/gemma-4-31b-it)으로 변경

해결 방법:

OpenRouter 모델명은 google/gemma-4-31b-it 형식이어야 함
하지만 OpenRouter는 유료 크레딧 필요 → HTTP 402 에러 발생
최종: provider: custom + base_url: https://ollama.com/v1 로 Ollama Cloud 직접 연결

에러 4: HTTP 402 크레딧 부족 (OpenRouter)

에러 메시지:

❌ Rate limited after 3 retries — HTTP 402: This request requires more credits, or fewer max_tokens. You requested up to 65536 tokens, but can only afford 48185. To increase, visit https://openrouter.ai/settings/credits

시도 방법:

OpenRouter로 gemma4:31b 대체 시도

해결 방법:

OpenRouter 무료 플랜 한도 초과
Ollama Cloud (ollama.com) 직접 사용으로 전환

에러 5: No LLM provider configured / unauthorized

에러 메시지:

RuntimeError: No LLM provider configured. Run hermes model to select a provider.
ERROR root: Non-retryable client error: unauthorized

시도 방법:

hermes config set model.api_key OLLAMA_API_KEY 설정
환경변수 참조를 의도했으나 Hermes가 문자열 그대로 인식

해결 방법:

api_key에는 실제 키 값을 직접 입력해야 함

hermes config set model.api_key '7e3ed4aab2bb432ca913793658de4b89.xxxxx'

.env에도 OLLAMA_API_KEY=실제키값 추가
둘 다 설정해야 안전

에러 6: YAML 직접 수정으로 설정 꼬임

에러 메시지:

python yaml.dump가 키 알파벳순 재배치
루키(맥미니) config까지 오염
systemd start request repeated too quickly

시도 방법:

python yaml로 config.yaml 직접 읽기/쓰기

해결 방법:

절대 YAML 직접 수정 금지 — 반드시 hermes config set 사용
systemd rate limit 걸리면 systemctl --user reset-failed 후 재시작

systemctl --user reset-failed hermes-gateway
hermes gateway start

최종 정상 설정 명령어 (전체)

# 1. 모델 설정
hermes config set model.provider custom
hermes config set model.base_url https://ollama.com/v1
hermes config set model.default gemma4:31b
hermes config set model.api_key '실제_OLLAMA_CLOUD_API_키'
hermes config set model.context_length 128000

# 2. .env에도 키 추가
echo 'OLLAMA_API_KEY=실제_OLLAMA_CLOUD_API_키' >> ~/.hermes/.env
echo 'OLLAMA_BASE_URL=https://ollama.com/v1' >> ~/.hermes/.env

# 3. 게이트웨이 재시작
hermes gateway restart

핵심 교훈 요약

#	교훈	상세
1	`hermes config set`만 사용	YAML 직접 수정 금지. 키 순서 꼬임, 오염 위험
2	Ollama Cloud = `provider: custom`	`ollama`는 Hermes가 인식 못함
3	api_key는 실제 값 입력	환경변수명 문자열 그대로 넣으면 안 됨
4	context_length 수동 설정 필수	gemma4:31b이 8K로 잘못 보고됨
5	로컬 작업 시 타 기기 config 주의	SSH 명령이 로컬 파일을 건드릴 수 있음
6	systemd rate limit 대응	`reset-failed` 후 `start`

[!note] 수정이력 | 2026-04-25 08:37, 미미 (openclaw 2026.4.22)