FAQ 및 트러블슈팅

기준일: 2026-07-26
난이도: 초급
공식 기준: FAQ

개요

자주 묻는 질문과 설치·프로바이더·터미널·메시징·성능·MCP·프로파일·워크플로 문제 해결을 모은 공식 FAQ입니다.

핵심 개념

주제	요지
프로바이더	OpenAI 호환 API 전반 (OpenRouter, Nous Portal, OpenAI, Anthropic, Gemini, 로컬 등)
데이터	설정한 LLM 프로바이더로만 API 호출 — Hermes 자체 텔레메트리 없음, `~/.hermes/` 로컬 저장
메모리 vs 스킬	사실(preferences) vs 절차(how-to)
프로파일	관리형 `HERMES_HOME` 계층 — 봇 토큰·메모리·세션 격리
백업	`hermes backup` (전체) vs `hermes profile export` (단일, 자격증명 제외)

상세

자주 묻는 질문

어떤 LLM 프로바이더가 동작하나?
OpenRouter, Nous Portal, OpenAI, Anthropic, Google Gemini, z.ai/GLM, Kimi, MiniMax, Ollama/vLLM/llama.cpp/SGLang 등 OpenAI 호환. hermes model 또는 ~/.hermes/.env.

플랫폼 지원?
Platform Support 매트릭스 참고.

WSL2에서 Windows Chrome 제어?
/browser connect보다 MCP 브리지 권장: Windows의 chrome-devtools-mcp를 cmd.exe/powershell.exe로 붙이기.

오프라인/로컬?
hermes model → Custom endpoint. base_url 예: http://localhost:11434/v1. 컨텍스트 길이는 서버 실효값과 맞출 것. 로컬은 스트림 타임아웃 완화(필요 시 HERMES_STREAM_READ_TIMEOUT).

비용?
Hermes 자체 MIT 무료. 과금은 선택한 LLM API.

다중 사용자?
메시징 게이트웨이 + allowlist / DM pairing.

Python 프로젝트?
from run_agent import AIAgent — Python Library.

설치 이슈

증상	조치
`hermes: command not found`	`source ~/.bashrc`/`~/.zshrc`, `~/.local/bin` PATH
Python 너무 오래됨	3.11+
`node`/`nvm` 미검출	`terminal.shell_init_files`에 `~/.zshrc`/`nvm.sh` 등, 기본 `~/.bashrc` auto-source
`uv` 없음	astral uv 설치
sudo 설치	`~/.local/bin` 경로 사용, 이전 sudo 바이너리 정리 후 재설치

프로바이더·모델

/model은 이미 설정한 프로바이더만 전환 — 신규 추가는 터미널 hermes model
키/모델 ID 불일치 → hermes config show, hermes model
429 → 대기·플랜·다른 프로바이더
컨텍스트 초과 → /compress, model.context_length 명시

터미널

위험 명령은 승인 프롬프트 (정상)
메시징에서 sudo 비밀번호 프롬프트 불가
Docker 백엔드: 데몬·docker 그룹

메시징

hermes gateway status
hermes gateway start
# 로그: ~/.hermes/logs/gateway.log

allowlist / DM pairing / open 모드 구분. WSL은 systemd 대신 hermes gateway run + tmux/nohup 권장. macOS launchd PATH는 hermes gateway install 재실행으로 스냅샷.

성능

작은 모델, -t 툴셋 축소, /compress, /usage.

MCP

uv pip install -e ".[mcp]", 서버 바이너리·tools.include/exclude, /reload-mcp.

프로파일 FAQ

봇 토큰 공유 불가 (플랫폼 exclusive)
메모리/세션 비공유 (--clone-all로 복사 가능)
hermes update 1회 → 코드 1번 + 스킬 전 프로파일 동기

워크플로 패턴

멀티모델: delegation.model / delegation.provider 또는 /model (캐시 리셋 주의)
WhatsApp 번호 하나 다중 에이전트: 현재 제한 — 성격 전환/별도 번호/Telegram·Discord
Telegram 노이즈: display.tool_progress: off|new
Telegram 슬래시 100개 한도: skills.platform_disabled.telegram
공유 스레드: Slack(스레드 키), Discord(채널 키)
이전: hermes backup / hermes import, 단일은 hermes profile export|import

여전히 막히면

GitHub Issues, Nous Discord, 버그 리포트에 OS·python3 --version·hermes --version·전체 에러 포함.

체크리스트

공식 원문과 명령·설정 키를 대조했다
로컬/config.yaml/.env에서 재현 경로를 확인했다
권한·allowlist·시크릿 노출을 점검했다
실패 시 롤백·비활성화 방법을 알고 있다

다음 단계

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스

FAQ 및 트러블슈팅

기준일: 2026-07-26
난이도: 초급
공식 기준: FAQ

개요

자주 묻는 질문과 설치·프로바이더·터미널·메시징·성능·MCP·프로파일·워크플로 문제 해결을 모은 공식 FAQ입니다.

핵심 개념

주제	요지
프로바이더	OpenAI 호환 API 전반 (OpenRouter, Nous Portal, OpenAI, Anthropic, Gemini, 로컬 등)
데이터	설정한 LLM 프로바이더로만 API 호출 — Hermes 자체 텔레메트리 없음, `~/.hermes/` 로컬 저장
메모리 vs 스킬	사실(preferences) vs 절차(how-to)
프로파일	관리형 `HERMES_HOME` 계층 — 봇 토큰·메모리·세션 격리
백업	`hermes backup` (전체) vs `hermes profile export` (단일, 자격증명 제외)

상세

자주 묻는 질문

플랫폼 지원?
Platform Support 매트릭스 참고.

WSL2에서 Windows Chrome 제어?
/browser connect보다 MCP 브리지 권장: Windows의 chrome-devtools-mcp를 cmd.exe/powershell.exe로 붙이기.

비용?
Hermes 자체 MIT 무료. 과금은 선택한 LLM API.

다중 사용자?
메시징 게이트웨이 + allowlist / DM pairing.

Python 프로젝트?
from run_agent import AIAgent — Python Library.

설치 이슈

증상	조치
`hermes: command not found`	`source ~/.bashrc`/`~/.zshrc`, `~/.local/bin` PATH
Python 너무 오래됨	3.11+
`node`/`nvm` 미검출	`terminal.shell_init_files`에 `~/.zshrc`/`nvm.sh` 등, 기본 `~/.bashrc` auto-source
`uv` 없음	astral uv 설치
sudo 설치	`~/.local/bin` 경로 사용, 이전 sudo 바이너리 정리 후 재설치

프로바이더·모델

/model은 이미 설정한 프로바이더만 전환 — 신규 추가는 터미널 hermes model
키/모델 ID 불일치 → hermes config show, hermes model
429 → 대기·플랜·다른 프로바이더
컨텍스트 초과 → /compress, model.context_length 명시

터미널

위험 명령은 승인 프롬프트 (정상)
메시징에서 sudo 비밀번호 프롬프트 불가
Docker 백엔드: 데몬·docker 그룹

메시징

hermes gateway status
hermes gateway start
# 로그: ~/.hermes/logs/gateway.log

allowlist / DM pairing / open 모드 구분. WSL은 systemd 대신 hermes gateway run + tmux/nohup 권장. macOS launchd PATH는 hermes gateway install 재실행으로 스냅샷.

성능

작은 모델, -t 툴셋 축소, /compress, /usage.

MCP

uv pip install -e ".[mcp]", 서버 바이너리·tools.include/exclude, /reload-mcp.

프로파일 FAQ

봇 토큰 공유 불가 (플랫폼 exclusive)
메모리/세션 비공유 (--clone-all로 복사 가능)
hermes update 1회 → 코드 1번 + 스킬 전 프로파일 동기

워크플로 패턴

멀티모델: delegation.model / delegation.provider 또는 /model (캐시 리셋 주의)
WhatsApp 번호 하나 다중 에이전트: 현재 제한 — 성격 전환/별도 번호/Telegram·Discord
Telegram 노이즈: display.tool_progress: off|new
Telegram 슬래시 100개 한도: skills.platform_disabled.telegram
공유 스레드: Slack(스레드 키), Discord(채널 키)
이전: hermes backup / hermes import, 단일은 hermes profile export|import

여전히 막히면

GitHub Issues, Nous Discord, 버그 리포트에 OS·python3 --version·hermes --version·전체 에러 포함.

체크리스트

공식 원문과 명령·설정 키를 대조했다
로컬/config.yaml/.env에서 재현 경로를 확인했다
권한·allowlist·시크릿 노출을 점검했다
실패 시 롤백·비활성화 방법을 알고 있다

다음 단계

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스

FAQ 및 트러블슈팅

개요

핵심 개념

상세

자주 묻는 질문

설치 이슈

프로바이더·모델

터미널

메시징

성능

MCP

프로파일 FAQ

워크플로 패턴

여전히 막히면

체크리스트

다음 단계

관련 가이드

FAQ 및 트러블슈팅

개요

핵심 개념

상세

자주 묻는 질문

설치 이슈

프로바이더·모델

터미널

메시징

성능

MCP

프로파일 FAQ

워크플로 패턴

여전히 막히면

체크리스트

다음 단계

관련 가이드