Gemma 같은 무료 모델로 Hermes 연결 안 된다면 이것부터 확인하세요 — .env 파일 한 줄이 범인이었다.

로컬 AI 환경 구축 시 필수 확인 사항: .env 파일 설정

한줄 요약

유료 AI API 없이 내 PC에서 완전 무료 AI 에이전트를 돌리려다 8번의 에러를 만났고, Gemini AI와 함께 근본 원인을 파헤쳐 결국 성공했습니다.

바쁘시면 이것만 읽어도 돼요:

• LM Studio + Hermes AI Agent + Gemma 4로 완전 무료 로컬 AI 환경 구축

• 핵심 문제: .env 파일에서 LM_BASE_URL 대신 OPENAI_API_BASE를 써야 함

• LM Studio는 OpenAI 호환 서버 — Gemma든 Llama든 무조건 OpenAI 프로토콜로 접근해야 함

• Gemma 4가 Google 모델이라 Hermes가 자동으로 Google 계열 설정을 붙여버린 것이 함정

• 에러 메시지가 바뀌면 오히려 진전 중이라는 신호 — 포기하지 말 것

이런 분들께 도움돼요

• LM Studio는 설치했는데 Hermes, Open WebUI 등 AI 에이전트 연결에서 막히고 있는 분

• OpenAI, Claude 같은 유료 API 없이 로컬 무료 AI 환경을 구축하고 싶은 분

• Connection error, WinError 10054, invalid_api_key 같은 에러를 보고 계신 분

문제 상황 (Before)

매달 나가는 AI 구독료가 부담됐다. Claude, GPT 같은 유료 서비스를 쓰다 보면 금방 한도가 차고, 그렇다고 무제한 플랜은 너무 비쌉니다. 올라가는 내 연봉보다 ai월세가 더오르는 이 현실!!!!그래서 필요하게 되었습니다.

그러던 중 알게 된 조합이 바로 LM Studio + Hermes AI Agent + Gemma 4. LM Studio는 오픈소스 AI 모델을 내 컴퓨터에서 직접 돌릴 수 있는 도구고, Hermes는 그 위에서 돌아가는 AI 에이전트 프레임워크입니다. *Gemma 4는 Google이 공개한 최신 무료 오픈소스 AI 모델.

이 세 가지를 연결하면 완전 무료로 내 PC에서 AI 에이전트를 돌릴 수 있다는 것!!!!

설치까지는 순조로웠습니다 저는 기존 오픈클로에 코덱스와 클로드를 사용해서 맥미니에서 이사갔던 경험이 있어 놀고있는 데스크탑에 설치는 순조로웠습니다. LM Studio에서 Gemma 4 E4B 양자화 모델을 올리고, Hermes도 설치했습니다. 그런데 연결하려는 순간부터 에러가 터지기 시작한 것입니다..!!!!!!!

Open optionsauto

APIConnectionError — Connection error.
Max retries (3) exhausted
💀 Final error: Connection error.

사용한 도구

• 로컬 AI 런타임: LM Studio (로컬 AI 모델 실행 도구)

• AI 모델: Google Gemma 4 E4B (오픈소스 무료 모델)

• AI 에이전트 프레임워크: Hermes AI Agent

• 트러블슈팅 도우미: Gemini AI

• 운영체제: Windows 11

작업 과정

에러 1단계 — "서버에 닿지도 못한다"

처음 마주한 에러는 단순했다. Hermes가 LM Studio 서버 자체에 연결을 못 하는 상황이었다.

Open optionsauto

GET /version → Unexpected endpoint or method. Returning 200 anyway
Connection error. Max retries (3) exhausted

Gemini AI에 에러 로그를 그대로 붙여넣었습니다. Gemini는 LM Studio 서버가 실행 중인지, 모델이 로드되어 있는지, 포트 1234가 다른 프로그램과 충돌하지 않는지를 순서대로 확인하라고 했으며 그리고 엔드포인트 경로에 /v1을 붙여야 할 수도 있다고 알려주었습니다. 하지만 엔드포인트 역시 정확하게 한거 같은데 뭐지? 한 상황이었습니다.

에러 2단계 — "PowerShell이 리눅스가 아니야"

LM Studio 서버가 살아있는지 확인하려고 curl 테스트를 시도하기로 했습니다. 결과론적으로 curl테스트는 문제없었습니다만!! 처음 접하시는분들이 리눅스와 윈도파워쉘 차이를 모르면 헤멜만한 에러가 있어 해당내용을 첨부하게 되었습니다.

Open optionsauto

curl http://localhost:1234/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{...}'
→ Invoke-WebRequest : '\' 인수를 허용하는 위치 매개 변수를 찾을 수 없습니다.

Windows PowerShell에서 curl은 사실 Invoke-WebRequest라는 다른 명령어의 별칭이고 리눅스의 \ 줄 바꿈이 여기서는 통하지 않습니다. 따라서 해당내용을 llm에 명확히 하지 않는다면 할루시네이션이 나올수 있기때문에 내용을 추가했습니다.

또한 PowerShell에서 줄 바꿈은 `(역틱)을 써야 합니다.

에러 3~5단계 — "연결은 됐다 → 근데 또 끊긴다"

curl을 확인하고 다시 시도해보니 이번엔 다른 에러들이 쏟아졌다.

• WinError 10054 원격 호스트에 의한 강제 종료 → 모델 메모리 과부하 의심

• HTTP 400 Bad Request → 요청 형식 불일치

에러가 바뀔 때마다 Gemini에게 로그를 보여주면서 하나씩 좁혀가도록 했습니다. 특히 인상적이었던 건 API 인증 에러가 떴을 때 Gemini가 한 말이었는데!!!!

"이 에러는 오히려 좋은 신호입니다. 통신 경로 자체는 연결됐다는 뜻이에요."

에러가 바뀐다는 것 자체가 진전이라는 관점이 새로우면서도 아 뭐지?? 잘해놨는데 아 뭐냐????ㅋㅋㅋ

진짜 범인 발견 — "Gemma 4는 Google 모델이었다"

LM Studio 로그를 자세히 보다가 결정적인 힌트를 발견했습니다.

Open optionsauto

[ERROR] Unexpected endpoint or method. (POST /api/show). Returning 200 anyway
[INFO] Returning 2 models from v1 API

Hermes가 /api/show라는 경로로 요청을 보내고 있었습니다.

Gemini는 이게 Hermes의 lmstudio 전용 드라이버가 작동하면서 LM Studio 독자 규격 명령을 보내는 것이라고 설명했는데 이거때문에 api가 뭐가 문제가 있는거 같아 .env 파일을 보여달라고 했습니다.

.env 파일의 맨 아래를 확인했습니다.

Open optionsauto

LM_API_KEY=
LM_BASE_URL=http://127.0.0.1:1234/v1

여기서 의구심이 생겼습니다. "아니 일단 키랑 URL은 잘된거 같은데 왜이러지???" 그래서 직접 .env 를 열어보았더니

ALT

항목 목록을 보여주는 컴퓨터 화면의 스크린샷

아.... 이거 뭐냐.......

Hermes에서 Gemma 4를 설정할 때, 모델 이름이 google/gemma-4-e4b이다 보니 Hermes가 자동으로 Google 계열 Provider로 인식해서 밑에 위치하며 LM_ 접두사 설정을 붙여버린 것이었습니다.

그런데 LM Studio는 OpenAI 호환 서버입니다. Gemma 4가 Google 모델이라도, 이 모델을 실행하는 서버(LM Studio)와는 OpenAI 프로토콜로 대화해야 합니다.

처음에 "나 OpenAI 안 쓸 거야"라고 했을 때 Gemini가 계속 OpenAI 모드 설정을 권유하는 게 답답했었습니다. 같은 말을 반복하는 AI에 "이미 말했잖아요"라고 하기도 했습니다. 그런데 결국 Gemini가 하고 싶었던 말은 이거였던것이었습니다.

"OpenAI 서비스를 쓰라는 게 아닙니다. LM Studio가 OpenAI가 만든 통신 규약을 사용한다는 뜻입니다. 127.0.0.1(내 컴퓨터) 안에서만 도는 설정이에요." 이 말은 이것이었습니다.

해결 — .env 파일 한 줄 수정

Open optionsauto

# 이렇게 바꿨다
OPENAI_API_BASE=http://127.0.0.1:1234/v1
OPENAI_API_KEY=lm-studio

LM_BASE_URL을 OPENAI_API_BASE로, LM_API_KEY를 OPENAI_API_KEY로 바꾸는 것이 전부였습니다. Hermes를 재시작하자 더 이상 /api/show 에러가 없었고, Gemma 4가 응답하기 시작했습니다.

완전 무료. 완전 로컬. 인터넷도 필요 없다.

결과 (After)

Before vs After

결과물

• Gemma 4 E4B 모델이 Hermes AI Agent를 통해 로컬에서 완전히 동작

• LM Studio ↔ Hermes 연결 구조를 완전히 이해

• 어떤 로컬 모델이든 같은 방식으로 연결 가능한 구조 파악

이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 에러 로그 전체를 그대로 복붙하기 — 요약하지 말고 로그 원문을 그대로 붙여넣으면 AI가 훨씬 정확하게 진단한다

2. 에러가 바뀌면 진전 중 — 같은 에러가 아닌 다른 에러가 나오면 오히려 원인에 가까워지고 있다는 신호

3. AI가 반복해서 같은 말을 하면 내가 오해하고 있을 가능성 — "OpenAI 안 쓴다"고 했을 때 Gemini가 반복 설명한 건 이유가 있었다

이렇게 하면 안 돼요

1. 에러 메시지를 직접 해석하려 하지 말 것 — WinError 10054가 뭔지 혼자 구글링하는 것보다 AI에게 맥락과 함께 보여주는 게 훨씬 빠르다

2. LM Studio에서 로컬 모델을 쓴다고 OpenAI 설정을 피하지 말 것 — LM Studio 자체가 OpenAI 호환 서버라 피할 수가 없다

3. 모델 이름만 보고 Provider를 판단하지 말 것 — google/gemma-4-e4b라도 LM Studio에서 돌리면 OpenAI 프로토콜로 접근해야 한다

다른 상황에 적용한다면?

이번에 파악한 원리는 LM Studio + Hermes 조합에만 적용되는 게 아니다. LM Studio에 연결하는 모든 AI 에이전트 도구들(Open WebUI, Continue, Cursor 등)은 동일하게 OpenAI 호환 방식으로 설정해야 한다. 모델이 Meta의 Llama든, Alibaba의 Qwen이든, Google의 Gemma든 관계없이 — LM Studio 서버와 대화하는 규약은 항상 OpenAI 표준이다.

앞으로의 계획

1. Gemma 4 E4B 디스틸 버전 테스트 — 더 가벼운 버전으로 성능 대비 속도 비교

2. 상위 Gemma 모델 연결 — 더 큰 모델도 같은 방식으로 연결 가능한지 확인

3. Hermes + Obsidian 로컬 활용법 — 지식 관리 도구 Obsidian을 로컬 AI와 연결하는 방법 사례글로 정리 예정

재사용 가능한 프롬프트

프롬프트 1: 에러 로그 진단 요청

[LM Studio + Hermes 연결 시도 중] 아래 에러 로그가 나오고 있어. LM Studio 로그와 Hermes 로그 둘 다 붙여넣을게. 원인이 뭔지 단계별로 짚어줘. [에러 로그 붙여넣기]

프롬프트 2: .env 설정 검토 요청

현재 내 Hermes .env 파일이야. LM Studio(로컬 서버, 포트 1234)에 연결하려고 하는데 어떤 부분을 어떻게 바꿔야 하는지 알려줘. [.env 파일 내용 붙여넣기]소개