Hermes Agent: Praktyczny przewodnik referencyjny (2026)

TL;DR: Hermes Agent to otwartoźródłowy, samodoskonalący się agent AI od Nous Research. Działa jako CLI oraz jako wieloplatformowa brama komunikacyjna, przechowuje trwałą tożsamość i stałą pamięć na dysku, agreguje umiejętności, które poprawiają się wraz z użyciem, i współpracuje z każdym dostawcą LLM kompatybilnym z OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Alibaba, Hugging Face, Google lub własnym, samodzielnie hostowanym punktem końcowym.¹² Najtrudniejszą częścią dla większości nowych użytkowników jest uwierzytelnianie u dostawcy: Hermes obsługuje ~19 dostawców pierwszej klasy oraz niestandardowe punkty końcowe, a także trzy odrębne ścieżki uwierzytelniania (klucz API w .env, OAuth poprzez hermes model lub niestandardowy punkt końcowy w config.yaml). Model uwierzytelniania to pierwsza rzecz, której warto się nauczyć — cała reszta jest pochodną tego, który dostawca zostanie wybrany.

Hermes Agent działa jako pełnoprawne środowisko uruchomieniowe agenta, a nie jako nakładka czatu. Czyta system plików, wykonuje polecenia w piaskownicowych backendach, przeszukuje sieć, tworzy podagentów, uruchamia zaplanowane zadania cron, komunikuje się z Telegram/Discord/Slack/WhatsApp/Signal/e-mailem z poziomu jednego procesu bramy oraz tworzy własne umiejętności na podstawie doświadczenia.¹ CLI to interfejs terminalowy zbudowany na bazie pętli konwersacyjnej w run_agent.py; brama to długo działający proces, który kieruje wiadomości z platform komunikacyjnych przez tę samą pętlę konwersacyjną.³

Różnica między swobodnym a eksperckim użyciem Hermesa sprowadza się do pięciu systemów. Opanowanie ich sprawia, że Hermes staje się mnożnikiem siły:

1. Wybór dostawcy: w jaki sposób przepływy uwierzytelniania mapują się na wywołania API
2. Hierarchia konfiguracji: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. System narzędzi i zestawów narzędzi (toolset): co agent może robić, z ograniczeniami per platforma
4. System skills: pamięć proceduralna, którą agent tworzy i rozwija
5. Gateway + cron + profile: uruchamianie Hermesa tam, gdzie się żyje, a nie tylko tam, gdzie się jest

Najważniejsze wnioski

• Uwierzytelnianie u dostawcy ma trzy ścieżki, nie jedną. Klucz API w .env, OAuth poprzez hermes model/hermes auth lub niestandardowy punkt końcowy w config.yaml. Należy wybrać ścieżkę pasującą do dostawcy, a nie tę, która wydaje się znajoma.
• Przełączanie dostawców to jedno polecenie. hermes model interaktywnie przeprowadza przez każdego obsługiwanego dostawcę, włącznie z logowaniami OAuth, a /model provider:model przełącza w środku sesji bez utraty historii.²
• Dwa pliki stanowią powierzchnię konfiguracji edytowalną przez użytkownika. ~/.hermes/config.yaml przechowuje ustawienia, a ~/.hermes/.env przechowuje sekrety. auth.json, SOUL.md, MEMORY.md oraz skills/ są zarządzane bezpośrednio przez Hermesa — można edytować SOUL.md ręcznie, ale resztą zajmuje się sam agent.⁴
• Hermes jest następcą OpenClaw. W przypadku migracji hermes claw migrate automatycznie importuje ponad 30 kategorii stanu.⁵
• Jakość działania zależy od pomocniczego modelu. Wizja, podsumowanie stron internetowych, kompresja oraz wyrzut pamięci korzystają z osobnego pomocniczego LLM. Domyślnie jest to Gemini Flash poprzez automatyczne wykrywanie (OpenRouter → Nous → Codex) — jeśli żaden z nich nie jest skonfigurowany, te funkcje degradują się po cichu, dopóki gniazda pomocnicze nie zostaną skierowane na głównego dostawcę.⁴

Każda poniższa sekcja opiera się na oficjalnej dokumentacji w hermes-agent.nousresearch.com/docs oraz drzewie źródłowym w github.com/NousResearch/hermes-agent. Każde stwierdzenie faktograficzne posiada przypis wskazujący konkretną stronę źródłową, z której pochodzi.

Wybierz swoją ścieżkę

Jak działa Hermes: model mentalny

Hermes opiera się na pojedynczej pętli konwersacyjnej, którą może wywołać dowolny punkt wejścia. Punktami wejścia są CLI (cli.py), gateway komunikacyjny (gateway/run.py), adapter ACP do integracji z edytorem, moduł przetwarzania wsadowego oraz serwer API.³ Wszystkie one ostatecznie wywołują AIAgent.run_conversation() w run_agent.py, który:

1. Buduje prompt systemowy z SOUL.md, MEMORY.md, USER.md, umiejętności, plików kontekstowych i wskazówek dotyczących narzędzi za pośrednictwem prompt_builder.py³
2. Rozwiązuje dostawcę runtime’u przez runtime_provider.py — to na tym etapie wybierane jest uwierzytelnianie, bazowy URL i tryb API³
3. Wywołuje dostawcę w jednym z trzech trybów API: chat_completions, codex_responses lub anthropic_messages³
4. Przekazuje zwrócone wywołania narzędzi przez model_tools.py i centralny rejestr narzędzi (tools/registry.py)³
5. Wykonuje pętlę do momentu wygenerowania końcowej odpowiedzi, po czym zapisuje sesję do SQLite z FTS5³

Zrozumienie tej pętli ma znaczenie, ponieważ każda funkcja — osobowości, pamięć, umiejętności, kompresja, mechanizm awaryjny — jest podłączona do jednego z tych etapów. Gdy analizuje się klucz konfiguracyjny i zastanawia, co robi, odpowiedź zwykle brzmi: „to pokrętło na etapie 1, 2, 3 lub 4 powyższej pętli”.

Rdzeń niezależny od platformy. Jedna klasa AIAgent obsługuje CLI, gateway, ACP, przetwarzanie wsadowe i serwer API. Różnice między platformami znajdują się w punkcie wejścia, nie w samym agencie.³ Dlatego te same komendy slash działają zarówno w terminalu, jak i w Telegram — są wysyłane ze współdzielonego COMMAND_REGISTRY w hermes_cli/commands.py.⁶

Struktura katalogów to system. Hermes przechowuje wszystko w ~/.hermes/ (lub $HERMES_HOME dla niestandardowych profili):⁴

~/.hermes/
├── config.yaml        # Ustawienia (model, terminal, TTS, kompresja itp.)
├── .env               # Klucze API i sekrety
├── auth.json          # Dane uwierzytelniające dostawców OAuth (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Główna tożsamość agenta (slot #1 w prompcie systemowym)
├── memories/          # Trwała pamięć (MEMORY.md, USER.md)
├── skills/            # Wbudowane + tworzone przez agenta + zainstalowane z huba
├── cron/              # Zaplanowane zadania
├── sessions/          # Stan sesji gateway
└── logs/              # agent.log, gateway.log, errors.log (sekrety automatycznie redagowane)

Każdy z powyższych plików pełni określoną rolę; żaden z nich się nie pokrywa. Szukając odpowiedzi na pytanie „gdzie Hermes przechowuje X”, wystarczy zajrzeć do jednego z nich.

Instalacja

Instalator jednoliniowy to ścieżka dla 95% użytkowników. Obsługuje Python, uv, Node.js, ripgrep, ffmpeg, klonowanie repozytorium, środowisko wirtualne i globalną komendę hermes.⁷

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

Działa na Linuksie, macOS, WSL2 i Android/Termux (instalator automatycznie wykrywa Termux i przełącza się na przetestowany pakiet dla Androida).⁷ Natywny Windows nie jest wspierany — należy zainstalować WSL2 i uruchomić powyższą komendę stamtąd.⁷

Po zakończeniu instalacji:

source ~/.bashrc    # lub ~/.zshrc
hermes              # Rozpocznij rozmowę

Jedynym wymaganiem wstępnym jest git. Instalator automatycznie udostępnia Python 3.11 przez uv (bez potrzeby sudo), Node.js v22 (do automatyzacji przeglądarki i mostu WhatsApp), ripgrep oraz ffmpeg.⁷

Weryfikacja instalacji

hermes version      # Sprawdź wersję
hermes doctor       # Zdiagnozuj problemy z konfiguracją/zależnościami
hermes status       # Wyświetl bieżącą konfigurację + stan uwierzytelnienia
hermes dump         # Podsumowanie konfiguracji do skopiowania i wklejenia przy debugowaniu

hermes doctor wskazuje dokładnie, czego brakuje i jak to naprawić.⁷ hermes dump to komenda diagnostyczna, którą można wkleić do zgłoszenia na GitHub lub wątku na Discord, gdy potrzebna jest pomoc — to tekstowe podsumowanie całej konfiguracji z zredagowanymi sekretami.⁸

Instalacja ręczna

Dla osób potrzebujących pełnej kontroli — niestandardowa wersja Python, określone dodatki, integracja z Nix/NixOS — procedura ręczna jest opisana krok po kroku w oficjalnym przewodniku instalacji.⁷ Kluczowe opcjonalne dodatki, które można łączyć z uv pip install -e ".[<extras>]":

Komenda instalacji na Termux jest inna — używa pip z plikiem ograniczeń, a nie uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

Wynika to z faktu, że .[all] na Androidzie pobiera faster-whisper przez dodatek voice, który zależy od pakietów ctranslate2 niedostępnych dla Androida.⁷

Uwierzytelnianie i dostawcy

Hermes obsługuje około 19 dostawców pierwszej kategorii oraz niestandardowe punkty końcowe, a także trzy odrębne ścieżki uwierzytelniania. Oto cała powierzchnia uwierzytelniania, uporządkowana według ścieżki, aby można było znaleźć tę, która odpowiada posiadanym danym.

Trzy ścieżki uwierzytelniania

Każdy dostawca w Hermesie pasuje do jednego z trzech wzorców uwierzytelniania:

Ścieżka 1 — klucz API w .env. Należy umieścić klucz w ~/.hermes/.env, a Hermes odczyta go przy uruchomieniu. Wykorzystywana przez OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (oraz MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini oraz większość dostawców zewnętrznych.²

Ścieżka 2 — OAuth poprzez hermes model lub hermes auth. Uruchamia przepływ device code, otwiera przeglądarkę, zapisuje dane uwierzytelniające w ~/.hermes/auth.json (i może zaimportować istniejące poświadczenia z narzędzi takich jak Claude Code czy Codex CLI). Wykorzystywana przez Nous Portal, OpenAI Codex (konto ChatGPT), GitHub Copilot oraz Anthropic (Claude Pro/Max).²

Ścieżka 3 — niestandardowy punkt końcowy w config.yaml. Dla dowolnego API kompatybilnego z OpenAI — Ollama, vLLM, SGLang, llama.cpp, LM Studio, proxy LiteLLM, Together AI, Groq, Azure OpenAI lub własnego serwera self-hosted. Konfigurowana raz przez hermes model → Custom endpoint, a następnie utrwalana w config.yaml.²

Pełna macierz dostawców

Oto kompletna lista dostawców pierwszej kategorii wraz z dokładnym przepływem konfiguracji dla każdego z nich.²

Anthropic: trzy metody uwierzytelniania

Anthropic ma własną sekcję, ponieważ Hermes obsługuje trzy odrębne ścieżki dostępu do Claude, a wybór właściwej ma znaczenie. Z dokumentacji upstream:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

Gdy wybierze się Anthropic OAuth poprzez hermes model, Hermes preferuje magazyn poświadczeń Claude Code zamiast kopiowania tokenu do ~/.hermes/.env. W ten sposób odświeżalne poświadczenia Claude pozostają odświeżalne.² Jeśli już używa się Claude Code na tej samej maszynie, jest to najczystsza ścieżka.

Aby przypiąć Anthropic na stałe w config.yaml:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude oraz --provider claude-code również działają jako skrót dla --provider anthropic.²

GitHub Copilot: dwa tryby

Copilot jest obsługiwany w dwóch trybach: bezpośrednie API Copilot (zalecane) oraz Copilot ACP (który uruchamia lokalny CLI Copilot jako podproces).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

Uwierzytelnianie jest sprawdzane w następującej kolejności, zgodnie z dokumentacją upstream:² 1. zmienna środowiskowa COPILOT_GITHUB_TOKEN 2. zmienna środowiskowa GH_TOKEN 3. zmienna środowiskowa GITHUB_TOKEN 4. fallback gh auth token CLI 5. logowanie OAuth device code poprzez hermes model

Typ tokenu ma znaczenie. API Copilot nie obsługuje klasycznych Personal Access Tokens (ghp_*). Obsługiwane typy to tokeny OAuth (gho_*), fine-grained PATs (github_pat_* z uprawnieniem Copilot Requests) oraz tokeny GitHub App (ghu_*). Jeśli gh auth token zwraca token ghp_*, należy użyć hermes model do uwierzytelnienia poprzez OAuth.²

Chińscy dostawcy AI (wsparcie pierwszej kategorii)

Hermes ma wbudowaną obsługę z.ai/GLM, Kimi/Moonshot, MiniMax (punkty końcowe global + China) oraz Alibaba Cloud z dedykowanymi identyfikatorami dostawców.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Bazowe adresy URL można nadpisać zmiennymi środowiskowymi GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL lub DASHSCOPE_BASE_URL.²

Z.AI automatycznie wykrywa punkt końcowy. Korzystając z dostawcy z.ai/GLM, Hermes sonduje wiele punktów końcowych (global, China, warianty coding), aby znaleźć ten, który akceptuje klucz API. Działający punkt końcowy jest automatycznie buforowany — w większości przypadków GLM_BASE_URL nie jest potrzebny.²

xAI (Grok) automatycznie włącza prompt caching. Gdy bazowy adres URL zawiera x.ai, Hermes wysyła nagłówek x-grok-conv-id z każdym żądaniem, aby kierować do tego samego serwera w ramach sesji konwersacji, ponownie wykorzystując buforowane prompty systemowe i historię.² Automatycznie; bez potrzeby konfiguracji.

Polecenie hermes auth

hermes auth to polecenie zarządzania poświadczeniami dla pul i poświadczeń OAuth.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Pule poświadczeń to sposób rotacji wielu kluczy API lub tokenów OAuth dla tego samego dostawcy — przydatne do rozłożenia limitów częstotliwości na wiele kluczy bez modyfikacji kodu.⁶ Starsze polecenia hermes login / hermes logout zostały usunięte; zamiast tego należy używać hermes auth.⁶

Niestandardowe i self-hosted punkty końcowe

Hermes działa z dowolnym punktem końcowym API kompatybilnym z OpenAI. Jeśli serwer implementuje /v1/chat/completions, można skierować Hermesa na ten serwer.²

Konfiguracja interaktywna (zalecana):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

Ręczna edycja config.yaml:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Oba podejścia utrwalają konfigurację w config.yaml, który jest jedynym źródłem prawdy dla głównego modelu, dostawcy i bazowego adresu URL.² Starsze zmienne środowiskowe OPENAI_BASE_URL oraz LLM_MODEL nie są już odczytywane dla konfiguracji głównego modelu — należy używać hermes model lub bezpośrednio edytować config.yaml.² (OPENAI_BASE_URL + OPENAI_API_KEY są nadal honorowane jako fallback dla pomocniczej ścieżki routingu provider: "main", więc nie należy ich bezmyślnie usuwać, jeśli są tam używane.)⁴

Przełączanie niestandardowych punktów końcowych w trakcie sesji:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (bez nazwy modelu) odpytuje API /v1/models punktu końcowego i automatycznie wybiera model, jeśli załadowany jest dokładnie jeden — przydatne dla lokalnych serwerów uruchamiających pojedynczy model.²

Lokalne serwery LLM (szablony konfiguracji)

Dokumentacja upstream zawiera pełne przewodniki konfiguracji dla Ollama, vLLM, SGLang, llama.cpp oraz LM Studio. Oto kluczowe polecenia, które rzeczywiście będą uruchamiane. Każde z nich zostało zaprojektowane tak, aby utworzyć działający punkt końcowy, na który Hermes może być skierowany.²

Ollama — najłatwiejsza ścieżka lokalna, zero konfiguracji:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Krytyczna pułapka Ollama: Ollama domyślnie ustawia bardzo niskie długości kontekstu (4 096 tokenów przy mniej niż 24 GB VRAM). Trzeba ją zwiększyć poprzez OLLAMA_CONTEXT_LENGTH lub plik Modelfile — API kompatybilne z OpenAI nie akceptuje długości kontekstu od klienta, więc Hermes nie może jej ustawić za użytkownika.² Do użytku jako agent należy ustawić co najmniej 16k–32k.

vLLM — wysokowydajne serwowanie GPU:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Wywoływanie narzędzi wymaga --enable-auto-tool-choice oraz --tool-call-parser <name>. Obsługiwane parsery: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Bez tych flag wywołania narzędzi będą zwracane jako zwykły tekst.²

SGLang — szybkie serwowanie z RadixAttention dla ponownego użycia bufora KV:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

Pułapka SGLang: Domyślny max_tokens to 128. Należy ustawić --default-max-tokens na serwerze lub skonfigurować model.max_tokens w config.yaml, jeśli odpowiedzi są obcinane.²

llama.cpp / llama-server — CPU oraz Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja jest wymagane do wywoływania narzędzi. Bez tej flagi llama-server całkowicie ignoruje parametr tools, a model próbuje wywoływać narzędzia, wpisując JSON w tekście odpowiedzi — czego Hermes nie potrafi przetworzyć jako rzeczywistych wywołań narzędzi.²

LM Studio — aplikacja desktopowa z GUI:

Uruchom serwer z aplikacji LM Studio (zakładka Developer → Start Server) lub poprzez CLI: lms server start (uruchamia na porcie 1234) oraz lms load qwen2.5-coder --context-length 32768.² Następnie skieruj hermes model na http://localhost:1234/v1.

Krytyczna pułapka LM Studio: LM Studio odczytuje długość kontekstu z metadanych modelu, ale wiele modeli GGUF zgłasza domyślne wartości 2048 lub 4096. Zawsze należy jawnie ustawić długość kontekstu w ustawieniach modelu LM Studio — kliknij ikonę koła zębatego obok selektora modelu, ustaw “Context Length” na co najmniej 16384 (najlepiej 32768) i przeładuj model.²

Nazwani niestandardowi dostawcy

Jeśli pracuje się z wieloma niestandardowymi punktami końcowymi (na przykład lokalnym serwerem dev i zdalnym serwerem GPU), można je zdefiniować jako nazwanych niestandardowych dostawców w config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Następnie można między nimi przełączać się w trakcie sesji, używając potrójnej składni:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

Można również wybrać nazwanych niestandardowych dostawców z interaktywnego menu hermes model.²

Architektura pluggable provider (v0.13.0+)

v0.13.0 wprowadza ProviderProfile ABC oraz katalog plugins/model-providers/, dzięki czemu zewnętrzni dostawcy inferencji mogą być dodawani bez modyfikacji rdzenia.¹⁸ Jeśli dostawca obsługuje tryb API kompatybilny z OpenAI, Anthropic lub Codex, można zaimplementować podklasę ProviderProfile, która deklaruje ścieżkę uwierzytelniania, bazowy adres URL, katalog modeli oraz nagłówki bufora; Hermes rozwiązuje ją tą samą ścieżką runtime_provider.py, której używają wbudowani dostawcy. To architektoniczna zmiana stojąca za rozszerzeniem dostawców w v0.13.0: zamiast edytować kod rdzenia w celu dodania dostawcy, dostarcza się wtyczkę.

Wykrywanie długości kontekstu

Dwa ustawienia są stale mylone, zgodnie z dokumentacją upstream:²

• context_length — całkowite okno kontekstu (połączony budżet tokenów wejście + wyjście, np. 1 000 000 dla Claude Opus 4.7 lub 200 000 dla Sonnet 4.6). Hermes używa tej wartości do decydowania, kiedy kompresować historię.
• model.max_tokens — limit wyjścia (maksymalna liczba tokenów, jaką model może wygenerować w pojedynczej odpowiedzi). Niezwiązany z długością historii.

Należy ustawić context_length, gdy automatyczne wykrywanie zwraca niewłaściwy rozmiar okna:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes używa łańcucha rozwiązywania z wielu źródeł do wykrywania okien kontekstu: nadpisanie konfiguracji → niestandardowy dostawca per-model → trwała pamięć podręczna → endpoint /models → Anthropic /v1/models → API OpenRouter → Nous Portal → models.dev (rejestr utrzymywany przez społeczność dla ponad 3800 modeli) → wartości domyślne (128K).² System uwzględnia dostawcę, więc ten sam model może mieć różne limity kontekstu w zależności od tego, kto go serwuje (np. claude-opus-4.6 ma 1M na Anthropic direct, ale 128K na GitHub Copilot).²

Rotacja dostawców i fallback

Pule poświadczeń. Gdy posiada się wiele kluczy API dla tego samego dostawcy, należy skonfigurować strategię rotacji poprzez hermes auth. W ten sposób rozkłada się limity częstotliwości na wiele kluczy.⁶

Model fallback. Skonfiguruj zapasowy provider:model, na który Hermes automatycznie przełącza się, gdy główny model zawiedzie (limity częstotliwości, błędy serwera, niepowodzenia uwierzytelniania):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

Fallback zamienia model i dostawcę w trakcie sesji bez utraty konwersacji. Uruchamia się co najwyżej raz na sesję.² Obsługiwani dostawcy fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Modele pomocnicze

Hermes używa lekkich modeli “pomocniczych” do zadań pobocznych: analizy obrazu, podsumowywania stron internetowych, analizy zrzutów ekranu przeglądarki, klasyfikacji zatwierdzania niebezpiecznych poleceń, kompresji kontekstu, podsumowywania wyszukiwania sesji, dopasowywania umiejętności, wysyłania narzędzi MCP oraz opróżniania pamięci.⁴ Domyślnie używają one Gemini Flash poprzez automatyczne wykrywanie (OpenRouter → Nous → Codex).

Można skonfigurować, jakiego modelu i dostawcy używa każde zadanie pomocnicze. Każdy slot pomocniczy używa tych samych trzech parametrów: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

Opcja dostawcy "main" oznacza “użyj dowolnego dostawcy, którego używa mój główny agent” — ważna wyłącznie wewnątrz konfiguracji auxiliary:, compression: oraz fallback_model:. Nie jest prawidłowa dla nadrzędnego ustawienia model.provider. Jeśli używa się niestandardowego punktu końcowego kompatybilnego z OpenAI jako głównego modelu, należy ustawić provider: custom w sekcji model:.⁴

Dlaczego to ma znaczenie: jeśli skonfigurowano tylko Anthropic OAuth (bez klucza OpenRouter), wizja, podsumowywanie webu i kompresja będą degradować się lub zawodzić, ponieważ domyślny pomocniczy łańcuch fallback najpierw próbuje OpenRouter. Należy dodać OPENROUTER_API_KEY dla zadań pomocniczych lub przekonfigurować każdy slot pomocniczy, aby używał głównego dostawcy:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

To najczęstsza pułapka typu “moje funkcje po cichu nie działają” dla nowych użytkowników Hermesa.

System konfiguracji

Hermes ma warstwowy system konfiguracji. Zrozumienie kolejności pierwszeństwa jest kluczowe, ponieważ wyższe warstwy nadpisują niższe, a jedną z warstw jest globalny rejestr dostawców, którego nie widać w config.yaml.

Układ plików konfiguracyjnych

Zgodnie z dokumentacją upstream, oto pliki tworzące konfigurację Hermes:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs .env — gdy obie wartości są ustawione, config.yaml wygrywa dla ustawień niebędących sekretami.⁴ Zasada jest następująca: - Sekrety (klucze API, tokeny botów, hasła) → .env - Wszystko inne (model, backend terminala, ustawienia kompresji, limity pamięci, toolsets) → config.yaml

Do sekretów można odwoływać się z poziomu config.yaml, używając interpolacji w stylu powłoki:⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

Zarządzanie konfiguracją

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Przykłady:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check i hermes config migrate to polecenia, które warto uruchomić po każdym hermes update — wychwytują one nowo dodane opcje konfiguracyjne, których plik użytkownika jeszcze nie zawiera.⁶

Pierwszeństwo konfiguracji

Hermes ładuje konfigurację z kilku źródeł. Gdy wiele źródeł ustawia tę samą wartość, wygrywa źródło o wyższym priorytecie:⁴

1. Argumenty CLI — hermes chat --model anthropic/claude-sonnet-4 (nadpisanie dla pojedynczego wywołania)
2. Zmienne środowiskowe — stosowane przy starcie procesu
3. config.yaml — główny plik ustawień
4. .env — wyłącznie sekrety
5. Wbudowane wartości domyślne — stosowane, gdy żadne inne źródło nie ustawia wartości

Flagi CLI zawsze wygrywają dla tego pojedynczego wywołania. config.yaml stanowi długoterminowe źródło prawdy.

Lokalizacja (v0.13.0+)

v0.13.0 dodaje 7 lokalizacji dla komunikatów CLI i gateway: chiński (uproszczony), japoński, niemiecki, hiszpański, francuski, ukraiński oraz turecki.¹⁸ Dokumentacja jest obecnie zlokalizowana wyłącznie w zh-Hans. Lokalizacja jest rozpoznawana na podstawie zmiennych środowiskowych LC_ALL / LANG lub jawnego klucza locale: w config.yaml. Angielski pozostaje wartością domyślną oraz źródłem prawdy dla każdego ciągu, którego tłumaczenie jeszcze nie obejmuje.

Profile — wiele izolowanych instancji Hermes

Profile umożliwiają korzystanie z wielu izolowanych instancji Hermes, z których każda ma własną konfigurację, sesje, skills, pamięć oraz PID gateway. W ten sposób można uruchamiać „służbowy Hermes” i „prywatny Hermes” obok siebie tak, aby żadna instancja nie widziała stanu drugiej.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Każdy profile otrzymuje własny HERMES_HOME (domyślnie ~/.hermes-<name>/), dzięki czemu wiele profili może jednocześnie uruchamiać gateway, nie wchodząc sobie w drogę.⁶³

Polecenia CLI

Ta sekcja stanowi praktyczne kompendium poleceń najwyższego poziomu CLI. Autorytatywne źródło oparte na kodzie źródłowym znajduje się w oficjalnej dokumentacji CLI Commands Reference.⁶

Opcje globalne

hermes [global-options] <command> [subcommand/options]

Polecenia najwyższego poziomu

hermes chat — główny punkt wejścia

Wywołanie hermes bez argumentów uruchamia interaktywny czat. hermes chat to forma jawna z dodatkowymi opcjami:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Kluczowe opcje:

hermes setup — pełny kreator konfiguracji

Uruchamia pełny kreator konfiguracji lub przechodzi bezpośrednio do wybranej sekcji:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — strukturowane odpytywanie logów

hermes logs oferuje znacznie więcej niż zwykłe tail -f na plikach logów, ponieważ umożliwia jednoczesne filtrowanie według poziomu, ID sesji i zakresu czasowego.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Pliki logów znajdują się w ~/.hermes/logs/:⁶ - agent.log — pełna aktywność agenta (wywołania API, dyspozycja narzędzi, cykl życia sesji, poziom INFO+) - errors.log — wyłącznie ostrzeżenia i błędy (przefiltrowany podzbiór agent.log) - gateway.log — aktywność bramy komunikacyjnej (połączenia z platformami, dyspozycja, webhooki)

Rotacja odbywa się automatycznie za pomocą RotatingFileHandler z Python — pliki rotowane to agent.log.1, agent.log.2 itd.⁶

hermes doctor — diagnostyka

hermes doctor [--fix] to pierwsze polecenie, które warto uruchomić w przypadku problemów. Sprawdza poprawność konfiguracji, obecność zależności, dostępność kluczy API, status usług i może podjąć automatyczne naprawy za pomocą flagi --fix.⁶

Aby udostępnić diagnostykę innej osobie, należy użyć hermes dump — generuje zwięzłe podsumowanie w formacie tekstowym z zamaskowanymi kluczami API, gotowe do wklejenia w zgłoszenie na GitHub lub wątek na Discord.⁶

Polecenia ukośnikowe

Polecenia ukośnikowe działają wewnątrz aktywnej sesji czatu (CLI lub platforma komunikacyjna). Są one rozsyłane ze współdzielonego rejestru COMMAND_REGISTRY w pliku hermes_cli/commands.py, dlatego większość poleceń działa identycznie na różnych powierzchniach.⁹

Sterowanie sesją

Konfiguracja i model

Polecenie /model to koń roboczy do przełączania dostawców w trakcie sesji:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

Narzędzia, skills i informacje

Dynamiczne polecenia ukośnikowe skills

Każda zainstalowana skill jest automatycznie udostępniana jako polecenie ukośnikowe:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Można również zdefiniować szybkie polecenia (quick commands) w pliku config.yaml, które przypisują krótką nazwę do dłuższego promptu:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Następnie wystarczy wpisać /review, /deploy lub /morning w CLI.

Dopasowanie po prefiksie

Polecenia obsługują dopasowanie po prefiksie: wpisanie /h zostanie rozwiązane do /help, a /mod do /model. Gdy prefiks jest niejednoznaczny, wygrywa pierwsza rejestracja w kolejności rejestru. Pełne nazwy poleceń oraz zarejestrowane aliasy zawsze mają pierwszeństwo przed dopasowaniami po prefiksie.⁹

Polecenia specyficzne dla platform komunikacyjnych

Niektóre polecenia działają wyłącznie na platformach komunikacyjnych (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — wyświetla informacje o sesji
• /sethome (alias /set-home) — oznacza bieżący czat jako home platformy
• /approve [session|always] — zatwierdza oczekujące niebezpieczne polecenie
• /deny — odrzuca oczekujące niebezpieczne polecenie
• /update — aktualizuje Hermes Agent do najnowszej wersji
• /commands [page] — przegląda wszystkie polecenia i skills (z podziałem na strony)

Niektóre z kolei są dostępne wyłącznie w CLI: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Narzędzia i zestawy narzędzi

Hermes jest dostarczany z obszernym wbudowanym rejestrem narzędzi obejmującym wyszukiwanie w sieci, automatyzację przeglądarki, wykonywanie poleceń terminala, edycję plików, pamięć, delegowanie, trening RL, dostarczanie wiadomości, integrację z Home Assistant i wiele innych.¹⁰ Narzędzia są zorganizowane w logiczne zestawy narzędzi, które można włączać lub wyłączać dla każdej platformy.

Kategorie wysokiego poziomu

Typowe nazwy zestawów narzędzi obejmują web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant oraz rl.¹⁰

Zarządzanie narzędziami

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Narzędzia można również przełączać w trakcie sesji za pomocą /tools disable <name> oraz /tools enable <name>, co resetuje sesję, aby nowy zestaw narzędzi został zastosowany.⁹

Backendy terminala

Narzędzie terminala umożliwia wykonywanie poleceń w sześciu różnych środowiskach:¹⁰

Backend można zmienić poleceniem hermes config set terminal.backend <name> lub w pliku config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

Backend SSH (zalecany ze względów bezpieczeństwa — agent nie może modyfikować własnego kodu):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Backend Docker:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Zasoby kontenera (dotyczy docker, singularity, modal, daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

Przy ustawieniu container_persistent: true zainstalowane pakiety, pliki i konfiguracja przetrwają między sesjami.¹⁰

Wszystkie backendy kontenerowe działają z hardeningiem bezpieczeństwa: system plików root tylko do odczytu (Docker), wszystkie uprawnienia (capabilities) Linuksa odrzucone z wyjątkiem DAC_OVERRIDE, CHOWN oraz FOWNER, brak eskalacji uprawnień, limity PID (256 procesów), pełna izolacja przestrzeni nazw, trwały obszar roboczy poprzez wolumeny.¹⁰

Procesy w tle

Narzędzie terminala wspiera wykonywanie w tle z jawnym zarządzaniem procesami:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

Tryb PTY (pty=true) umożliwia korzystanie z interaktywnych narzędzi CLI, takich jak Codex i Claude Code.¹⁰

Sudo

Jeśli polecenie wymaga sudo, Hermes poprosi o hasło (zostanie ono zapamiętane na czas sesji). Można też ustawić SUDO_PASSWORD w pliku ~/.hermes/.env.¹⁰

Multi-Agent Kanban (v0.13.0+)

v0.13.0 czyni współpracę wieloagentową prymitywem pierwszej klasy: trwała tablica Kanban, która śledzi zadania, ich status oraz tożsamość wykonawców pomiędzy agentami i przez restartami.¹⁸ To właśnie tablica sprawia, że rój pracowników Hermes faktycznie kończy pracę, zamiast utykać na martwych przekazaniach.

Tablica Kanban naturalnie współgra z /goal (pętla Ralph z zablokowanym celem) po stronie celu oraz z istniejącym narzędziem delegate_task po stronie spawnowania. Rezultatem jest wzorzec roju, w którym każdy agent dzieli jedno źródło prawdy o tym, co robić dalej, kto to robi i co jest zablokowane.

System skills

Skills to dokumenty wiedzy ładowane na żądanie, które agent może wczytać, gdy są potrzebne. Stosują wzorzec progresywnego ujawniania, aby zminimalizować zużycie tokenów i są zgodne ze standardem otwartym agentskills.io.¹¹

Wszystkie skille znajdują się w ~/.hermes/skills/ — to katalog główny i źródło prawdy. Przy świeżej instalacji dołączone skille są kopiowane z repozytorium. Skille zainstalowane z huba oraz utworzone przez agenta również trafiają tutaj.¹¹

Progresywne ujawnianie

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

Agent ładuje pełną zawartość skilla tylko wtedy, gdy faktycznie jej potrzebuje.¹¹

Format SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Weryfikacja
Jak potwierdzić, że zadziałało.

Aktywacja warunkowa

Skills mogą się ujawniać lub ukrywać w zależności od tego, jakie narzędzia są dostępne. Jest to najbardziej przydatne w przypadku skills awaryjnych — darmowych lub lokalnych alternatyw, które powinny pojawiać się tylko wtedy, gdy narzędzie premium jest niedostępne:¹¹

Przykład: wbudowany skill duckduckgo-search używa fallback_for_toolsets: [web]. Po ustawieniu FIRECRAWL_API_KEY toolset web jest dostępny i agent korzysta z web_search — skill DuckDuckGo pozostaje ukryty. Bez klucza API skill DuckDuckGo automatycznie pojawia się jako rozwiązanie awaryjne.¹¹

Skills zarządzane przez agenta

Agent może tworzyć, aktualizować i usuwać własne skills za pomocą narzędzia skill_manage. To jest pamięć proceduralna agenta — gdy wypracuje on nietrywialny przepływ pracy, zapisuje to podejście jako skill do przyszłego wykorzystania.¹¹

Kiedy agent tworzy skills:¹¹ - Po pomyślnym ukończeniu złożonego zadania (5+ wywołań narzędzi) - Gdy napotkał błędy lub ślepe zaułki i znalazł działającą ścieżkę - Gdy użytkownik skorygował jego podejście - Gdy odkrył nietrywialny przepływ pracy

Akcje:¹¹

Skill Hub

Przeglądanie, wyszukiwanie, instalowanie i zarządzanie skills z rejestrów online:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Zintegrowane źródła hub:¹¹

Domyślne tapy GitHub (do przeglądania bez konfiguracji): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Skanowanie bezpieczeństwa

Wszystkie skills instalowane z huba przechodzą przez skaner bezpieczeństwa, który sprawdza eksfiltrację danych, prompt injection, destrukcyjne polecenia, sygnały supply-chain i inne zagrożenia.¹¹

Poziomy zaufania:¹¹

--force może nadpisać blokady polityki dla skills społecznościowych, jeśli nie są one niebezpieczne. Nie nadpisuje werdyktu skanowania dangerous.¹¹

Zewnętrzne katalogi skills

Można wskazać Hermesowi dodatkowe katalogi skills skanowane obok lokalnego:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Ścieżki obsługują rozwijanie ~ oraz podstawianie zmiennych środowiskowych ${VAR}. Zewnętrzne katalogi są tylko do odczytu — gdy agent tworzy lub edytuje skill, zawsze zapisuje go do ~/.hermes/skills/. Lokalne pierwszeństwo wygrywa, jeśli nazwa skilla istnieje w obu miejscach.¹¹

Pamięć trwała

Hermes posiada ograniczoną, kuratorowaną pamięć, która utrzymuje się pomiędzy sesjami. Pamięć agenta składa się z dwóch plików, oba przechowywane w ~/.hermes/memories/:¹²

Oba są wstrzykiwane do system prompt jako zamrożona migawka na początku sesji. Agent zarządza własną pamięcią poprzez narzędzie memory — add, replace lub remove.¹²

Wzorzec zamrożonej migawki: wstrzyknięcie do system prompt jest przechwytywane raz na początku sesji i nigdy nie zmienia się w trakcie. Jest to celowe — zachowuje to prefix cache LLM dla wydajności. Zmiany dokonane w trakcie sesji są zapisywane na dysk natychmiast, ale pojawiają się w system prompt dopiero w kolejnej sesji.¹²

Co zapisywać

Zapisywać te informacje (agent robi to proaktywnie):¹² - Preferencje użytkownika: „Wolę TypeScript od JavaScript” → user - Fakty środowiskowe: „Ten serwer pracuje pod Debian 12 z PostgreSQL 16” → memory - Korekty: „Nie używaj sudo dla poleceń Docker, użytkownik jest w grupie docker” → memory - Konwencje: „Projekt używa tabulatorów, 120-znakowej szerokości linii, docstringów w stylu Google” → memory - Ukończona praca: „Zmigrowano bazę danych z MySQL do PostgreSQL w dniu 2026-01-15” → memory

Pomijać te informacje:¹² - Trywialne/oczywiste informacje - Łatwe do ponownego odkrycia fakty - Surowe zrzuty danych (zbyt duże dla pamięci) - Efemeryczne dane specyficzne dla sesji - Informacje już znajdujące się w plikach kontekstowych

Wyszukiwanie sesji

Poza MEMORY.md i USER.md agent może przeszukiwać swoje wcześniejsze rozmowy za pomocą narzędzia session_search. Wszystkie sesje CLI i komunikatorów są przechowywane w SQLite (~/.hermes/state.db) z pełnotekstowym wyszukiwaniem FTS5. Zapytania zwracają istotne wcześniejsze rozmowy z podsumowaniem przez Gemini Flash.¹²

Zewnętrzni dostawcy pamięci

Aby zapewnić głębszą pamięć trwałą wykraczającą poza MEMORY.md i USER.md, Hermes jest wyposażony w osiem zewnętrznych wtyczek dostawców pamięci: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover oraz Supermemory.¹²

Zewnętrzni dostawcy działają równolegle z pamięcią wbudowaną (nigdy jej nie zastępując) i dodają możliwości takie jak grafy wiedzy, wyszukiwanie semantyczne, automatyczne wyodrębnianie faktów oraz modelowanie użytkownika między sesjami:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

W danym momencie aktywny może być tylko jeden zewnętrzny dostawca. Pamięć wbudowana jest zawsze aktywna.⁶

Automatyczne wznawianie sesji (v0.13.0+)

v0.13.0 sprawia, że przerwanie pracy agenta w trakcie staje się przeżywalne. Gateway automatycznie wznawia przerwane sesje po restarcie; restarty /update zachowują stan sesji przez aktualizację; przeładowania plików źródłowych podczas pracy deweloperskiej utrzymują aktywną sesję przy życiu, zamiast wymuszać nową.¹⁸ Praktyczny efekt: długo działające zadania gateway oraz cron-driven joby nie resetują już swojego okna kontekstu, gdy proces zostaje zrestartowany.

Checkpoints v2 (v0.13.0+)

Trwałość stanu została przepisana w v0.13.0 jako projekt single-store z prawdziwym przycinaniem, zabezpieczeniami dyskowymi i bez sierot shadow repos.¹⁸ Poprzedni system checkpointów akumulował stan na dysku w długo działających profilach; magazyn v2 nakłada twardy limit na lokalne przechowywanie checkpointów i usuwa zduplikowaną księgowość, która napędzała ten wzrost. Nie jest wymagana żadna zmiana konfiguracji widoczna dla użytkownika; następny zapis checkpointu używa ścieżki v2.

Osobowość i SOUL.md

SOUL.md to podstawowa tożsamość instancji Hermes. Zajmuje miejsce #1 w prompcie systemowym, zastępując zakodowaną na stałe tożsamość domyślną.¹³

Hermes automatycznie tworzy domyślny plik SOUL.md w lokalizacji ~/.hermes/SOUL.md (lub $HERMES_HOME/SOUL.md dla profili niestandardowych). Istniejące pliki użytkownika nigdy nie są nadpisywane. Hermes wczytuje SOUL.md wyłącznie z HERMES_HOME — nie szuka go w bieżącym katalogu roboczym. Dzięki temu osobowość pozostaje przewidywalna w różnych projektach.¹³

Co należy umieścić w SOUL.md

Należy go używać do trwałych wskazówek dotyczących głosu i osobowości:¹³ - ton - styl komunikacji - poziom bezpośredniości - domyślny styl interakcji - czego unikać pod względem stylistycznym - jak Hermes powinien obsługiwać niepewność, niezgodę, niejednoznaczność

Mniej nadaje się do:¹³ - jednorazowych instrukcji projektowych - ścieżek plików - konwencji repozytorium - tymczasowych szczegółów przepływu pracy

Te informacje należą do AGENTS.md, a nie do SOUL.md.

SOUL.md a AGENTS.md

To najważniejsze rozróżnienie w zarządzaniu tożsamością Hermes:¹³

SOUL.md — tożsamość, ton, styl, domyślne ustawienia komunikacji, zachowanie na poziomie osobowości.

AGENTS.md — architektura projektu, konwencje kodowania, preferencje narzędzi, przepływy pracy specyficzne dla repozytorium, polecenia, porty, ścieżki, uwagi dotyczące wdrożenia.

Przydatna zasada: jeśli coś ma podążać za Panem/Panią wszędzie, należy do SOUL.md. Jeśli należy do projektu, należy do AGENTS.md.¹³

Wbudowane osobowości

Hermes jest dostarczany z wbudowanymi osobowościami, na które można się przełączyć za pomocą /personality:¹³

Niestandardowe osobowości w config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Następnie można się przełączyć poleceniem /personality codereviewer.

SOUL.md a /personality

SOUL.md to bazowy głos. /personality to nakładka na poziomie sesji.¹³ Warto zachować pragmatyczny domyślny SOUL.md, a następnie używać /personality teacher do rozmowy szkoleniowej lub /personality creative do burzy mózgów.

Nous Tool Gateway (v0.10.0+)

Od wersji Hermes Agent v0.10.0 (2026-04-16) płatni subskrybenci Nous Portal uzyskują zarządzany dostęp do wyselekcjonowanego zestawu narzędzi za pośrednictwem swoich istniejących poświadczeń Portal — bez dodatkowych kluczy API do zarządzania.²⁰ Sam CLI Hermes pozostaje na licencji MIT i jest w pełni open source. Zmieniło się to, że uwierzytelnianie Portal odblokowuje teraz coś więcej niż tylko inferencję modelu.

Co znajduje się w gateway

Jak to działa

Gateway jest opcjonalny dla każdego narzędzia za pomocą nowego pola konfiguracyjnego use_gateway. Jeśli posiada Pan/Pani poświadczenia Portal w hermes auth oraz gateway jest włączony dla danego narzędzia, wywołania tego narzędzia są kierowane przez Portal. W przeciwnym razie używany jest bezpośredni klucz API (jeśli jest obecny).

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Pierwszeństwo w czasie wykonywania: gdy gateway jest dostępny i narzędzie ma use_gateway: true, Hermes preferuje gateway nawet wtedy, gdy skonfigurowany jest również bezpośredni klucz API. Ma to znaczenie dla rozliczeń — wywołania przez gateway są pobierane z subskrypcji Portal, a nie ze stanu konta bezpośredniego klucza API.

Włączanie gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

Nie istnieje osobne polecenie hermes subscribe ani hermes login --portal. Subskrypcja jest wykrywana automatycznie na podstawie poświadczeń Portal OAuth, które już znajdują się w hermes auth.

Cennik i dostęp

Cennik i nazwy poziomów są publikowane na stronie cennika Nous Portal (https://portal.nousresearch.com/pricing). Niniejszy przewodnik nie wylicza poziomów, ponieważ leżą one w gestii produktu Portal, a nie CLI Hermes, i zmieniają się niezależnie od wydań Hermes. Można się zarejestrować pod adresem https://portal.nousresearch.com/ i sprawdzić aktualne poziomy na stronie cennika.

Informacja o wycofaniu

• Zmienna środowiskowa HERMES_ENABLE_NOUS_MANAGED_TOOLS została usunięta w v0.10.0. Zarządzane narzędzia są teraz włączane za pomocą pola konfiguracyjnego use_gateway przypisanego do danego narzędzia i podlegają stanowi subskrypcji Portal.²⁰

Kontekst: czym to wydanie nie jest

CLI Hermes Agent nie jest ograniczony subskrypcją. Projekt nadal jest na licencji MIT, wszystkie podstawowe funkcje (CLI, skille, pamięć, messaging gateway, cron, MCP, lokalny dashboard, BYOK dla każdego dostawcy) działają od początku do końca bez konieczności płacenia komukolwiek. v0.10.0 dodaje wygodną ścieżkę dla użytkowników, którzy już płacą za Nous Portal — nie usuwa niczego z bezpłatnej ścieżki.

Messaging Gateway

Hermes może działać jako długo działający proces gateway, który łączy się z 20 platformami komunikacyjnymi z poziomu jednego procesu gateway: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat oraz ogólny adapter Webhook.^3191718 v0.9.0 dodała iMessage poprzez BlueBubbles (automatyczna rejestracja webhooków, kreator konfiguracji, odporność na awarie) oraz natywną obsługę WeChat przez iLink Bot API z trybem callback WeCom dla aplikacji firmowych.¹⁶ v0.11.0 dodała QQBot.¹⁹ v0.12.0 dodała Microsoft Teams i Tencent Yuanbao.¹⁷ v0.13.0 dodała Google Chat jako 20. platformę, korzystającą z tej samej architektury wtyczkowych adapterów; IRC i Microsoft Teams również zostały zmigrowane na nowy wzorzec adapterów z ogólnymi punktami zaczepienia wtyczek env_enablement_fn / cron_deliver_env_var.¹⁸

Konfiguracja

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

Interaktywna konfiguracja prowadzi przez podłączenie każdej platformy: tokeny API, identyfikatory botów, mapowania kanałów, listy dozwolonych.⁶

Jak przepływają wiadomości

Z dokumentacji architektury upstream:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Każda platforma komunikacyjna przechodzi przez tę samą pętlę konwersacji AIAgent co CLI. Dlatego polecenia ukośnikowe działają identycznie w obu miejscach i dlatego zadanie cron zaplanowane w Telegramie może dostarczyć wynik na Discorda — różnica między platformami istnieje jedynie na brzegu.³

Autoryzacja użytkownika i parowanie

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Kody parowania chronią przed tym, by przypadkowi obcy mogli rozmawiać z gatewayem. Użytkownik wysyła kod parowania ze swojej platformy komunikacyjnej; zatwierdza go Pan/Pani poleceniem hermes pairing approve; od tego momentu jest autoryzowany.⁶

Zadania zaplanowane (Cron)

Hermes ma pierwszoklasowy system cron, w którym zadania są zadaniami agenta, a nie poleceniami powłoki. Każde zaplanowane zadanie przechodzi przez świeżą instancję AIAgent ze skonfigurowanym promptem, opcjonalnymi dołączonymi skillami i dostarcza wyniki na dowolną platformę:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Lub utworzyć je konwersacyjnie wewnątrz czatu komunikacyjnego:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

Agent skonfiguruje zadanie cron za pomocą swoich narzędzi. Zadania są zachowywane w JSON i przetrwają restarty.³

Integracja z MCP

Hermes obsługuje Model Context Protocol zarówno jako klient, jak i serwer:⁶

Jako klient — można połączyć Hermes z zewnętrznymi serwerami MCP, aby rozszerzyć dostępny zestaw narzędzi:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

Lub ręcznie w pliku config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Jako serwer — można udostępnić rozmowy Hermes innym agentom:

hermes mcp serve
hermes mcp serve -v    # Verbose

Kompresja kontekstu

Hermes automatycznie kompresuje długie rozmowy, aby mieściły się w oknie kontekstowym wybranego modelu. Sumaryzator kompresji jest osobnym wywołaniem LLM — można skierować go na dowolnego dostawcę lub punkt końcowy.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Opcje dostawcy:⁴

summary_model musi obsługiwać długość kontekstu co najmniej taką samą, jak model główny, ponieważ otrzymuje pełną środkową część rozmowy do skompresowania.⁴

Ostrzeżenia o presji budżetu

Gdy agent pracuje nad złożonym zadaniem z wieloma wywołaniami narzędzi, może wyczerpać swój budżet iteracji (domyślnie: 90 tur) bez świadomości tego faktu. Mechanizm presji budżetu automatycznie ostrzega model:⁴

Limity czasu strumienia

Połączenie strumieniujące LLM ma dwie warstwy limitów czasu, które automatycznie dostosowują się do lokalnych dostawców (localhost, adresy LAN):⁴

Limit odczytu socketu zostaje podniesiony do 30 minut dla lokalnych punktów końcowych, ponieważ lokalne LLM mogą potrzebować kilku minut na wstępne przetworzenie dużych kontekstów przed wygenerowaniem pierwszego tokenu.⁴

Lokalny panel WWW (v0.9.0+)

Panel oparty na przeglądarce do lokalnego zarządzania Hermes Agent. Pozwala konfigurować ustawienia, monitorować sesje, przeglądać skille i zarządzać gateway bez konieczności edytowania plików konfiguracyjnych ani korzystania z terminala.¹⁶ Uruchamia się go poleceniem hermes dashboard. Jest to najprostsza ścieżka wdrożenia dla nowych użytkowników preferujących GUI.

Monitorowanie procesów w tle (v0.9.0+)

watch_patterns umożliwia ustawianie wzorców monitorowanych w wyjściu procesu działającego w tle oraz otrzymywanie powiadomień w czasie rzeczywistym, gdy nastąpi dopasowanie.¹⁶ Można monitorować błędy, czekać na konkretne zdarzenia („listening on port”) lub obserwować logi kompilacji — wszystko bez odpytywania. W połączeniu z notify_on_complete z v0.8.0 (powiadamiającym o zakończeniu zadania w tle) Hermes zyskuje pełną warstwę obserwowalności procesów w tle.¹⁵

Wymienny silnik kontekstu (v0.9.0+)

Zarządzanie kontekstem stało się obecnie wymiennym slotem dostępnym poprzez hermes plugins. Można podstawić niestandardowe silniki kontekstu, które kontrolują, co agent widzi w każdej turze — filtrowanie, sumaryzacja czy iniekcja kontekstu specyficznego dla domeny.¹⁶ Rozwiązanie to oddziela strategię kontekstu od głównej pętli agenta, umożliwiając dostosowanie kontekstu do konkretnego projektu lub domeny.

Kopia zapasowa i przywracanie (v0.9.0+)

hermes backup tworzy pełne archiwum konfiguracji, sesji, skilli i pamięci. hermes import przywraca dane z archiwum kopii zapasowej.¹⁶ Funkcja ta służy do migracji między maszynami, tworzenia migawek przed istotnymi zmianami lub udostępniania sprawdzonej konfiguracji członkom zespołu.

Wsparcie dla Termux / Android (v0.9.0+)

Hermes działa natywnie na Androidzie poprzez Termux. Dostosowane ścieżki instalacyjne, optymalizacje TUI dla ekranów mobilnych, obsługa głosowych backendów oraz polecenie /image działają bezpośrednio na urządzeniu.¹⁶

Wzmocnienie bezpieczeństwa (v0.13.0+)

W wersji v0.13.0 zamknięto 8 problemów bezpieczeństwa P0 oraz zmieniono jedno ustawienie domyślne na korzyść użytkownika.¹⁸

Osoby utrzymujące wdrożenie Hermes powinny traktować v0.13.0 jako aktualizację o znaczeniu bezpieczeństwa, a nie jedynie wydanie z nowymi funkcjami. Obejście między guildami w Discord oraz dwa okna TOCTOU pozostają możliwe do wykorzystania w poprzednich wersjach.

Architektura dla praktyków

Ta sekcja jest przeznaczona dla osób, które chcą zrozumieć, co dzieje się pod maską, aby móc to debugować, rozszerzać lub wnioskować o wydajności. Stanowi syntezę dokumentacji architektury upstream.³

Punkty wejścia → AIAgent

Każdy punkt wejścia w Hermes ostatecznie wywołuje AIAgent.run_conversation():

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagram zaadaptowany z dokumentacji architektury upstream.³

„47 tools / 20 toolsets” vs „28 tools” w Państwa banerze. Liczba „47 tools” to całkowity rejestr narzędzi w repozytorium upstream — każde narzędzie, dla którego Hermes dostarcza kod źródłowy, we wszystkich toolsetach. Faktycznie uruchomiony CLI pokaże mniejszą liczbę w banerze startowym (instalacja, na której weryfikowałem ten przewodnik, raportuje 28 tools / 89 skills). To nie błąd. Wiele toolsetów jest opcjonalnych i musi zostać jawnie włączonych w config.yaml w sekcji toolsets: — adaptery platform komunikacyjnych, automatyzacja przeglądarki, cięższe narzędzia do scrapingu itd. Suma w rejestrze to „co jest dostępne”; liczba w banerze to „co jest włączone w bieżącym profilu”. Można sprawdzić, które toolsety są aktywne, za pomocą polecenia hermes tools --list oraz włączyć lub wyłączyć poszczególne toolsety w bloku toolsets: w pliku ~/.hermes/config.yaml (lub poleceniami /tools list / /tools enable <name> / /tools disable <name> wewnątrz uruchomionej sesji — usunięcie narzędzia powoduje reset sesji, aby agent przebudował swój manifest narzędzi).

Trzy tryby API

Hermes abstrahuje różnice między dostawcami do trzech trybów API, wybieranych automatycznie w czasie wykonania:³

Resolver runtime_provider.py mapuje krotki (provider, model) na (api_mode, api_key, base_url) dla ponad 18 dostawców, obsługując przepływy OAuth, pule poświadczeń i rozwiązywanie aliasów.³

Przepływ danych przez sesję CLI

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

Z upstreamowej strony architektury.³

Kolejność składania promptu

Stos promptu obejmuje:¹³

1. SOUL.md (tożsamość agenta — lub wbudowany fallback, jeśli niedostępny)
2. Wytyczne dotyczące zachowania świadomego narzędzi
3. Kontekst pamięci/użytkownika (MEMORY.md, USER.md)
4. Wytyczne dotyczące skilli
5. Pliki kontekstu (AGENTS.md, .cursorrules)
6. Znacznik czasu
7. Wskazówki formatowania specyficzne dla platformy
8. Opcjonalne nakładki system-prompt, takie jak /personality

SOUL.md stanowi fundament — wszystko inne nadbudowuje się na nim.¹³

Przechowywanie sesji

Przechowywanie sesji oparte na SQLite z pełnotekstowym wyszukiwaniem FTS5. Sesje posiadają śledzenie linii rodowodowej (rodzic/dziecko między kompresjami), izolację per platforma oraz atomowe zapisy z obsługą rywalizacji.³

System wtyczek

Trzy źródła wykrywania: ~/.hermes/plugins/ (użytkownik), .hermes/plugins/ (projekt) oraz punkty wejścia pip. Wtyczki rejestrują narzędzia, hooki i polecenia CLI poprzez kontekstowe API. Dostawcy pamięci stanowią wyspecjalizowany typ wtyczki w plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Zasady projektowe

Z upstreamowej strony architektury:³

Migracja z OpenClaw

Hermes Agent jest następcą OpenClaw. W przypadku migracji z istniejącej instalacji OpenClaw:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate domyślnie czyta z ~/.openclaw (automatycznie wykrywa również starsze katalogi ~/.clawdbot oraz ~/.moldbot) i zapisuje do ~/.hermes.⁶

Bezpośrednio importowane (ponad 30 kategorii): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skille z 4 katalogów źródłowych, domyślny model, niestandardowi dostawcy, serwery MCP, tokeny i allowlisty platform komunikacyjnych (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), domyślne ustawienia agenta (poziom rozumowania, kompresja, opóźnienie ludzkie, strefa czasowa, sandbox), polityki resetu sesji, reguły zatwierdzania, konfiguracja TTS, ustawienia przeglądarki, ustawienia narzędzi, exec timeout, allowlista poleceń, konfiguracja gateway oraz klucze API z 3 źródeł.⁶

Zarchiwizowane do ręcznego przeglądu: zadania cron, wtyczki, hooki/webhooki, backend pamięci (QMD), konfiguracja rejestru skilli, UI/tożsamość, logowanie, konfiguracja multi-agenta, powiązania kanałów, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

Rozwiązywanie kluczy API sprawdza trzy źródła w kolejności priorytetu: wartości konfiguracyjne → ~/.openclaw/.env → auth-profiles.json.⁶

Rozwiązywanie problemów

“API key not set”

Proszę uruchomić hermes model, aby skonfigurować dostawcę interaktywnie, lub hermes config set OPENROUTER_API_KEY your_key. Polecenie hermes doctor wskaże dokładnie, których kluczy brakuje.⁷

“Context limit: 2048 tokens” przy uruchomieniu (modele lokalne)

Hermes automatycznie wykrywa długość kontekstu z punktu końcowego /v1/models serwera, jednak wiele lokalnych serwerów raportuje niskie wartości domyślne. Można ustawić ją jawnie w config.yaml:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Wywołania narzędzi pojawiają się jako tekst zamiast się wykonywać

Serwer nie ma włączonej obsługi wywołań narzędzi lub model nie obsługuje jej w implementacji serwera.²

Odpowiedzi są ucinane w połowie zdania

Dwie możliwe przyczyny:²

1. Niski limit wyjściowy (max_tokens) na serwerze — SGLang domyślnie ustawia 128 tokenów na odpowiedź. Należy ustawić --default-max-tokens na serwerze lub skonfigurować model.max_tokens w config.yaml.
2. Wyczerpanie kontekstu — Model zapełnił okno kontekstowe. Proszę zwiększyć model.context_length lub włączyć kompresję kontekstu w Hermesie.

“Connection refused” z WSL2 do serwera modelu hostowanego w Windows

WSL2 używa wirtualnego adaptera sieciowego z własną podsiecią — localhost wewnątrz WSL2 odnosi się do maszyny wirtualnej Linux, a nie do hosta Windows. Dwie opcje:²

Sieć lustrzana (Windows 11 22H2+): należy edytować %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Następnie wsl --shutdown i ponowne uruchomienie. localhost działa teraz dwukierunkowo.

Adres IP hosta jako rozwiązanie zapasowe (starsze wersje Windows): należy uzyskać adres IP hosta Windows z wnętrza WSL2 i użyć go zamiast localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

Konieczne jest również, aby serwer modelu nasłuchiwał na 0.0.0.0, a nie na 127.0.0.1 — należy ustawić OLLAMA_HOST=0.0.0.0 dla Ollamy, dodać --host 0.0.0.0 dla llama-server/SGLang lub włączyć “Serve on Network” w LM Studio.²

Gdzie wszystko się znajduje?

hermes status i hermes dump to przyjaciele w tej sytuacji. hermes logs list pokazuje wszystkie pliki logów wraz z rozmiarami. hermes config path wyświetla lokalizację pliku konfiguracyjnego. hermes config env-path wyświetla lokalizację pliku .env.⁶

FAQ

Jaka jest różnica między Hermes Agent a Claude Code?

Claude Code jest oficjalnym CLI firmy Anthropic, ograniczonym do modeli Anthropic. Hermes Agent to otwartoźródłowy framework agentowy od Nous Research, który współpracuje z dowolnym dostawcą zgodnym z OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google lub własny, samodzielnie hostowany punkt końcowy.¹² Hermes oferuje również bramę komunikacyjną dla Telegram/Discord/Slack/WhatsApp/Signal, której Claude Code nie posiada.

Czy mogę używać Hermesa z kluczem API od Anthropic?

Tak. Trzy sposoby:²

1. Ustawić ANTHROPIC_API_KEY w ~/.hermes/.env i uruchomić hermes chat --provider anthropic --model claude-sonnet-4-6
2. Uruchomić hermes model i wybrać Anthropic — Hermes wykorzysta magazyn poświadczeń Claude Code, jeśli będzie dostępny
3. Ustawić ręczny ANTHROPIC_TOKEN (setup-token lub token OAuth) jako rozwiązanie zapasowe

Opcja 2 jest preferowana, jeśli Claude Code jest już używany na tej samej maszynie — zachowuje odświeżalne poświadczenia Claude jako odświeżalne.

Jak przełączyć dostawców bez utraty konwersacji?

Należy użyć /model provider:model wewnątrz sesji. Historia konwersacji, pamięć i umiejętności zostają zachowane:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Skonfigurowałem Anthropic, ale wizja/web/kompresja nie działają

Następuje wtedy odwołanie do pomocniczego modelu zapasowego. Wizja, podsumowywanie stron, kompresja i inne zadania pomocnicze wykorzystują oddzielny pomocniczy LLM — domyślnie Gemini Flash poprzez automatyczne wykrywanie (OpenRouter → Nous → Codex). Jeśli żaden z nich nie jest skonfigurowany, a skonfigurowany jest tylko Anthropic, te funkcje cicho ulegają degradacji.⁴

Rozwiązanie: można dodać OPENROUTER_API_KEY dla zadań pomocniczych albo przekonfigurować sloty pomocnicze, aby używały głównego dostawcy. Warto zauważyć, że kompresja kontekstu znajduje się we własnym bloku najwyższego poziomu compression: i przyjmuje summary_provider, a nie auxiliary.compression.provider — slot auxiliary.compression udostępnia jedynie timeout. Pełne rozwiązanie:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

Jaka jest różnica między SOUL.md a AGENTS.md?

SOUL.md to tożsamość agenta — ton, styl, domyślne ustawienia komunikacji. Znajduje się w ~/.hermes/SOUL.md i podąża za użytkownikiem wszędzie. AGENTS.md jest specyficzny dla projektu — architektura, konwencje, polecenia, ścieżki — i znajduje się w katalogu projektu.¹³ Jeśli coś ma podążać za użytkownikiem wszędzie, należy użyć SOUL.md. Jeśli należy do projektu, należy użyć AGENTS.md.

Jak uruchomić wiele instancji Hermesa równolegle?

Profile. Każdy profil otrzymuje własny HERMES_HOME, konfigurację, pamięć, sesje i PID bramy:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Czy Hermes obsługuje lokalne LLM?

Tak, poprzez ścieżkę niestandardowego punktu końcowego. Hermes współpracuje z dowolnym serwerem zgodnym z OpenAI: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan lub własnym.² Patrz Custom & Self-Hosted Endpoints, aby uzyskać konfigurację dla poszczególnych serwerów.

Dlaczego baner startowy pokazuje mniej narzędzi, niż przewodnik podaje, że Hermes posiada?

Przewodnik wymienia 47 narzędzi / 20 toolsetów z rejestru architektury źródłowej — to pełna liczba narzędzi, dla których Hermes dostarcza kod źródłowy we wszystkich toolsetach. Działająca instalacja pokazuje mniejszą liczbę w banerze (referencyjna instalacja użyta dla tego przewodnika raportuje 28 narzędzi), ponieważ Hermes włącza tylko domyślny zestaw toolsetów przy uruchomieniu. Wiele toolsetów jest opcjonalnych: adaptery bramy komunikacyjnej, automatyzacja przeglądarki, cięższe stosy do scrapingu oraz kilka wyspecjalizowanych integracji muszą być jawnie wymienione w toolsets: w ~/.hermes/config.yaml, zanim się załadują. Suma w rejestrze = “co jest dostępne, jeśli to włączysz”. Suma w banerze = “co Twój bieżący profil faktycznie załadował”. Należy użyć hermes tools --list, aby zobaczyć, które toolsety są aktywne, a które są dostępne, ale wyłączone. Pojedyncze toolsety można przełączać w czasie działania za pomocą /tools enable <name> oraz /tools disable <name> (wyłączenie powoduje reset sesji, aby agent przebudował manifest narzędzi z nowym kształtem).

Jak Hermes obsługuje awarię modelu, gdy mój podstawowy dostawca zawodzi?

Należy skonfigurować blok fallback_model w config.yaml:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Gdy podstawowy dostawca zawiedzie (limit zapytań, błąd serwera, awaria uwierzytelniania), Hermes przełącza się na zapasowy w trakcie sesji bez utraty historii konwersacji. Uruchamia się co najwyżej raz na sesję.

Czy agent może z czasem ulepszać własne umiejętności?

Tak — to właśnie część “samodoskonaląca się” w Hermes Agent. Agent może tworzyć, aktualizować i usuwać umiejętności za pomocą narzędzia skill_manage. Gdy odkryje nietrywialny przepływ pracy, zapisuje to podejście jako umiejętność do późniejszego ponownego użycia.¹¹ Agent tworzy umiejętności po złożonych zadaniach (5+ wywołań narzędzi), gdy napotka błędy i znajdzie działającą ścieżkę, gdy użytkownik skoryguje jego podejście lub gdy odkryje nietrywialny przepływ pracy.

Czy istnieje integracja z IDE?

Tak — Hermes może działać jako serwer ACP (Agent Client Protocol) dla VS Code, Zed i JetBrains:⁶

pip install -e '.[acp]'
hermes acp

Dziennik zmian

Bibliografia