책에 포함된 노트Hermes Agent 사용법: 설치부터 메모리·자동화·운영까지 한 권으로 끝내기

13. 문제 해결과 운영 체크리스트

2026-04-18Views 93약 9분

문제 해결과 운영 체크리스트

Hermes를 오래 쓰다 보면 한 번쯤은 이런 순간이 옵니다. 설치는 했는데 명령이 안 잡히고, 모델 키는 넣은 것 같은데 인증이 실패하고, Telegram 봇은 묵묵부답이고, cron은 분명 등록했는데 조용한 순간 말입니다.

이럴 때 가장 나쁜 대응은 두 가지입니다. 하나는 무작정 재설치하는 것이고, 다른 하나는 "Hermes가 원래 불안정한가 보다" 하고 포기하는 것입니다. 실제로는 대부분의 문제가 생각보다 좁은 층에서 생깁니다. 운영체제, PATH, API 키, 게이트웨이 상태, 일정 표현식, 권한 설정 같은 곳 말입니다.¹²

이 장의 목표는 에러 문구를 많이 외우는 데 있지 않습니다. 문제가 생겼을 때 어느 층부터 확인해야 하는지 익히는 것입니다. 이 감각이 생기면 Hermes는 훨씬 덜 신비롭고, 훨씬 더 관리 가능한 시스템이 됩니다.

문제 해결과 운영 체크리스트

문제는 보통 네 층 중 하나에서 생긴다

Hermes 문제는 대체로 아래 네 층 가운데 하나에 속합니다.

실행 환경 문제: 운영체제, WSL2, Python, 네트워크, 설치 스크립트
명령 경로 문제: hermes 명령이 PATH에 없거나 셸이 갱신되지 않음
모델·프로바이더 문제: API 키, 모델 이름, 엔드포인트 주소, 속도 제한
운영 계층 문제: 게이트웨이, cron, 허용 사용자, 서비스 자동 시작, 로그

이렇게 나누면 머리가 훨씬 맑아집니다. 예를 들어 command not found는 모델 문제가 아닙니다. 반대로 Telegram 봇이 답하지 않는다고 해서 설치가 잘못된 것도 아닙니다. 증상은 다 비슷하게 "안 된다"지만, 보는 위치는 완전히 다릅니다.

가장 먼저 돌려 볼 기본 진단 루틴

공식 문서 기준으로 가장 먼저 써 볼 만한 명령은 이 정도입니다.²³

hermes --version
hermes doctor
hermes status
hermes gateway status
hermes logs gateway -n 50

여기서 감각을 정리해 보면 이렇습니다.

hermes --version: 정말 Hermes가 실행되는지 확인
hermes doctor: 환경·의존성·설정의 큰 문제를 점검
hermes status: 현재 상태를 전체적으로 확인
hermes gateway status: 메시징 게이트웨이 서비스 상태 확인
hermes logs gateway -n 50: 최근 게이트웨이 로그 확인

예전 글이나 커뮤니티 팁에서 hermes gateway logs 같은 표현을 볼 수도 있지만, 현재 공식 CLI 기준 로그 확인 명령은 hermes logs입니다.³

예를 들면 이렇게 씁니다.

hermes logs
hermes logs gateway -n 100
hermes logs errors --since 1h
hermes logs -f

즉, 문제 해결의 첫걸음은 추측이 아니라 현재 상태와 로그를 먼저 보는 것입니다.

설치 실패와 `command not found`

설치 문제는 초반에 가장 많이 만나지만, 의외로 가장 빨리 해결되는 문제이기도 합니다.

먼저 큰 전제부터 확인해야 합니다. 공식 퀵스타트 기준으로 Windows 사용자는 네이티브 Windows 터미널이 아니라 WSL2 안에서 Hermes를 실행하는 것이 권장 경로입니다.¹ PowerShell이나 CMD에서 바로 밀어붙이다가 꼬이는 것은 이상한 일이 아니라, 오히려 흔한 상황입니다.

설치가 끝난 것 같은데 hermes: command not found가 나온다면, 가장 먼저 의심할 것은 설치 실패보다 셸이 아직 새 PATH를 못 읽은 상태입니다.¹

source ~/.bashrc      # bash
source ~/.zshrc       # zsh
which hermes
ls ~/.local/bin/hermes

그래도 안 잡히면 ~/.local/bin이 PATH에 없을 수 있습니다.

export PATH="$HOME/.local/bin:$PATH"

이 줄이 먹히면, 같은 내용을 .bashrc나 .zshrc에 추가해 영구화하면 됩니다.

설치 자체가 실패하는 경우에는 대개 이런 원인들이 많습니다.

WSL2가 제대로 설치되지 않았거나 최신 상태가 아님
GitHub 접근이 막혀 설치 스크립트가 중간에 멈춤
Git이 없어서 설치가 출발하지 못함
지원 범위 밖의 Python 환경이나 시스템 설정 문제

Windows라면 먼저 WSL 상태부터 정리하는 편이 좋습니다.

wsl --update

그리고 Hermes 설치의 실제 핵심은 의외로 간단합니다.

지원 환경인가
Git이 있는가
셸을 다시 불러왔는가
PATH가 맞는가
GitHub와 모델 API에 네트워크로 닿는가

이 다섯 가지만 먼저 보면 대부분의 "설치가 안 돼요"는 꽤 빨리 좁혀집니다.

모델 연결 오류는 "키, 이름, 주소" 순서로 본다

모델이 연결되지 않을 때는 복잡하게 생각하지 말고 세 가지부터 봅니다.

API 키가 맞는가
모델 이름이 맞는가
엔드포인트 주소가 맞는가

이 순서가 좋습니다.²⁴

가장 쉬운 확인 방법은 hermes model로 다시 들어가 보는 것입니다.

hermes model

이 과정에서 흔한 실수는 이런 것들입니다.

다른 제공업체 키를 잘못 넣음
키 앞뒤에 공백이나 줄바꿈이 붙음
만료되었거나 한도에 걸린 키를 계속 사용함
커스텀 엔드포인트의 base_url이 틀림

특히 로컬 모델이나 자체 서버를 쓸 때는 /v1 경로가 빠졌는지 꼭 봐야 합니다.⁴

model:
  provider: custom
  default: qwen2.5-coder:32b
  base_url: http://localhost:11434/v1

또 하나 흔한 오해가 있습니다. 로컬 모델이 "인터넷 접근 권한이 없다"는 식으로 말해도, 실제로는 권한 문제가 아니라 도구 호출을 잘 못하는 모델 한계인 경우가 많습니다. 작은 로컬 모델은 웹 도구나 파일 도구를 서툴게 다뤄서 마치 권한이 막힌 것처럼 보일 수 있습니다.²⁴

이럴 때는 권한 설정을 뒤지기보다, 도구 호출이 더 안정적인 모델로 바꿔 보는 쪽이 빠릅니다.

또 429 같은 속도 제한 오류는 고장이라기보다 "지금은 잠깐 쉬어 달라"는 신호입니다. 이때는 재시도 간격을 두거나, 더 가벼운 모델과 fallback 구성을 고민하는 편이 현실적입니다.²

컨텍스트 부족과 토큰 폭주를 구분해야 한다

context length exceeded와 "왜 이렇게 토큰이 많이 들지?"는 비슷해 보여도 성격이 다릅니다.

컨텍스트 부족

이건 말 그대로 한 세션 안에 너무 많은 내용이 쌓인 상태입니다. 가장 먼저 할 일은 세션을 가볍게 만드는 것입니다.

/compress

필요하면 새 세션으로 넘어가는 것도 빠른 해결책입니다. Hermes는 긴 작업을 끝없이 한 세션에 몰아넣는 것보다, 중간중간 정리하며 가는 편이 더 안정적입니다.²⁵

처음부터 금방 컨텍스트가 터진다면, 커스텀 엔드포인트의 context_length가 실제 모델 상태와 어긋났을 가능성도 있습니다.⁴

토큰 폭주

이쪽은 조금 다릅니다. 보통은 다음 같은 경우가 원인입니다.

도구를 불필요하게 많이 호출함
작업 디렉터리 문맥이 너무 무거움
메모리나 스킬이 과하게 비대해짐
게이트웨이 경유 세션에서 불필요한 문맥이 끌려옴

이럴 때는 프롬프트를 더 명확하게 바꾸는 것이 의외로 큰 도움이 됩니다.

예를 들면:

"도구 쓰지 말고 바로 답해줘"
"읽기만 하고 수정은 하지 마"
"결론만 세 줄로 정리해줘"

이런 제한을 주면 괜한 도구 호출과 장황한 답을 줄일 수 있습니다.

즉, 세션이 길어 터지는 문제는 압축과 새 세션의 문제이고, 질문은 짧은데 비용이 큰 문제는 도구 사용과 문맥 관리의 문제로 보면 됩니다.

게이트웨이가 응답하지 않을 때

Telegram이나 Discord 봇이 말을 안 하면 괜히 심장이 철렁합니다. 하지만 여기서도 순서는 아주 단순합니다.

게이트웨이가 실행 중인가
토큰이 맞는가
내가 허용된 사용자인가
플랫폼 권한이 맞는가
로그에 무슨 메시지가 남는가

먼저 상태를 봅니다.

hermes gateway status

서비스가 죽어 있다면, 봇은 아무리 설정이 좋아도 대답할 수 없습니다. 살아 있는데도 무응답이면 로그를 봅니다.

hermes logs gateway -n 50

Telegram에서는 보통 다음을 확인합니다.

봇 토큰이 맞는가
허용 사용자 설정이 맞는가
홈 채널이나 채팅 대상이 의도와 맞는가

Discord에서는 특히 Message Content Intent가 자주 빠집니다. 공식 문서도 이게 "봇은 온라인인데 메시지를 못 읽는" 대표 원인이라고 설명합니다.⁶

또 DM과 서버 채널의 동작 차이도 알아야 합니다.

DM: 보통 모든 메시지에 응답
서버 채널: 기본적으로 @mention이 있어야 응답
예외: free-response 채널을 따로 열 수 있음⁶

즉, "서버에서는 답이 없는데 DM에서는 된다"는 경우는 버그가 아니라 기본 멘션 규칙일 가능성도 큽니다.

재부팅 뒤부터 갑자기 조용해졌다면 자동 시작 여부도 봐야 합니다. 공식 기준으로는 hermes gateway install 후 start를 사용하는 흐름입니다.⁷

hermes gateway install
hermes gateway start
hermes gateway status

Linux라면 필요에 따라 loginctl enable-linger도 검토합니다.⁷

cron이 실패할 때는 "작업, 시계, 전달, 게이트웨이"를 본다

cron이 안 돌면 가장 미스터리하게 느껴집니다. 눈앞에서 실행되지 않기 때문입니다. 그래서 네 칸으로 나눠 보면 좋습니다.

작업이 실제로 존재하는가
일정과 시간대가 맞는가
게이트웨이가 스케줄러를 돌리고 있는가
결과 전달만 실패한 것은 아닌가

먼저 목록부터 봅니다.

hermes cron list

여기서 작업이 paused 상태라면 안 도는 것이 정상입니다. 또 상대 시간이나 ISO 타임스탬프 같은 1회성 작업은 실행 후 사라질 수 있는데, 이것도 정상 동작입니다.⁵⁸

다음으로 중요한 사실 하나. cron은 게이트웨이가 돌립니다. CLI 세션을 켜 둔다고 자동 실행되는 것이 아닙니다.⁸ 즉, 자동화를 기대한다면 게이트웨이가 살아 있어야 합니다.

테스트할 때는 수동 실행이 유용합니다.

hermes cron tick
hermes cron run <job_id>

시간대 문제도 자주 놓칩니다. "매일 9시"라고 했는데 시스템 시간이 UTC를 보고 있으면, cron은 틀린 것이 아니라 내 시계와 다른 시계를 보고 있는 것입니다.

date
hermes cron list

전달 실패도 흔합니다. 작업은 성공했는데, 결과를 보낼 플랫폼 설정이 틀리거나 홈 채널이 없어서 조용히 끝나는 경우입니다.⁸

그리고 [SILENT] 규칙도 잊지 마세요. 프롬프트에서 "정상이면 [SILENT]만 응답하라"고 했다면, 아무것도 안 오는 것이 오히려 정상일 수 있습니다.⁸

즉, cron 진단은 이렇게 외우면 됩니다.

작업이 있나, 시계가 맞나, 게이트웨이가 도나, 결과가 갈 길을 찾았나.

오류처럼 보이지만 사실은 정상 동작인 것들

모든 "막힘"이 버그는 아닙니다. Hermes가 일부러 막는 경우도 많습니다.

대표적인 예가 curl | sh 같은 위험 패턴입니다. 이게 거부되면 "왜 안 되지?" 싶을 수 있지만, 보안 계층이 강하게 차단하는 것은 꽤 정상적인 동작입니다.²

또 메모리를 저장했는데 현재 세션에서 바로 반영되지 않는 것도 정상일 수 있습니다. 공식 메모리 문서 기준으로 메모리는 세션 시작 시의 frozen snapshot으로 주입되기 때문입니다. 중간에 저장된 내용은 디스크에는 즉시 반영되지만, 현재 세션 시스템 프롬프트에는 바로 안 들어갑니다.⁹

로컬 모델이 도구를 잘못 이해해서 "권한이 없다"고 말하는 것도 자주 있는 착시입니다. 이건 Hermes 자체보다 모델의 도구 호출 능력 부족일 가능성이 큽니다.²⁴

즉, 막혔을 때는 이렇게 한 번 더 생각하면 좋습니다.