본문으로 건너뛰기

FAQ 및 문제 해결

anchor alias​
anchor alias​

FAQ 및 문제 해결

가장 일반적인 질문과 문제에 대한 빠른 답변과 수정 사항을 제공합니다.

자주 묻는 질문​

어떤 LLM 제공업체가 Hermes와 협력합니까?​

Hermes Agent는 모든 OpenAI 호환 API와 작동합니다. 지원되는 제공업체는 다음과 같습니다.

  • OpenRouter — 하나의 API 키를 통해 수백 가지 모델에 액세스(유연성을 위해 권장)
  • Nous Portal — Nous Research의 자체 추론 엔드포인트
  • OpenAI — GPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o 등
  • 인류적 — Claude 모델(직접 API, hermes login anthropic을 통한 OAuth, OpenRouter 또는 호환되는 프록시)
  • Google — Gemini 모델(gemini 공급자, google-gemini-cli OAuth 공급자, OpenRouter 또는 호환 프록시를 통한 직접 API)
  • z.ai / ZhipuAI — GLM 모델
  • Kimi / Moonshot AI — Kimi 모델
  • MiniMax — 글로벌 및 중국 엔드포인트
  • 로컬 모델 — Ollama, vLLM, llama.cpp, SGLang 또는 모든 OpenAI 호환 서버를 통해

hermes model을 사용하거나 ~/.hermes/.env을 편집하여 공급자를 설정하세요. 모든 공급자 키에 대해서는 환경 변수 참조를 확인하세요.

Windows에서 작동하나요?​

기본적으로는 그렇지 않습니다. Hermes Agent에는 Unix와 유사한 환경이 필요합니다. Windows에서는 WSL2를 설치하고 내부에서 Hermes를 실행합니다. 표준 설치 명령은 WSL2에서 완벽하게 작동합니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

WSL2에서 Hermes를 실행합니다. 일반 Windows Chrome을 제어하는 ​​가장 좋은 방법은 무엇입니까?​

/browser connect보다 MCP 브리지를 선호합니다.

권장 패턴:

  • WSL2 내에서 Hermes 실행
  • Windows에서 정상적으로 로그인된 Chrome을 계속 사용하세요.
  • cmd.exe 또는 powershell.exe을 통해 chrome-devtools-mcp을 MCP 서버로 추가합니다.
  • Hermes가 결과 MCP 브라우저 도구를 사용하도록 허용

이는 Hermes 핵심 브라우저 전송을 WSL2/Windows 경계를 넘어 직접 연결하는 것보다 더 안정적입니다.

참조:

Android/Termux에서 작동하나요?​

예 — Hermes는 이제 Android 휴대폰에 대해 테스트된 Termux 설치 경로를 보유하고 있습니다.

빠른 설치:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

완전히 명시적인 수동 단계, 지원되는 추가 기능 및 현재 제한 사항은 Termux 가이드를 참조하세요.

중요한 주의 사항: voice 추가 항목은 faster-whisper → ctranslate2에 종속되고 ctranslate2은 Android 휠을 게시하지 않기 때문에 전체 .[all] 추가 항목은 현재 Android에서 사용할 수 없습니다. 대신 테스트된 .[termux] extra를 사용하세요.

내 데이터가 어디로든 전송되나요?​

API 호출은 귀하가 구성한 LLM 공급자(예: OpenRouter, 로컬 Ollama 인스턴스)로만 이동합니다. Hermes Agent는 원격 측정, 사용 데이터 또는 분석을 수집하지 않습니다. 대화, 기억 및 기술은 ~/.hermes/에 로컬로 저장됩니다.

오프라인/로컬 모델과 함께 사용할 수 있나요?​

그렇습니다. hermes model을 실행하고 사용자 정의 엔드포인트를 선택한 후 서버 URL을 입력하세요.

hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 32768   ← set this to match your server's actual context window

또는 config.yaml에서 직접 구성합니다.

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Hermes는 config.yaml의 엔드포인트, 공급자 및 기본 URL을 유지하므로 다시 시작해도 유지됩니다. 로컬 서버에 정확히 하나의 모델이 로드된 경우 /model custom이 이를 자동 감지합니다. config.yaml에서 provider: custom을 설정할 수도 있습니다. 이는 다른 것에 대한 별칭이 아닌 일류 공급자입니다.

이는 Ollama, vLLM, llama.cpp 서버, SGLang, LocalAI 등과 함께 작동합니다. 자세한 내용은 구성 가이드를 참조하세요.

Ollama users

Ollama에서 사용자 정의 num_ctx(예: ollama run --num_ctx 16384)을 설정하는 경우 Hermes에서 일치하는 컨텍스트 길이를 설정해야 합니다. Ollama의 /api/show는 사용자가 구성한 유효 num_ctx이 아니라 모델의 최대 컨텍스트를 보고합니다.

Timeouts with local models

Hermes는 로컬 엔드포인트를 자동으로 감지하고 스트리밍 시간 제한을 완화합니다(읽기 시간 제한을 120초에서 1800초로 늘림, 오래된 스트림 감지 비활성화). 매우 큰 컨텍스트에서 여전히 시간 초과가 발생하는 경우 .env에 HERMES_STREAM_READ_TIMEOUT=1800을 설정하세요. 자세한 내용은 로컬 LLM 가이드를 참조하세요.

비용은 얼마입니까?​

Hermes Agent 자체는 무료이며 오픈 소스(MIT 라이센스)입니다. 선택한 제공업체의 LLM API 사용에 대해서만 비용을 지불합니다. 로컬 모델은 완전히 무료로 실행할 수 있습니다.

여러 사람이 하나의 인스턴스를 사용할 수 있나요?​

그렇습니다. 메시징 게이트웨이를 사용하면 여러 사용자가 Telegram, Discord, Slack, WhatsApp 또는 Home Assistant를 통해 동일한 Hermes Agent 인스턴스와 상호 작용할 수 있습니다. 액세스는 허용 목록(특정 사용자 ID) 및 DM 페어링(메시지에 대한 첫 번째 사용자가 액세스 요청)을 통해 제어됩니다.

기억력과 기술의 차이점은 무엇입니까?​

  • 메모리는 사실, 즉 상담원이 귀하, 귀하의 프로젝트, 선호도에 대해 알고 있는 정보를 저장합니다. 관련성에 따라 추억이 자동으로 검색됩니다.
  • 기술 저장 절차 — 작업 수행 방법에 대한 단계별 지침입니다. 에이전트가 유사한 작업에 직면하면 기술이 회상됩니다.

둘 다 세션 전반에 걸쳐 지속됩니다. 자세한 내용은 메모리 및 스킬을 참조하세요.

내 Python 프로젝트에서 사용할 수 있나요?​

그렇습니다. AIAgent 클래스를 가져오고 프로그래밍 방식으로 Hermes를 사용합니다.

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")

전체 API 사용법은 Python 라이브러리 가이드를 참조하세요.

문제 해결​

설치 문제​

hermes: command not found 설치 후​

원인: 쉘이 업데이트된 PATH를 다시 로드하지 않았습니다.

해결책:

# Reload your shell profile
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# Or start a new terminal session

그래도 작동하지 않으면 설치 위치를 확인하세요.

which hermes
ls ~/.local/bin/hermes
팁

설치 프로그램은 PATH에 ~/.local/bin을 추가합니다. 비표준 쉘 구성을 사용하는 경우 export PATH="$HOME/.local/bin:$PATH"을 수동으로 추가하세요.

Python 버전이 너무 오래됨​

원인: Hermes에는 Python 3.11 이상이 필요합니다.

해결책:

python3 --version   # Check current version

# Install a newer Python
sudo apt install python3.12   # Ubuntu/Debian
brew install python@3.12      # macOS

설치 프로그램이 이를 자동으로 처리합니다. 수동 설치 중에 이 오류가 표시되면 먼저 Python을 업그레이드하세요.

터미널 명령은 node: command not found(또는 nvm, pyenv, asdf, …)이라고 말합니다.​

원인: Hermes는 시작 시 bash -l을 한 번 실행하여 세션별 환경 스냅샷을 구축합니다. Bash 로그인 쉘은 /etc/profile, ~/.bash_profile 및 ~/.profile을 읽지만 **~/.bashrc을 소스로 제공하지 않습니다. 따라서 도구는 그곳에 스스로 설치됩니다(nvm, asdf, pyenv, cargo, 사용자 정의 PATH 내보내기)는 스냅샷에 표시되지 않습니다. 이는 Hermes가 systemd에서 실행되거나 대화형 셸 프로필이 미리 로드되지 않은 최소 셸에서 실행될 때 가장 일반적으로 발생합니다.

해결책: Hermes는 기본적으로 ~/.bashrc을 자동 소스로 제공합니다. 충분하지 않은 경우 – 예를 들어 PATH가 ~/.zshrc에 있는 zsh 사용자이거나 독립형 파일에서 nvm을 초기화한 경우 — ~/.hermes/config.yaml에 소스로 추가할 파일을 나열합니다.

terminal:
  shell_init_files:
    - ~/.zshrc                     # zsh users: pulls zsh-managed PATH into the bash snapshot
    - ~/.nvm/nvm.sh                # direct nvm init (works regardless of shell)
    - /etc/profile.d/cargo.sh      # system-wide rc files
  # When this list is set, the default ~/.bashrc auto-source is NOT added —
  # include it explicitly if you want both:
  #   - ~/.bashrc
  #   - ~/.zshrc

누락된 파일은 자동으로 건너뜁니다. 소싱은 bash에서 발생하므로 zsh 전용 구문에 의존하는 파일은 오류가 발생할 수 있습니다. 이것이 문제가 되는 경우 전체 rc 파일이 아닌 PATH 설정 부분(예: nvm의 nvm.sh 직접)만 소싱하세요.

자동 소스 동작을 비활성화하려면(엄격한 로그인 쉘 의미에만 해당):

terminal:
  auto_source_bashrc: false

uv: command not found​

원인: uv 패키지 관리자가 설치되지 않았거나 PATH에 없습니다.

해결책:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

설치 중 권한 거부 오류​

원인: 설치 디렉터리에 쓸 수 있는 권한이 부족합니다.

해결책:

# Don't use sudo with the installer — it installs to ~/.local/bin
# If you previously installed with sudo, clean up:
sudo rm /usr/local/bin/hermes
# Then re-run the standard installer
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

공급자 및 모델 문제​

/model에는 공급자가 하나만 표시되며 공급자를 전환할 수 없습니다.​

원인: /model(채팅 세션 내)은 이미 구성한 공급자 간에만 전환할 수 있습니다. OpenRouter만 설정한 경우 /model이 모두 표시됩니다.

해결책: 세션을 종료하고 터미널에서 hermes model을 사용하여 새 공급자를 추가하세요.

# Exit the Hermes chat session first (Ctrl+C or /quit)

# Run the full provider setup wizard
hermes model

# This lets you: add providers, run OAuth, enter API keys, configure endpoints
``hermes model`을 통해 새 공급자를 추가한 후 새 채팅 세션을 시작하세요. 이제 `/model`에 구성된 모든 공급자가 표시됩니다.

:::tip[Quick reference]
| 싶어... | 사용 |
|-----------|-----|
| 새 제공업체 추가 | `hermes model` (터미널에서) |
| API 키 입력/변경 | `hermes model` (터미널에서) |
| 세션 중간에 모델 전환 | `/model <name>`(세션 내부) |
| 구성된 다른 제공업체로 전환 | `/model provider:model`(세션 내부) |

:::
#### API 키가 작동하지 않습니다 \{#api-key-not-working}

**원인:** 키가 누락되었거나, 만료되었거나, 잘못 설정되었거나, 잘못된 제공업체에 대한 것입니다.

**해결책:**
```bash
# Check your configuration
hermes config show

# Re-configure your provider
hermes model

# Or set directly
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
경고

키가 공급자와 일치하는지 확인하세요. OpenAI 키는 OpenRouter에서 작동하지 않으며 그 반대의 경우도 마찬가지입니다. 충돌하는 항목이 있는지 ~/.hermes/.env을 확인하세요.

모델을 사용할 수 없음/모델을 찾을 수 없음​

원인: 모델 식별자가 올바르지 않거나 제공업체에서 사용할 수 없습니다.

해결책:

# List available models for your provider
hermes model

# Set a valid model
hermes config set HERMES_MODEL anthropic/claude-opus-4.7

# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

속도 제한(429 오류)​

원인: 제공업체의 요금 한도를 초과했습니다.

해결책: 잠시 기다렸다가 다시 시도하세요. 지속적인 사용을 위해서는 다음을 고려하십시오.

  • 제공업체 요금제 업그레이드
  • 다른 모델이나 제공업체로 전환
  • hermes chat --provider <alternative>을 사용하여 다른 백엔드로 라우팅

컨텍스트 길이가 초과되었습니다.​

원인: 모델의 컨텍스트 창에 비해 대화가 너무 길어졌거나 Hermes가 모델에 대해 잘못된 컨텍스트 길이를 감지했습니다.

해결책:

# Compress the current session
/compress

# Or start a fresh session
hermes chat

# Use a model with a larger context window
hermes chat --model openrouter/google/gemini-3-flash-preview

첫 번째 긴 대화에서 이런 일이 발생하면 Hermes가 모델에 대해 잘못된 컨텍스트 길이를 가질 수 있습니다. 감지된 내용을 확인하세요.

CLI 시작 줄을 살펴보세요. 감지된 컨텍스트 길이(예: 📊 Context limit: 128000 tokens)가 표시됩니다. 세션 중에 /usage을(를) 통해 확인할 수도 있습니다.

컨텍스트 감지를 수정하려면 명시적으로 설정하세요.

# In ~/.hermes/config.yaml
model:
  default: your-model-name
  context_length: 131072  # your model's actual context window

또는 사용자 정의 엔드포인트의 경우 모델별로 추가합니다.

custom_providers:
  - name: "My Server"
    base_url: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 32768

자동 감지 작동 방식과 모든 재정의 옵션은 컨텍스트 길이 감지를 참조하세요.

터미널 문제​

위험한 명령으로 차단됨​

원인: Hermes가 잠재적으로 파괴적인 명령(예: rm -rf, DROP TABLE)을 감지했습니다. 이는 안전 기능입니다.

해결책: 메시지가 표시되면 명령을 검토하고 y을 입력하여 승인합니다. 다음을 수행할 수도 있습니다.

  • 상담원에게 더 안전한 대안을 사용하도록 요청하세요.
  • 보안 문서에서 위험한 패턴의 전체 목록을 확인하세요.
팁

이는 의도한 대로 작동합니다. Hermes는 절대로 자동으로 파괴적인 명령을 실행하지 않습니다. 승인 프롬프트는 실행될 작업을 정확하게 보여줍니다.

sudo이 메시징 게이트웨이를 통해 작동하지 않습니다.​

원인: 메시징 게이트웨이는 대화형 터미널 없이 실행되므로 sudo에서 비밀번호를 묻는 메시지를 표시할 수 없습니다.

해결책:

  • 메시지에서 sudo을 피하세요. 상담원에게 대안을 찾아달라고 요청하세요.
  • sudo을 사용해야 하는 경우 /etc/sudoers의 특정 명령에 대해 비밀번호 없는 sudo를 구성하세요.
  • 또는 관리 작업을 위해 터미널 인터페이스로 전환하세요: hermes chat

Docker 백엔드가 연결되지 않음​

원인: Docker 데몬이 실행되고 있지 않거나 사용자에게 권한이 부족합니다.

해결책:

# Check Docker is running
docker info

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker run hello-world

메시징 문제​

봇이 메시지에 응답하지 않음​

원인: 봇이 실행되지 않거나 승인되지 않았거나 사용자가 허용 목록에 없습니다.

해결책:

# Check if the gateway is running
hermes gateway status

# Start the gateway
hermes gateway start

# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50

메시지가 전달되지 않음​

원인: 네트워크 문제, 봇 토큰 만료 또는 플랫폼 웹훅 구성 오류.

해결책:

  • hermes gateway setup을 사용하여 봇 토큰이 유효한지 확인하세요.
  • 게이트웨이 로그 확인: cat ~/.hermes/logs/gateway.log | tail -50
  • 웹훅 기반 플랫폼(Slack, WhatsApp)의 경우 서버가 공개적으로 액세스 가능한지 확인하세요.

허용 목록 혼란 — 누가 봇과 대화할 수 있나요?​

원인: 인증 모드에 따라 액세스할 수 있는 사람이 결정됩니다.

해결책:

모드작동 원리
허용 목록구성에 나열된 사용자 ID만 상호 작용할 수 있습니다.
DM 페어링DM으로 메시지를 보낸 첫 번째 사용자는 독점 액세스 권한을 요구합니다.
열기누구나 상호작용 가능(프로덕션에는 권장되지 않음)

게이트웨이 설정에서 ~/.hermes/config.yaml을 구성합니다. 메시징 문서를 참조하세요.

게이트웨이가 시작되지 않습니다​

원인: 종속성 누락, 포트 충돌 또는 잘못 구성된 토큰.

해결책:

# Install core messaging gateway dependencies
pip install "hermes-agent[messaging]"  # Telegram, Discord, Slack, and shared gateway deps

# Check for port conflicts
lsof -i:8080

# Verify configuration
hermes config show

WSL: 게이트웨이 연결이 계속 끊어지거나 hermes gateway start이 실패합니다.​

원인: WSL의 시스템 지원은 신뢰할 수 없습니다. 많은 WSL2 설치에는 systemd가 활성화되어 있지 않으며, 활성화하더라도 서비스는 WSL 다시 시작 또는 Windows 유휴 종료 후에 유지되지 않을 수 있습니다.

해결책: systemd 서비스 대신 포그라운드 모드를 사용하십시오.

# Option 1: Direct foreground (simplest)
hermes gateway run

# Option 2: Persistent via tmux (survives terminal close)
tmux new -s hermes 'hermes gateway run'
# Reattach later: tmux attach -t hermes

# Option 3: Background via nohup
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

어쨌든 systemd를 시도하려면 활성화되어 있는지 확인하십시오.

  1. /etc/wsl.conf 열기(존재하지 않는 경우 생성)
  2. 추가: 
    [boot]
    systemd=true
  3. PowerShell에서: wsl --shutdown
  4. WSL 터미널을 다시 엽니다.
  5. 확인: systemctl is-system-running이 "실행 중" 또는 "성능 저하"로 표시되어야 합니다.
Auto-start on Windows boot

안정적인 자동 시작을 위해 Windows 작업 스케줄러를 사용하여 로그인 시 WSL + 게이트웨이를 시작합니다.

  1. wsl -d Ubuntu -- bash -lc 'hermes gateway run'을 실행하는 작업을 만듭니다.
  2. 사용자 로그온 시 트리거되도록 설정

macOS: Node.js/ffmpeg/게이트웨이에서 찾을 수 없는 기타 도구​

원인: 시작된 서비스는 Homebrew, nvm, 화물 또는 기타 사용자 설치 도구 디렉터리를 포함하지 않는 최소 PATH(/usr/bin:/bin:/usr/sbin:/sbin)를 상속합니다. 이로 인해 일반적으로 WhatsApp 브리지(node not found) 또는 음성 전사(ffmpeg not found)가 중단됩니다.

해결책: hermes gateway install을 실행할 때 게이트웨이는 셸 PATH를 캡처합니다. 게이트웨이를 설정한 후 도구를 설치한 경우 설치를 다시 실행하여 업데이트된 PATH를 캡처하세요.

hermes gateway install    # Re-snapshots your current PATH
hermes gateway start      # Detects the updated plist and reloads

plist에 올바른 경로가 있는지 확인할 수 있습니다.

/usr/libexec/PlistBuddy -c "Print:EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

성능 문제​

느린 응답​

원인: 대규모 모델, 멀리 떨어진 API 서버 또는 도구가 많은 무거운 시스템 프롬프트.

해결책:

  • 더 빠르고 더 작은 모델을 사용해 보세요: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
  • 활성 도구 집합 줄이기: hermes chat -t "terminal"
  • 공급자에 대한 네트워크 대기 시간을 확인하세요.
  • 로컬 모델의 경우 GPU VRAM이 충분한지 확인하세요.

높은 토큰 사용량​

원인: 긴 대화, 장황한 시스템 프롬프트 또는 컨텍스트를 축적하는 많은 도구 호출.

해결책:

# Compress the conversation to reduce tokens
/compress

# Check session token usage
/usage
팁

장시간 세션 중에는 /compress을 정기적으로 사용하세요. 대화 기록을 요약하고 컨텍스트를 유지하면서 토큰 사용량을 크게 줄입니다.

세션이 너무 길어짐​

원인: 확장된 대화는 메시지와 도구 출력을 축적하여 컨텍스트 제한에 접근합니다.

해결책:

# Compress current session (preserves key context)
/compress

# Start a new session with a reference to the old one
hermes chat

# Resume a specific session later if needed
hermes chat --continue

MCP 문제​

MCP 서버가 연결되지 않음​

원인: 서버 바이너리를 찾을 수 없거나 명령 경로가 잘못되었거나 런타임이 누락되었습니다.

해결책:

# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

# For npm-based servers, ensure Node.js is available
node --version
npx --version

# Test the server manually
npx -y @modelcontextprotocol/server-filesystem /tmp
``~/.hermes/config.yaml` MCP 구성을 확인하세요.
```yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

MCP 서버에서 도구가 표시되지 않음​

원인: 서버가 시작되었지만 도구 검색에 실패했거나 도구가 구성에 의해 필터링되었거나 서버가 예상한 MCP 기능을 지원하지 않습니다.

해결책:

  • MCP 연결 오류에 대한 게이트웨이/에이전트 로그를 확인하세요.
  • 서버가 tools/list RPC 메서드에 응답하는지 확인하세요.
  • 해당 서버에서 tools.include, tools.exclude, tools.resources, tools.prompts 또는 enabled 설정을 검토합니다.
  • 리소스/프롬프트 유틸리티 도구는 세션이 실제로 해당 기능을 지원할 때만 등록된다는 점을 기억하세요.
  • 구성을 변경한 후 /reload-mcp을 사용하세요.
# Verify MCP servers are configured
hermes config show | grep -A 12 mcp_servers

# Restart Hermes or reload MCP after config changes
hermes chat

참조:

MCP 시간 초과 오류​

원인: MCP 서버가 응답하는 데 너무 오랜 시간이 걸리거나 실행 중에 충돌이 발생했습니다.

해결책:

  • 지원되는 경우 MCP 서버 구성의 시간 초과를 늘립니다.
  • MCP 서버 프로세스가 아직 실행 중인지 확인하세요.
  • 원격 HTTP MCP 서버의 경우 네트워크 연결을 확인하세요.
경고

MCP 서버가 요청 중에 충돌하면 Hermes는 시간 초과를 보고합니다. Hermes 로그뿐만 아니라 서버 자체 로그를 확인하여 근본 원인을 진단하세요.

프로필​

프로필은 단순히 HERMES_HOME을 설정하는 것과 어떻게 다릅니까?​

프로필은 HERMES_HOME 위에 있는 관리 레이어입니다. 모든 명령 전에 HERMES_HOME=/some/path을 수동으로 설정할 수 있지만* 디렉터리 구조 생성, 셸 별칭(hermes-work) 생성, ~/.hermes/active_profile에서 활성 프로필 추적, 모든 프로필에 걸쳐 기술 업데이트 자동 동기화 등 모든 작업은 프로필이 처리합니다. 또한 탭 완성 기능과 통합되므로 경로를 기억할 필요가 없습니다.

두 프로필이 동일한 봇 토큰을 공유할 수 있나요?​

아니요. 각 메시징 플랫폼(Telegram, Discord 등)에는 봇 토큰에 대한 독점적인 액세스가 필요합니다. 두 프로필이 동일한 토큰을 동시에 사용하려고 하면 두 번째 게이트웨이가 연결되지 않습니다. 프로필별로 별도의 봇을 생성하세요. Telegram의 경우 @BotFather에게 문의하여 추가 봇을 생성하세요.

프로필은 메모리나 세션을 공유합니까?​

아니요. 각 프로필에는 자체 메모리 저장소, 세션 데이터베이스 및 기술 디렉터리가 있습니다. 그들은 완전히 고립되어 있습니다. 기존 메모리와 세션으로 새 프로필을 시작하려면 hermes profile create newname --clone-all을 사용하여 현재 프로필의 모든 내용을 복사하세요.

hermes update을 실행하면 어떻게 되나요?​

hermes update은 최신 코드를 가져오고 종속성을 한 번(프로필별로 설치하지 않음) 다시 설치합니다. 그런 다음 업데이트된 기술을 모든 프로필에 자동으로 동기화합니다. hermes update은 한 번만 실행하면 됩니다. 이는 머신의 모든 프로필에 적용됩니다.

얼마나 많은 프로필을 실행할 수 있나요?​

엄격한 제한은 없습니다. 각 프로필은 ~/.hermes/profiles/ 아래의 디렉터리입니다. 실제 제한은 디스크 공간과 시스템이 처리할 수 있는 동시 게이트웨이 수에 따라 다릅니다(각 게이트웨이는 경량 Python 프로세스입니다). 수십 개의 프로필을 실행하는 것은 괜찮습니다. 각 유휴 프로필은 리소스를 사용하지 않습니다.

워크플로 및 패턴​

다양한 작업에 다양한 모델 사용(다중 모델 워크플로)​

시나리오: GPT-5.4를 일일 드라이버로 사용하지만 Gemini 또는 Grok이 더 나은 소셜 미디어 콘텐츠를 작성합니다. 매번 수동으로 모델을 전환하는 것은 지루한 작업입니다.

해결책: 위임 구성. Hermes는 자동으로 하위 에이전트를 다른 모델로 라우팅할 수 있습니다. ~/.hermes/config.yaml에서 다음을 설정하세요.

delegation:
  model: "google/gemini-3-flash-preview"   # subagents use this model
  provider: "openrouter"                    # provider for subagents

이제 Hermes에게 "X에 대한 Twitter 스레드를 작성해 주세요"라고 말하면 delegate_task 하위 에이전트가 생성되고 해당 하위 에이전트는 기본 모델 대신 Gemini에서 실행됩니다. 기본 대화는 GPT-5.4에 유지됩니다.

프롬프트에서 명시적으로 설명할 수도 있습니다. "제품 출시에 대한 소셜 미디어 게시물을 작성하는 작업을 위임하세요. 실제 작성에는 하위 에이전트를 사용하세요." 에이전트는 위임 구성을 자동으로 선택하는 delegate_task을 사용합니다.

위임이 없는 일회용 모델 스위치의 경우 CLI에서 /model을 사용합니다.

/model google/gemini-3-flash-preview    # switch for this session
#... write your content...
/model openai/gpt-5.4                   # switch back

위임 작동 방식에 대한 자세한 내용은 하위 에이전트 위임을 참조하세요.

하나의 WhatsApp 번호에서 여러 에이전트 실행(채팅별 바인딩)​

시나리오: OpenClaw에는 특정 WhatsApp 채팅에 연결된 여러 독립 에이전트가 있었습니다. 하나는 가족 쇼핑 목록 그룹용이고 다른 하나는 비공개 채팅용입니다. 헤르메스가 이것을 할 수 있습니까?

현재 제한 사항: Hermes 프로필에는 각각 고유한 WhatsApp 번호/세션이 필요합니다. 동일한 WhatsApp 번호의 서로 다른 채팅에 여러 프로필을 바인딩할 수 없습니다. WhatsApp 브리지(Baileys)는 번호당 하나의 인증된 세션을 사용합니다.

해결 방법:

  1. 특성 전환이 가능한 단일 프로필을 사용하세요. 다른 AGENTS.md 컨텍스트 파일을 생성하거나 /personality 명령을 사용하여 채팅별 동작을 변경하세요. 상담원은 자신이 속한 채팅을 확인하고 이에 적응할 수 있습니다.

  2. 특수 작업에는 크론 작업을 사용하세요. 쇼핑 목록 추적기의 경우 특정 채팅을 모니터링하고 목록을 관리하는 크론 작업을 설정하세요. 별도의 에이전트가 필요하지 않습니다.

  3. 별도의 번호를 사용하세요. 완전히 독립적인 상담원이 필요한 경우 각 프로필을 자체 WhatsApp 번호와 연결하세요. Google Voice와 같은 서비스의 가상 번호가 이에 사용됩니다.

  4. 대신 Telegram 또는 Discord를 사용하세요. 이러한 플랫폼은 보다 자연스럽게 채팅별 바인딩을 지원합니다. 각 Telegram 그룹 또는 Discord 채널은 자체 세션을 가지며 동일한 계정에서 여러 봇 토큰(프로필당 하나)을 실행할 수 있습니다.

자세한 내용은 프로필 및 WhatsApp 설정을 참조하세요.

텔레그램에 표시되는 내용 제어(로그 및 추론 숨기기)​

시나리오: 최종 출력 대신 Telegram에서 게이트웨이 실행 로그, Hermes 추론 및 도구 호출 세부 정보를 볼 수 있습니다.

해결책: config.yaml의 display.tool_progress 설정은 표시되는 도구 활동의 양을 제어합니다.

display:
  tool_progress: "off"   # options: off, new, all, verbose
  • off — 최종 응답만입니다. 도구 호출도 없고 추론도 없고 로그도 없습니다.
  • new — 새로운 도구 호출이 발생하는 대로 표시합니다(간략한 한 줄).
  • all — 결과를 포함한 모든 도구 활동을 표시합니다.
  • verbose — 도구 인수 및 출력을 포함한 전체 세부정보입니다.

메시징 플랫폼의 경우 일반적으로 off 또는 new이 원하는 것입니다. config.yaml을 편집한 후 변경 사항을 적용하려면 게이트웨이를 다시 시작하세요.

/verbose 명령(활성화된 경우)을 사용하여 이 세션별 전환을 전환할 수도 있습니다.

display:
  tool_progress_command: true   # enables /verbose in the gateway

텔레그램에서 스킬 관리(슬래시 명령 제한)​

시나리오: Telegram에는 슬래시 명령 제한이 100개 있는데, 여러분의 기술이 이를 뛰어넘고 있습니다. 텔레그램에서 필요하지 않은 기술을 비활성화하고 싶지만 hermes skills config 설정이 적용되지 않는 것 같습니다.

해결책: 플랫폼별 스킬을 비활성화하려면 hermes skills config을 사용하세요. config.yaml에 씁니다:

skills:
  disabled:                     # globally disabled skills
  platform_disabled:
    telegram: [skill-a, skill-b]  # disabled only on telegram

이를 변경한 후 게이트웨이를 다시 시작하세요(hermes gateway restart 또는 종료하고 다시 시작). Telegram 봇 명령 메뉴는 시작 시 다시 작성됩니다.

팁

설명이 매우 긴 스킬은 페이로드 크기 제한 내에서 유지하기 위해 텔레그램 메뉴에서 40자로 잘립니다. 스킬이 나타나지 않으면 100개의 명령 수 제한이 아니라 전체 페이로드 크기 문제일 수 있습니다. 사용하지 않는 스킬을 비활성화하면 두 가지 모두에 도움이 됩니다.

공유 스레드 세션(여러 사용자, 하나의 대화)​

시나리오: 여러 사람이 봇을 언급하는 Telegram 또는 Discord 스레드가 있습니다. 해당 스레드의 모든 멘션이 별도의 사용자별 세션이 아닌 하나의 공유 대화의 일부가 되기를 원합니다.

현재 동작: Hermes는 대부분의 플랫폼에서 사용자 ID로 키가 지정된 세션을 생성하므로 각 사용자는 자신의 대화 컨텍스트를 얻을 수 있습니다. 이는 개인 정보 보호 및 컨텍스트 격리를 위해 설계된 것입니다.

해결 방법:

  1. Slack을 사용하세요. Slack 세션은 사용자가 아닌 스레드를 기준으로 키가 지정됩니다. 동일한 스레드에 있는 여러 사용자가 하나의 대화를 공유합니다. 이는 정확히 설명하는 동작입니다. 가장 자연스러운 핏입니다.

  2. 단일 사용자와 그룹 채팅을 사용하세요. 한 사람이 질문을 전달하는 지정된 "운영자"인 경우 세션이 통일된 상태로 유지됩니다. 다른 사람들도 함께 읽을 수 있습니다.

  3. Discord 채널을 사용하세요. Discord 세션은 채널별로 키가 지정되므로 동일한 채널에 있는 모든 사용자가 컨텍스트를 공유합니다. 공유 대화에는 전용 채널을 사용하세요.

Hermes를 다른 컴퓨터로 내보내기​

시나리오: 하나의 시스템에 기술, 크론 작업 및 메모리를 구축했으며 모든 것을 새로운 전용 Linux 상자로 옮기기를 원합니다.

해결책:

  1. 새 머신에 Hermes 에이전트를 설치합니다.

    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

  2. 소스 머신에서 전체 백업을 생성합니다.

    hermes backup

이렇게 하면 전체 ~/.hermes/ 디렉터리(구성, API 키, 메모리, 스킬, 세션 및 프로필)의 zip이 생성되어 홈 디렉터리에 ~/hermes-backup-<timestamp>.zip로 저장됩니다.

  1. zip을 새 시스템에 복사하고 가져옵니다.

    # On the source machine
    scp ~/hermes-backup-<timestamp>.zip newmachine:~/

    # On the new machine
    hermes import ~/hermes-backup-<timestamp>.zip

  2. 새 머신에서 hermes setup을 실행하여 API 키와 공급자 구성이 작동하는지 확인합니다.

단일 프로필을 다른 컴퓨터로 이동​

시나리오: 전체 설치가 아닌 하나의 특정 프로필을 이동하거나 공유하려고 합니다.

# On the source machine
hermes profile export work./work-backup.tar.gz

# Copy the file to the target machine, then:
hermes profile import./work-backup.tar.gz work

가져온 프로필에는 내보내기의 모든 구성, 메모리, 세션 및 기술이 포함됩니다. 새 시스템의 설정이 다른 경우 경로를 업데이트하거나 공급자를 통해 다시 인증해야 할 수도 있습니다.

hermes backup 대 hermes profile export​

특징hermes backuphermes profile export
사용 사례전체 머신 마이그레이션특정 프로필 포팅/공유
범위전역(전체 ~/.hermes 디렉터리)로컬(단일 프로필 디렉터리)
포함모든 프로필, 전역 구성, API 키, 세션단일 프로필: SOUL.md, 추억, 세션, 기술
자격증명포함됨 (.env 및 auth.json)제외(안전한 공유를 위해 제거됨)
형식.zip.tar.gz

수동 대체(rsync): 파일을 직접 복사하려면 코드 저장소를 제외하세요.

rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/
팁

hermes backup은 Hermes가 활발하게 실행되는 동안에도 일관된 스냅샷을 생성합니다. 복원된 아카이브에서는 gateway.pid 및 cron.pid과 같은 머신-로컬 런타임 파일을 제외합니다.

설치 후 셸을 다시 로드할 때 권한이 거부되었습니다.​

시나리오: Hermes 설치 프로그램을 실행한 후 source ~/.zshrc에서 권한 거부 오류가 발생합니다.

원인: 이 문제는 일반적으로 ~/.zshrc(또는 ~/.bashrc)에 잘못된 파일 권한이 있거나 설치 프로그램이 여기에 쓸 수 없는 경우에 발생합니다. 이는 Hermes에만 국한된 문제가 아닙니다. 쉘 구성 권한 문제입니다.

해결책:

# Check permissions
ls -la ~/.zshrc

# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc

# Then reload
source ~/.zshrc

# Or just open a new terminal window — it picks up PATH changes automatically

설치 프로그램이 PATH 줄을 추가했지만 권한이 잘못된 경우 수동으로 추가할 수 있습니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

첫 번째 에이전트 실행 시 오류 400 발생​

시나리오: 설정이 정상적으로 완료되었지만 HTTP 400으로 인해 첫 번째 채팅 시도가 실패했습니다.

원인: 일반적으로 모델 이름이 일치하지 않습니다. 구성된 모델이 공급자에 존재하지 않거나 API 키가 해당 모델에 액세스할 수 없기 때문입니다.

해결책:

# Check what model and provider are configured
hermes config show | head -20

# Re-run model selection
hermes model

# Or test with a known-good model
hermes chat -q "hello" --model anthropic/claude-opus-4.7

OpenRouter를 사용하는 경우 API 키에 크레딧이 있는지 확인하세요. OpenRouter의 400은 모델에 유료 요금제가 필요하거나 모델 ID에 오타가 있음을 의미하는 경우가 많습니다.

아직도 막혔나요?​

문제가 여기에서 다루어지지 않은 경우:

  1. 기존 문제 검색: GitHub 문제
  2. 커뮤니티에 질문: Nous Research Discord
  3. 버그 신고 제출: OS, Python 버전(python3 --version), Hermes 버전(hermes --version) 및 전체 오류 메시지를 포함합니다.