Hermes Agent: praktyczny podręcznik referencyjny (2026)

TL;DR: Hermes Agent to open-source’owy, samodoskonalący się agent AI od Nous Research. Działa jako CLI oraz jako wieloplatformowy gateway komunikacyjny, przechowuje trwałą tożsamość i pamięć trwałą na dysku, agreguje skill, które ulepszają się wraz z użyciem, i współpracuje z dowolnym dostawcą LLM zgodnym z OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok albo z własnym, samodzielnie hostowanym endpointem.¹²¹⁹ Od wersji v0.14.0 (16 maja 2026) Hermes dodaje OAuth SuperGrok z kontekstem grok-4.3 1M, lokalny proxy zgodny z OpenAI dla dostawców OAuth (hermes proxy), pełnoprawne x_search, obsługę instalacji z PyPI, leniwe instalowanie zależności, 22 platformy komunikacyjne z LINE i SimpleX Chat, /handoff, semantyczną diagnostykę LSP po zapisach, ujednolicone video_generate, computer_use przez cua-driver dla dostawców innych niż Anthropic, natywną betę Windows oraz zamknięcie 12 zgłoszeń P0 i 50 zgłoszeń P1.¹⁹ Najtrudniejszą częścią dla większości nowych użytkowników jest uwierzytelnianie dostawcy: Hermes obsługuje około 20 pełnoprawnych dostawców oraz niestandardowe endpointy, a także trzy odrębne ścieżki uwierzytelniania: klucz API w .env, OAuth przez hermes model albo niestandardowy endpoint w config.yaml. Model uwierzytelniania warto poznać najpierw — wszystko inne zależy od tego, który dostawca zostanie rozpoznany.

Hermes Agent działa jako pełne środowisko uruchomieniowe agenta, a nie nakładka na czat. Odczytuje system plików, wykonuje polecenia w sandboxowanych backendach, pobiera dane z internetu, uruchamia subagentów, wykonuje zaplanowane zadania cron, komunikuje się z Telegram/Discord/Slack/WhatsApp/Signal/Email z poziomu jednego procesu gateway i tworzy własne skill na podstawie doświadczenia.¹ CLI to terminalowy interfejs użytkownika zbudowany na pętli konwersacji w run_agent.py; gateway to długo działający proces, który kieruje wiadomości z platform komunikacyjnych przez tę samą pętlę konwersacji.³

Różnica między okazjonalnym a eksperckim użyciem Hermes sprowadza się do pięciu systemów. Opanowanie ich sprawia, że Hermes staje się mnożnikiem możliwości:

1. Rozpoznawanie dostawcy: jak 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 toolset: co agent może robić, z ograniczeniami zależnymi od platformy
4. System skill: proceduralna pamięć, którą agent tworzy i rozwija
5. Gateway + cron + profile: uruchamianie Hermes tam, gdzie faktycznie Pan/Pani pracuje, a nie tylko tam, gdzie akurat się znajduje

Najważniejsze wnioski

• Uwierzytelnianie dostawcy ma trzy ścieżki, nie jedną. Klucz API w .env, OAuth przez hermes model/hermes auth albo niestandardowy endpoint w config.yaml. Należy wybrać ścieżkę zgodną z dostawcą, a nie tę, która wydaje się znajoma.
• Zmiana dostawcy to jedno polecenie. hermes model interaktywnie prowadzi przez każdego obsługiwanego dostawcę, w tym logowania OAuth, a /model provider:model przełącza model w trakcie sesji bez utraty historii.²
• Dwa pliki są edytowalną przez użytkownika powierzchnią konfiguracji. ~/.hermes/config.yaml przechowuje ustawienia, a ~/.hermes/.env przechowuje sekrety. auth.json, SOUL.md, MEMORY.md i skills/ są zarządzane bezpośrednio przez Hermes — SOUL.md można edytować ręcznie, ale resztę modyfikuje sam agent.⁴
• Hermes jest następcą OpenClaw. Przy migracji hermes claw migrate automatycznie importuje ponad 30 kategorii stanu.⁵
• Jakość usługi zależy od modelu pomocniczego. Wizja, podsumowywanie stron, kompresja i zapis pamięci korzystają z osobnego pomocniczego LLM. Domyślnie jest to Gemini Flash przez automatyczne wykrywanie (OpenRouter → Nous → Codex) — jeśli żaden z nich nie jest skonfigurowany, funkcje te degradują się po cichu, dopóki sloty pomocnicze nie zostaną skierowane na głównego dostawcę.⁴

Co zmienia v0.14

v0.14.0 mniej opiera się na jednej sztandarowej funkcji, a bardziej na zmniejszeniu tarcia podczas konfiguracji i rozszerzeniu miejsc, w których Hermes może działać.¹⁹ Główne zmiany operacyjne:

• Instalacja i start są lżejsze. pip install hermes-agent działa z PyPI, ciężkie adaptery instalują się leniwie przy pierwszym użyciu, a ścieżka uruchamiania odracza wystarczająco dużo pracy, aby skrócić zimny start o około 19 sekund.
• Subskrypcje mogą stać się lokalnymi endpointami API. hermes proxy przekształca dostawców opartych na OAuth, takich jak Claude Pro, ChatGPT Pro i SuperGrok, w lokalny endpoint zgodny z OpenAI dla narzędzi takich jak Codex, Aider, Cline i Continue.
• Zasięg gateway się rozszerza. LINE i SimpleX Chat zwiększają liczbę platform do 22, Microsoft Teams jest połączony end-to-end, uzupełnianie historii Discord jest domyślnie włączone, a prompt clarify w Telegram/Discord korzysta teraz z natywnych przycisków.
• Weryfikacja podczas zapisu jest lepsza. Po edycjach Hermes może pokazywać podsumowania zmian plików dla każdej tury oraz semantyczną diagnostykę language-server przed następną turą, co przybliża go do pracy agenta opartej na dowodach.
• Narzędzia desktopowe i medialne są szersze. computer_use działa przez cua-driver dla dostawców innych niż Anthropic, video_generate jest ujednolicone za pluggable backendami, a vision_analyze wysyła surowe piksele do modeli, które faktycznie potrafią widzieć.

Każda sekcja poniżej opiera się na dokumentacji upstream pod adresem hermes-agent.nousresearch.com/docs oraz drzewie źródłowym w github.com/NousResearch/hermes-agent. Każde twierdzenie faktograficzne ma przypis wskazujący konkretną stronę upstream, z której pochodzi.

Wybór ścieżki

Jak działa Hermes: model mentalny

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

1. Buduje prompt systemowy z SOUL.md, MEMORY.md, USER.md, skills, plików kontekstu oraz wskazówek dla narzędzi za pomocą prompt_builder.py³
2. Ustala providera uruchomieniowego przez runtime_provider.py — to etap, który wybiera auth, bazowy URL oraz tryb API³
3. Wywołuje providera przy użyciu jednego z trzech trybów API: chat_completions, codex_responses albo anthropic_messages³
4. Przekazuje wszystkie zwrócone wywołania narzędzi przez model_tools.py oraz centralny rejestr narzędzi (tools/registry.py)³
5. Powtarza pętlę, aż model wygeneruje odpowiedź końcową, po czym zapisuje sesję w SQLite z FTS5³

Zrozumienie tej pętli jest ważne, ponieważ każda funkcja — personalities, memory, skills, compression, fallback — podpina się pod jeden z tych etapów. Gdy podczas czytania klucza konfiguracji pojawia się pytanie, do czego służy, odpowiedź zwykle brzmi: „to pokrętło na etapie 1, 2, 3 albo 4 powyższej pętli”.

Rdzeń niezależny od platformy. Jedna klasa AIAgent obsługuje CLI, gateway, ACP, batch oraz serwer API. Różnice platformowe znajdują się w punkcie wejścia, a nie w samym agencie.³ Dlatego te same slash commands działają w terminalu i w Telegram — są obsługiwane ze współdzielonego COMMAND_REGISTRY w hermes_cli/commands.py.⁶

Struktura katalogów jest systemem. Hermes przechowuje wszystko w ~/.hermes/ (albo w $HERMES_HOME dla profili niestandardowych):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── 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)

Każdy z powyższych plików ma określoną rolę; żadne z nich się nie nakładają. Jeśli trzeba znaleźć odpowiedź na pytanie „gdzie Hermes przechowuje X”, będzie to jedno z tych miejsc.

Instalacja

Jednowierszowy instalator pozostaje zalecaną, prowadzoną ścieżką dla większości użytkowników. Obsługuje Python, uv, Node.js, ripgrep, ffmpeg, sklonowanie repozytorium, środowisko wirtualne oraz globalne polecenie hermes.⁷ v0.14.0 dostarcza też prawdziwy pakiet PyPI, więc pip install hermes-agent jest teraz realną opcją bezpośredniej instalacji, jeśli środowisko Python jest już pod kontrolą użytkownika.¹⁹

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

pip install hermes-agent
hermes

Działa na Linux, macOS, WSL2 oraz Android/Termux (instalator automatycznie wykrywa Termux i przełącza się na przetestowany pakiet dla Androida).⁷ v0.14.0 dodaje natywną obsługę Windows we wczesnej wersji beta przez instalator PowerShell, ale WSL2 pozostaje bezpieczniejszą rekomendacją do zastosowań produkcyjnych, dopóki ścieżka Windows nie dojrzeje.¹⁹

Po zakończeniu:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

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

Weryfikacja instalacji

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor dokładnie informuje, czego brakuje i jak to naprawić.⁷ hermes dump to polecenie diagnostyczne, które warto wkleić do zgłoszenia GitHub albo wątku na Discord, prosząc o pomoc — jest to zwykłe tekstowe podsumowanie całej konfiguracji z usuniętymi sekretami.⁸

Instalacja ręczna

Jeśli potrzebna jest pełna kontrola — niestandardowa wersja Python, konkretne extras, integracja z Nix/NixOS — ręczny proces jest udokumentowany krok po kroku w upstreamowym przewodniku instalacji.⁷ Kluczowe opcjonalne extras, które można łączyć z uv pip install -e ".[<extras>]":

Polecenie instalacji Termux jest inne — używa pip z plikiem constraints, a nie uv pip:

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

Dzieje się tak, ponieważ .[all] na Androidzie pobiera faster-whisper przez extra voice, który zależy od kół ctranslate2 niepublikowanych dla Androida.⁷

Uwierzytelnianie i dostawcy

Hermes obsługuje około 19 pełnoprawnych dostawców oraz niestandardowe punkty końcowe, a także 3 odrębne ścieżki uwierzytelniania. Poniżej znajduje się pełny zakres uwierzytelniania, uporządkowany według ścieżek, aby łatwo można było znaleźć wariant pasujący do posiadanej konfiguracji.

3 ścieżki uwierzytelniania

Każdy dostawca w Hermes należy do jednego z 3 wzorców uwierzytelniania:

Ścieżka 1 — klucz API w .env. Należy umieścić klucz w ~/.hermes/.env, a Hermes odczyta go podczas uruchamiania. Tej ścieżki używają 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 przez hermes model lub hermes auth. Uruchamia przepływ kodu urządzenia, otwiera przeglądarkę, zapisuje poświadczenia w ~/.hermes/auth.json (i może importować istniejące poświadczenia z narzędzi takich jak Claude Code lub Codex CLI). Tej ścieżki używają 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 punktu końcowego API zgodnego z OpenAI — Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM proxy, Together AI, Groq, Azure OpenAI lub własny serwer self-hosted. Konfigurowane jednokrotnie przez hermes model → Custom endpoint, a następnie zapisywane w config.yaml.²

Pełna macierz dostawców

To kompletna lista pełnoprawnych dostawców wraz z dokładnym przepływem konfiguracji dla każdego z nich.²

Anthropic: 3 metody uwierzytelniania

Anthropic ma własną sekcję, ponieważ Hermes obsługuje 3 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

Po wybraniu Anthropic OAuth przez hermes model Hermes preferuje własny magazyn poświadczeń Claude Code zamiast kopiowania tokenu do ~/.hermes/.env. Dzięki temu odświeżalne poświadczenia Claude pozostają odświeżalne.² Jeśli Claude Code jest już używane na tej samej maszynie, jest to najczystsza ścieżka.

Aby trwale przypiąć Anthropic w config.yaml:

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

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

GitHub Copilot: 2 tryby

Copilot jest obsługiwany w 2 trybach: bezpośredni GitHub Copilot API (zalecany) oraz Copilot ACP (który uruchamia lokalny Copilot CLI 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 tej kolejności, zgodnie z dokumentacją upstream:² 1. Zmienna środowiskowa COPILOT_GITHUB_TOKEN 2. Zmienna środowiskowa GH_TOKEN 3. Zmienna środowiskowa GITHUB_TOKEN 4. Awaryjnie CLI gh auth token 5. Logowanie kodem urządzenia OAuth przez hermes model

Typ tokenu ma znaczenie. Copilot API nie obsługuje klasycznych Personal Access Tokens (ghp_*). Obsługiwane typy to tokeny OAuth (gho_*), fine-grained PAT (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, aby uwierzytelnić się przez OAuth.²

Chińscy dostawcy AI (pełnoprawna obsługa)

Hermes ma wbudowaną obsługę z.ai/GLM, Kimi/Moonshot, MiniMax (punkty końcowe globalne i chińskie) 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. Podczas używania dostawcy z.ai/GLM Hermes sprawdza wiele punktów końcowych (globalny, chiński, warianty coding), aby znaleźć taki, który akceptuje klucz API. Działający punkt końcowy jest automatycznie zapisywany w pamięci podręcznej — w przypadku większości użytkowników GLM_BASE_URL nie jest potrzebne.²

xAI (Grok) automatycznie włącza buforowanie promptów. Gdy bazowy adres URL zawiera x.ai, Hermes wysyła nagłówek x-grok-conv-id z każdym żądaniem, aby kierować je na ten sam serwer w ramach sesji rozmowy, ponownie wykorzystując buforowane prompty systemowe i historię.² Działa automatycznie; konfiguracja nie jest potrzebna.

Polecenie hermes auth

hermes auth to polecenie do 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ń pozwalają rotować wiele kluczy API lub tokenów OAuth dla tego samego dostawcy — przydatne do rozkładania limitów szybkości na wiele kluczy bez zmian w kodzie.⁶ Starsze polecenia hermes login / hermes logout zostały usunięte; zamiast nich należy używać hermes auth.⁶

Niestandardowe i self-hosted punkty końcowe

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

Konfiguracja interaktywna (zalecana):

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

Ręczny 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 zapisują konfigurację w config.yaml, który jest jedynym źródłem prawdy dla modelu głównego, dostawcy i bazowego adresu URL.² Starsze zmienne środowiskowe OPENAI_BASE_URL i LLM_MODEL nie są już odczytywane na potrzeby konfiguracji modelu głównego — należy użyć hermes model albo bezpośrednio edytować config.yaml.² (OPENAI_BASE_URL + OPENAI_API_KEY nadal są honorowane jako fallback dla pomocniczej ścieżki routingu provider: "main", więc nie należy usuwać ich pochopnie, 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 (samo, bez nazwy modelu) odpytuje API /v1/models punktu końcowego i automatycznie wybiera model, jeśli załadowany jest dokładnie 1 — 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. Poniżej znajdują się kluczowe polecenia, które faktycznie trzeba uruchomić. Każde ma utworzyć działający punkt końcowy, na który Hermes może wskazywać.²

Ollama — najprostsza lokalna ścieżka, bez 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

Krytyczny haczyk Ollama: Ollama domyślnie używa bardzo niskich długości kontekstu (4,096 tokenów poniżej 24GB VRAM). Trzeba je zwiększyć przez OLLAMA_CONTEXT_LENGTH albo Modelfile — zgodny z OpenAI API nie przyjmuje długości kontekstu od klienta, więc Hermes nie może ustawić jej za użytkownika.² Do użytku agentowego 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 wrócą jako zwykły tekst.²

SGLang — szybkie serwowanie z RadixAttention do ponownego użycia cache 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

Haczyk SGLang: domyślne max_tokens wynosi 128. Należy ustawić --default-max-tokens na serwerze albo skonfigurować model.max_tokens w config.yaml, jeśli odpowiedzi są ucinane.²

llama.cpp / llama-server — CPU i 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 tego 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 może sparsować jako rzeczywistych wywołań narzędzi.²

LM Studio — aplikacja desktopowa z GUI:

Należy uruchomić serwer z aplikacji LM Studio (karta Developer → Start Server) albo przez CLI: lms server start (uruchamia na porcie 1234) i lms load qwen2.5-coder --context-length 32768.² Następnie należy wskazać hermes model na http://localhost:1234/v1.

Krytyczny haczyk LM Studio: LM Studio odczytuje długość kontekstu z metadanych modelu, ale wiele modeli GGUF zgłasza domyślnie 2048 lub 4096. Zawsze należy jawnie ustawić długość kontekstu w ustawieniach modelu LM Studio — kliknąć ikonę koła zębatego obok selektora modelu, ustawić “Context Length” na co najmniej 16384 (najlepiej 32768) i ponownie załadować model.²

Nazwani dostawcy niestandardowi

Jeśli pracuje się z wieloma niestandardowymi punktami końcowymi (na przykład lokalnym serwerem deweloperskim i zdalnym serwerem GPU), należy zdefiniować je jako nazwanych dostawców niestandardowych 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 przełączać się między nimi w trakcie sesji za pomocą potrójnej składni:

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

Nazwanych dostawców niestandardowych można również wybierać z interaktywnego menu hermes model.²

Wtyczkowa architektura dostawców (v0.13.0+)

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

Lokalny proxy zgodny z OpenAI (v0.14.0+)

hermes proxy udostępnia lokalny punkt końcowy zgodny z OpenAI, oparty na dostawcy OAuth, do którego Hermes jest już zalogowany — Claude Pro, ChatGPT Pro, SuperGrok lub innym zgodnym skonfigurowanym dostawcy.¹⁹ Oznacza to, że narzędzia oczekujące API w stylu OpenAI, w tym Codex CLI, Aider, Cline, Continue lub niestandardowe skrypty, mogą ponownie użyć uwierzytelniania Hermes opartego na subskrypcji bez osobnego klucza API. Proxy należy traktować jako lokalną infrastrukturę deweloperską: wiązać je świadomie, nie wystawiać szeroko i pamiętać o warunkach specyficznych dla dostawcy.

Wykrywanie długości kontekstu

Zgodnie z dokumentacją upstream 2 ustawienia są stale mylone:²

• context_length — całkowite okno kontekstu (łączny budżet tokenów wejściowych i wyjściowych, np. 1,000,000 dla Claude Opus 4.7 albo 200,000 dla Sonnet 4.6). Hermes używa tego do decyzji, kiedy kompresować historię.
• model.max_tokens — limit wyjścia (maksymalna liczba tokenów, które model może wygenerować w jednej odpowiedzi). Nie jest związany z długością historii.

Należy ustawić context_length, gdy automatyczne wykrywanie błędnie rozpozna rozmiar okna:

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

Hermes używa wieloźródłowego łańcucha rozstrzygania do wykrywania okien kontekstu: nadpisanie w konfiguracji → niestandardowy dostawca per model → trwały cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev (utrzymywany przez społeczność rejestr dla ponad 3800 modeli) → domyślne fallbacki (128K).² System jest świadomy dostawcy, więc ten sam model może mieć różne limity kontekstu zależnie od tego, kto go serwuje (np. claude-opus-4.6 ma 1M przy bezpośrednim Anthropic, ale 128K w GitHub Copilot).²

Rotacja dostawców i fallback

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

Model fallback. Należy skonfigurować zapasowy provider:model, na który Hermes automatycznie przełączy się, gdy model główny zawiedzie (limity szybkoś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 rozmowy. Uruchamia się najwyżej raz na sesję.² Obsługiwani dostawcy dla fallbacku: 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 obrazów, streszczania stron internetowych, analizy zrzutów ekranu z przeglądarki, klasyfikacji zatwierdzania niebezpiecznych poleceń, kompresji kontekstu, streszczania wyszukiwania w sesji, dopasowywania skill, wysyłania narzędzi MCP oraz opróżniania pamięci.⁴ Domyślnie używają one Gemini Flash przez automatyczne wykrywanie (OpenRouter → Nous → Codex).

Można skonfigurować, którego modelu i dostawcy używa każde zadanie pomocnicze. Każdy slot pomocniczy używa tych samych 3 pokręteł: 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 tego samego dostawcy, którego używa mój główny agent” — jest poprawna wyłącznie w konfiguracjach auxiliary:, compression: i fallback_model:. Nie jest poprawna dla ustawienia najwyższego poziomu model.provider. Jeśli jako model główny używany jest niestandardowy punkt końcowy zgodny z OpenAI, w sekcji model: należy ustawić provider: custom.⁴

Dlaczego to ma znaczenie: jeśli skonfigurowano tylko Anthropic OAuth (bez klucza OpenRouter), analiza wizualna, streszczanie stron i kompresja ulegną degradacji albo przestaną działać, ponieważ domyślny łańcuch fallbacków pomocniczych najpierw próbuje OpenRouter. Należy dodać OPENROUTER_API_KEY dla zadań pomocniczych albo przekonfigurować każdy slot pomocniczy tak, aby używał głównego dostawcy:

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

To najczęstszy haczyk typu „moje funkcje po cichu nie działają” u nowych użytkowników Hermes.

System konfiguracji

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

Układ plików konfiguracyjnych

Zgodnie z dokumentacją upstream, na konfigurację Hermes składają się następujące pliki:⁴

~/.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 a .env — gdy ustawione są oba, config.yaml ma pierwszeństwo 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 config.yaml przy użyciu 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 należy uruchamiać po każdym hermes update — wykrywają nowo dodane opcje konfiguracji, których dany plik jeszcze nie zawiera.⁶

Pierwszeństwo konfiguracji

Hermes wczytuje 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 żadna inna warstwa nie ustawia wartości

Flagi CLI zawsze wygrywają w ramach tego pojedynczego wywołania. config.yaml pozostaje długoterminowym źródłem prawdy.

Lokalizacja (v0.13.0+)

W v0.13.0 dodano 7 lokalizacji dla komunikatów CLI i gateway: chiński (uproszczony), japoński, niemiecki, hiszpański, francuski, ukraiński i turecki.¹⁸ v0.14.0 lokalizuje wszystkie polecenia gateway oraz web dashboard, dodaje 8 kolejnych lokalizacji i zwiększa łączną liczbę do 16.¹⁹ Dokumentacja jest obecnie zlokalizowana tylko w zh-Hans. Lokalizacja jest ustalana na podstawie zmiennych środowiskowych LC_ALL / LANG albo jawnego klucza locale: w config.yaml. Angielski pozostaje językiem domyślnym i źródłem prawdy dla każdego ciągu, którego tłumaczenie jeszcze nie obejmuje.

Profile — wiele izolowanych instancji Hermes

Profile zapewniają wiele izolowanych instancji Hermes, z których każda ma własną konfigurację, sesje, skills, pamięć i PID gateway. W ten sposób można uruchomić „służbowy Hermes” i „prywatny Hermes” obok siebie, bez wzajemnego dostępu do swojego stanu.⁶

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łasne HERMES_HOME (domyślnie ~/.hermes-<name>/), dzięki czemu wiele profili może uruchamiać gateway równolegle bez wzajemnego kolidowania ze sobą.⁶³

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 slash

Polecenia slash działają wewnątrz aktywnej sesji czatu (CLI lub platforma komunikacyjna). Są obsługiwane przez wspólny COMMAND_REGISTRY w hermes_cli/commands.py, dlatego większość poleceń działa identycznie na różnych powierzchniach.⁹

Kontrola sesji

Konfiguracja i model

Polecenie /model jest głównym narzędziem do przełączania provider 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 slash dla skills

Każdy zainstalowany skill jest automatycznie udostępniany jako polecenie slash:⁹

/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 też zdefiniować quick commands w config.yaml, które mapują krótką nazwę na dłuższy prompt:⁹

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 w CLI można wpisać /review, /deploy albo /morning.

Dopasowywanie prefiksów

Polecenia obsługują dopasowywanie prefiksów: wpisanie /h rozwiązuje się do /help, a /mod do /model. Gdy prefiks jest niejednoznaczny, wygrywa pierwsza rejestracja w kolejności registry. Pełne nazwy poleceń i zarejestrowane aliasy zawsze mają pierwszeństwo przed dopasowaniami prefiksów.⁹

Polecenia specyficzne dla komunikatorów

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

• /status — wyświetlenie informacji o sesji
• /sethome (alias /set-home) — oznaczenie bieżącego czatu jako platform home
• /approve [session|always] — zatwierdzenie oczekującego niebezpiecznego polecenia
• /deny — odrzucenie oczekującego niebezpiecznego polecenia
• /update — aktualizacja Hermes Agent do najnowszej wersji
• /commands [page] — przeglądanie wszystkich poleceń i skills (z paginacją)

Niektóre działają wyłącznie w CLI: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Narzędzia i toolsets

Hermes zawiera szeroki wbudowany rejestr narzędzi obejmujący wyszukiwanie w sieci, automatyzację przeglądarki, wykonywanie poleceń w terminalu, edycję plików, pamięć, delegowanie, trenowanie RL, dostarczanie wiadomości, integrację z Home Assistant i nie tylko.¹⁰ Narzędzia są zorganizowane w logiczne toolsets, które można włączać lub wyłączać dla poszczególnych platform.

Kategorie wysokiego poziomu

Typowe nazwy toolsets to web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant i 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 też przełączać w trakcie sesji za pomocą /tools disable <name> i /tools enable <name>, co resetuje sesję, aby nowy zestaw narzędzi zaczął obowiązywać.⁹

Backendy terminala

Narzędzie terminala może wykonywać polecenia w 6 różnych środowiskach:¹⁰

Backendy można przełączać za pomocą hermes config set terminal.backend <name> albo w 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 container_persistent: true zainstalowane pakiety, pliki i konfiguracja są zachowywane między sesjami.¹⁰

Wszystkie backendy kontenerowe działają ze wzmocnieniami bezpieczeństwa: system plików root tylko do odczytu (Docker), wszystkie możliwości Linux usunięte z wyjątkiem DAC_OVERRIDE, CHOWN i FOWNER, brak eskalacji uprawnień, limity PID (256 procesów), pełna izolacja namespace, trwały workspace przez wolumeny.¹⁰

Procesy w tle

Narzędzie terminala obsługuje 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 (buforowane na czas sesji). Można też ustawić SUDO_PASSWORD w ~/.hermes/.env.¹⁰

Multi-agent Kanban (v0.13.0+)

v0.13.0 przekształca współpracę wielu agentów w prymityw pierwszej klasy: trwałą tablicę Kanban, która śledzi zadania, status i tożsamość workerów między agentami oraz po restartach.¹⁸ To właśnie tablica sprawia, że rój workerów Hermes faktycznie kończy pracę, zamiast zatrzymywać się na martwych przekazaniach.

Tablica Kanban naturalnie łączy się z /goal (pętla Ralph z zablokowanym celem) po stronie celu oraz z istniejącym narzędziem delegate_task dla semantyki uruchamiania. Wynikiem jest wzorzec roju, w którym każdy agent korzysta z jednego źródła prawdy o tym, co trzeba zrobić dalej, kto to robi i co utknęło.

System skill

Skill to dokumenty wiedzy ładowane na żądanie, które agent może wczytać w razie potrzeby. Działają zgodnie ze wzorcem progresywnego ujawniania, aby ograniczać użycie tokenów, i są zgodne z otwartym standardem agentskills.io.¹¹

Wszystkie skill znajdują się w ~/.hermes/skills/ — to główny katalog i źródło prawdy. Przy świeżej instalacji wbudowane skill są kopiowane z repozytorium. Skill zainstalowane z hubu i 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 wczytuje pełną treść skill 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

## Verification
How to confirm it worked.

Aktywacja warunkowa

Skill mogą się pokazywać lub ukrywać zależnie od tego, które narzędzia są dostępne. Najbardziej przydaje się to w przypadku fallback skill — darmowych lub lokalnych alternatyw, które powinny pojawiać się tylko wtedy, gdy niedostępne jest narzędzie premium:¹¹

Przykład: wbudowany skill duckduckgo-search używa fallback_for_toolsets: [web]. Gdy ustawiono FIRECRAWL_API_KEY, toolset web jest dostępny, a agent używa web_search — skill DuckDuckGo pozostaje ukryty. Bez klucza API skill DuckDuckGo automatycznie pojawia się jako fallback.¹¹

Skill zarządzane przez agenta

Agent może tworzyć, aktualizować i usuwać własne skill za pomocą narzędzia skill_manage. To pamięć proceduralna agenta — gdy agent opracuje nietrywialny workflow, zapisuje podejście jako skill do ponownego użycia w przyszłości.¹¹

Kiedy agent tworzy skill:¹¹ - Po pomyślnym wykonaniu złożonego zadania (ponad 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 workflow

Akcje:¹¹

Skill Hub

Przeglądanie, wyszukiwanie, instalowanie i zarządzanie skill 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 hubu:¹¹

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

Skanowanie bezpieczeństwa

Wszystkie skill zainstalowane z hubu przechodzą przez skaner bezpieczeństwa, który sprawdza wyciek danych, prompt injection, destrukcyjne polecenia, sygnały supply-chain i inne zagrożenia.¹¹

Poziomy zaufania:¹¹

--force może nadpisać niegroźne blokady zasad dla community skill. Nie nadpisuje werdyktu skanowania dangerous.¹¹

Zewnętrzne katalogi skill

Można wskazać Hermes dodatkowe katalogi skill skanowane obok katalogu lokalnego:¹¹

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

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

Trwała pamięć

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

Oba są wstrzykiwane do promptu systemowego jako zamrożony snapshot na początku sesji. Agent zarządza własną pamięcią za pomocą narzędzia memory — add, replace albo remove.¹²

Wzorzec zamrożonego snapshotu: wstrzyknięcie do promptu systemowego jest przechwytywane raz, na początku sesji, i nigdy nie zmienia się w jej trakcie. To celowe rozwiązanie — zachowuje pamięć podręczną prefiksów LLM ze względów wydajnościowych. Zmiany wprowadzone podczas sesji są natychmiast zapisywane na dysku, ale pojawiają się w prompcie systemowym dopiero w następnej sesji.¹²

Co zapisywać

Zapisywać te informacje (agent robi to proaktywnie):¹² - Preferencje użytkownika: „Wolę TypeScript niż JavaScript” → user - Fakty o środowisku: „Ten serwer działa na Debianie 12 z PostgreSQL 16” → memory - Korekty: „Nie używać sudo dla poleceń Docker, użytkownik jest w grupie docker” → memory - Konwencje: „Projekt używa tabulatorów, szerokości linii 120 znaków, docstringów w stylu Google” → memory - Ukończone prace: „Przeniesiono bazę danych z MySQL do PostgreSQL 2026-01-15” → memory

Pomijać te informacje:¹² - Informacje trywialne lub oczywiste - Fakty łatwe do ponownego odkrycia - Surowe zrzuty danych (za duże na pamięć) - Ulotne informacje specyficzne dla sesji - Informacje już obecne w plikach kontekstowych

Wyszukiwanie sesji

Oprócz 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ą trafne wcześniejsze rozmowy ze streszczeniem Gemini Flash.¹²

Zewnętrzni dostawcy pamięci

Do głębszej trwałej pamięci wykraczającej poza MEMORY.md i USER.md Hermes zawiera 8 wtyczek zewnętrznych dostawców pamięci: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover i Supermemory.¹²

Zewnętrzni dostawcy działają równolegle z wbudowaną pamięcią (nigdy jej nie zastępują) 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)

Aktywny może być tylko jeden zewnętrzny dostawca naraz. Wbudowana pamięć jest zawsze aktywna.⁶

Automatyczne wznawianie sesji (v0.13.0+)

v0.13.0 sprawia, że przerwanie pracy agenta w trakcie działania nie niszczy sesji. Gateway automatycznie wznawia przerwane sesje po restarcie; restarty /update zachowują stan sesji podczas aktualizacji; przeładowania plików źródłowych w trakcie developmentu utrzymują aktywną sesję zamiast wymuszać nową.¹⁸ Praktyczny efekt: długotrwałe prace gateway i zadania uruchamiane przez cron nie resetują już okna kontekstu po restarcie procesu.

Checkpoints v2 (v0.13.0+)

W v0.13.0 trwałość stanu została przepisana jako projekt z jednym magazynem, z rzeczywistym przycinaniem, zabezpieczeniami dyskowymi i bez osieroconych repozytoriów-cieni.¹⁸ Poprzedni system checkpoint gromadził stan na dysku w długotrwałych profilach; magazyn v2 nakłada twardy limit na lokalną przestrzeń checkpoint i usuwa zdublowaną księgowość, która powodowała ten wzrost. Nie jest wymagana żadna zmiana konfiguracji widoczna dla użytkownika; następny zapis checkpoint użyje ścieżki v2.

Osobowość i SOUL.md

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

Hermes automatycznie inicjalizuje domyślny SOUL.md w ~/.hermes/SOUL.md (albo $HERMES_HOME/SOUL.md dla profili niestandardowych). Istniejące pliki użytkownika nigdy nie są nadpisywane. Hermes ładuje SOUL.md wyłącznie z HERMES_HOME — nie szuka go w bieżącym katalogu roboczym. Dzięki temu osobowość pozostaje przewidywalna między projektami.¹³

Co powinno znaleźć się w SOUL.md

Warto używać go do trwałych wytycznych dotyczących głosu i osobowości:¹³ - tonu - stylu komunikacji - poziomu bezpośredniości - domyślnego stylu interakcji - tego, czego unikać stylistycznie - sposobu, w jaki Hermes powinien obsługiwać niepewność, niezgodę i niejednoznaczność

Rzadziej używać go do:¹³ - jednorazowych instrukcji projektowych - ścieżek plików - konwencji repozytorium - tymczasowych szczegółów workflow

Te elementy należą do AGENTS.md, 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 zasady komunikacji, zachowanie na poziomie osobowości.

AGENTS.md — architektura projektu, konwencje kodowania, preferencje narzędziowe, workflow specyficzne dla repozytorium, polecenia, porty, ścieżki, notatki wdrożeniowe.

Przydatna zasada: jeśli coś ma podążać za użytkownikiem wszędzie, należy to umieścić w SOUL.md. Jeśli należy do projektu, powinno trafić do AGENTS.md.¹³

Wbudowane osobowości

Hermes zawiera wbudowane osobowości, na które można przełączać się 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 przełączyć się za pomocą /personality codereviewer.

SOUL.md a /personality

SOUL.md jest głosem bazowym. /personality to nakładka na poziomie sesji.¹³ Warto zachować pragmatyczny domyślny SOUL.md, a potem użyć /personality teacher dla rozmowy edukacyjnej albo /personality creative do burzy mózgów.

Nous Tool Gateway (v0.10.0+)

Od Hermes Agent v0.10.0 (2026-04-16) płatni subskrybenci Nous Portal otrzymują zarządzany dostęp do kuratorowanego zestawu narzędzi przez swoje istniejące dane uwierzytelniające Portal — bez dodatkowych kluczy API do zarządzania.²¹ Sam Hermes CLI pozostaje objęty licencją MIT i w pełni open source. Zmiana polega na tym, że uwierzytelnienie Portal odblokowuje teraz więcej niż tylko inferencję modeli.

Co znajduje się w gateway

Jak to działa

Gateway jest włączany osobno dla każdego narzędzia przez nowe pole konfiguracji use_gateway. Jeśli dane uwierzytelniające Portal są dostępne w hermes auth i gateway jest włączony dla danego narzędzia, wywołania tego narzędzia przechodzą 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

Priorytet w czasie działania: gdy gateway jest dostępny i narzędzie ma use_gateway: true, Hermes preferuje gateway nawet wtedy, gdy skonfigurowano również bezpośredni klucz API. Ma to znaczenie dla rozliczeń — wywołania gateway korzystają z subskrypcji Portal, a nie z salda 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 ma osobnego polecenia hermes subscribe ani hermes login --portal. Subskrypcja jest wykrywana automatycznie na podstawie danych uwierzytelniających Portal OAuth, które już znajdują się w hermes auth.

Ceny i dostęp

Ceny i nazwy poziomów są publikowane na stronie cen Nous Portal (https://portal.nousresearch.com/pricing). Ten przewodnik nie wylicza poziomów, ponieważ odpowiada za nie produkt Portal, nie Hermes CLI, i zmieniają się one niezależnie od wydań Hermes. Rejestracja odbywa się pod adresem https://portal.nousresearch.com/; bieżące poziomy należy sprawdzić na stronie cen.

Informacja o wycofaniu

• Zmienna środowiskowa HERMES_ENABLE_NOUS_MANAGED_TOOLS została usunięta w v0.10.0. Narzędzia zarządzane są teraz włączane przez pole konfiguracji use_gateway osobne dla każdego narzędzia i zależą od stanu subskrypcji Portal.²¹

Ujęcie: czym to wydanie nie jest

Hermes Agent CLI nie jest blokowany subskrypcją. Projekt nadal ma licencję MIT, wszystkie funkcje podstawowe (CLI, skills, pamięć, messaging gateway, cron, MCP, lokalny dashboard, BYOK dla każdego dostawcy) działają end-to-end bez 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 ze ścieżki bezpłatnej.

Messaging gateway

Hermes może działać jako długotrwały proces gateway, który łączy się z 22 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, LINE, SimpleX Chat oraz ogólny adapter Webhook.^320171819 Wersja v0.9.0 dodała iMessage przez BlueBubbles (automatyczną rejestrację webhook, kreator konfiguracji, odporność na awarie) oraz natywne wsparcie WeChat przez iLink Bot API z trybem callback WeCom dla aplikacji firmowych.¹⁶ Wersja v0.11.0 dodała QQBot.²⁰ Wersja 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 wtyczkowej architektury adapterów; IRC i Microsoft Teams zostały również przeniesione na nowy wzorzec adaptera z ogólnymi hookami pluginów env_enablement_fn / cron_deliver_env_var.¹⁸ v0.14.0 dodaje LINE i SimpleX Chat oraz domyka stos Microsoft Teams end-to-end za pomocą Graph auth, listenera webhook, środowiska wykonawczego pipeline i dostarczania wychodzącego.¹⁹

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łączanie każdej platformy: tokeny API, identyfikatory botów, mapowania kanałów, allowlisty.⁶

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 działa przez tę samą pętlę konwersacji AIAgent co CLI. Dlatego polecenia slash działają identycznie w obu miejscach i dlatego zadanie cron zaplanowane w Telegram może dostarczyć wynik do Discord — różnica między platformami znajduje się tylko na brzegu systemu.³

Autoryzacja użytkowników 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 uniemożliwiają przypadkowym osobom komunikowanie się z gateway. Użytkownik wysyła kod parowania ze swojej platformy komunikacyjnej; zatwierdza się go poleceniem hermes pairing approve; od tego momentu użytkownik jest autoryzowany.⁶

Zaplanowane zadania (cron)

Hermes ma pełnoprawny system cron, w którym zadania są zadaniami agenta, a nie poleceniami shell. Każde zaplanowane zadanie działa przez świeżą instancję AIAgent ze skonfigurowanym promptem, opcjonalnie dołączonymi skills 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

Można też 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ą zapisywane w JSON i przetrwają ponowne uruchomienia.³

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ć jego powierzchnię narzędziową:

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

Albo ręcznie w 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ć konwersacje Hermes innym agentom:

hermes mcp serve
hermes mcp serve -v    # Verbose

Kompresja kontekstu

Hermes automatycznie kompresuje długie konwersacje, aby mieściły się w oknie kontekstu modelu. Summarizer kompresji to oddzielne wywołanie LLM — można skierować je do dowolnego providera lub endpointu.⁴

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 providera:⁴

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

Ostrzeżenia o presji budżetu

Gdy agent pracuje nad złożonym zadaniem z wieloma wywołaniami narzędzi, może wyczerpać budżet iteracji (domyślnie: 90 tur), nie zdając sobie z tego sprawy. Presja budżetu automatycznie ostrzega model:⁴

Limity czasu strumienia

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

Limit czasu odczytu z gniazda jest podnoszony do 30 minut dla lokalnych endpointów, ponieważ lokalne LLM mogą potrzebować kilku minut na prefill przy dużych kontekstach, zanim wygenerują pierwszy token.⁴

Lokalny web dashboard (v0.9.0+)

Dashboard działający w przeglądarce do lokalnego zarządzania Hermes Agent. Można konfigurować ustawienia, monitorować sesje, przeglądać skills i zarządzać gateway bez dotykania plików konfiguracyjnych ani terminala.¹⁶ Uruchamia się go poleceniem hermes dashboard. To najprostsza ścieżka wdrożenia dla nowych użytkowników preferujących GUI.

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

watch_patterns pozwala ustawić wzorce do monitorowania w wyjściu procesów w tle i otrzymywać powiadomienia w czasie rzeczywistym, gdy wystąpi dopasowanie.¹⁶ Można monitorować błędy, czekać na konkretne zdarzenia („listening on port”) albo obserwować logi buildów — wszystko bez odpytywania. W połączeniu z notify_on_complete z v0.8.0 (które powiadamia o ukończeniu zadania w tle) Hermes ma teraz pełną warstwę obserwowalności procesów w tle.¹⁵

Pluggable context engine (v0.9.0+)

Zarządzanie kontekstem jest teraz wtyczkowym slotem przez hermes plugins. Można podmieniać niestandardowe context engines, które kontrolują, co agent widzi w każdej turze — filtrowanie, summarization albo wstrzykiwanie kontekstu specyficznego dla domeny.¹⁶ Oddziela to strategię kontekstu od głównej pętli agenta, umożliwiając dostosowanie kontekstu per projekt lub per domena.

Backup i restore (v0.9.0+)

hermes backup tworzy pełne archiwum konfiguracji, sesji, skills i pamięci. hermes import przywraca dane z archiwum backup.¹⁶ Warto używać tego do migracji między maszynami, tworzenia snapshotów przed większymi zmianami albo udostępniania sprawdzonej konfiguracji członkom zespołu.

Obsługa Termux / Android (v0.9.0+)

Hermes działa natywnie na Androidzie przez Termux. Dostosowane ścieżki instalacji, optymalizacje TUI dla ekranów mobilnych, obsługa backendu głosowego i polecenie /image działają bezpośrednio na urządzeniu.¹⁶

Wzmacnianie bezpieczeństwa (v0.13.0+)

v0.13.0 zamknęła 8 problemów bezpieczeństwa P0 i zmieniła jedno ustawienie domyślne na korzyść użytkownika.¹⁸ v0.14.0 dodaje kolejne zamknięcia: 12 P0 i 50 P1, w tym wzmocnienie ochrony przed brute-force sudo / sudo-stdin, poprawki obejść dla niebezpiecznych poleceń, sanityzację błędów narzędzi przed ponownym wstrzyknięciem do modelu, uwierzytelnianie API dla pluginu dashboardu, pokrycie SSRF w skills-hub oraz skanowanie ostrzeżeń supply-chain podczas instalacji.¹⁹

Jeśli utrzymywane jest wdrożenie Hermes, v0.13.0 i v0.14.0 należy traktować jako aktualizacje istotne dla bezpieczeństwa, a nie tylko dostawy funkcji. v0.13.0 zamyka obejście między guildami w Discord i dwa okna TOCTOU; v0.14.0 dodaje kolejną rundę wzmocnień obejmującą obsługę sudo, ponowne wstrzykiwanie błędów narzędzi, API pluginów, SSRF w skills-hub oraz ostrzeżenia dotyczące zależności.

Architektura dla praktyków

Ta sekcja jest przeznaczona dla osób, które chcą zrozumieć, co dzieje się pod spodem, aby móc debugować system, rozszerzać go lub analizować wydajność. To synteza upstreamowej dokumentacji architektury.³

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 upstreamowej dokumentacji architektury.³

„47 narzędzi / 20 toolsetów” kontra „28 narzędzi” w banerze. Liczba „47 narzędzi” oznacza pełny rejestr narzędzi w upstreamowym repozytorium, czyli każde narzędzie, którego kod źródłowy Hermes dostarcza we wszystkich toolsetach. Rzeczywiście uruchomiony CLI pokaże mniejszą liczbę w banerze startowym (instalacja, na której zweryfikowano ten przewodnik, raportuje 28 tools / 89 skills). To nie jest błąd. Wiele toolsetów jest opcjonalnych i trzeba je jawnie włączyć w config.yaml pod toolsets: — adaptery platform komunikacyjnych, automatyzację przeglądarki, cięższe narzędzia scrapingowe itd. Łączna liczba w rejestrze oznacza „co jest dostępne”; liczba w banerze oznacza „co jest włączone w bieżącym profilu”. Aktywne toolsety można sprawdzić poleceniem hermes tools --list, a pojedyncze toolsety włączać lub wyłączać blokiem toolsets: w ~/.hermes/config.yaml albo przez /tools list / /tools enable <name> / /tools disable <name> w uruchomionej sesji — usunięcie narzędzia wywołuje reset sesji, aby agent odbudował manifest narzędzi.

Trzy tryby API

Hermes abstrahuje różnice między providerami do trzech trybów API, wybieranych automatycznie w czasie działania:³

Resolver runtime_provider.py mapuje krotki (provider, model) na (api_mode, api_key, base_url) dla ponad 18 provideró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 — albo wbudowany fallback, jeśli plik jest niedostępny)
2. Wskazówki zachowania świadome narzędzi
3. Pamięć/kontekst użytkownika (MEMORY.md, USER.md)
4. Wskazówki dotyczące skills
5. Pliki kontekstowe (AGENTS.md, .cursorrules)
6. Znacznik czasu
7. Wskazówki formatowania specyficzne dla platformy
8. Opcjonalne nakładki system-promptu, takie jak /personality

SOUL.md stanowi fundament — wszystko inne jest budowane na nim.¹³

Przechowywanie sesji

Przechowywanie sesji oparte na SQLite z pełnotekstowym wyszukiwaniem FTS5. Sesje mają śledzenie linii pochodzenia (parent/child między kompresjami), izolację per platforma oraz atomowe zapisy z obsługą rywalizacji o zasoby.³

System pluginów

Trzy źródła wykrywania: ~/.hermes/plugins/ (użytkownik), .hermes/plugins/ (projekt) oraz punkty wejścia pip. Pluginy rejestrują narzędzia, hooki i polecenia CLI przez kontekst API. Providery pamięci są wyspecjalizowanym typem pluginu 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 odczytuje dane z ~/.openclaw (automatycznie wykrywa też starsze katalogi ~/.clawdbot i ~/.moldbot) i zapisuje je do ~/.hermes.⁶

Importowane bezpośrednio (ponad 30 kategorii): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills z 4 katalogów źródłowych, model domyślny, niestandardowi providerzy, serwery MCP, tokeny platform komunikacyjnych i allowlisty (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), domyślne ustawienia agenta (reasoning effort, kompresja, human delay, strefa czasowa, sandbox), polityki resetowania sesji, reguły zatwierdzania, konfiguracja TTS, ustawienia przeglądarki, ustawienia narzędzi, timeout exec, allowlista poleceń, konfiguracja gateway oraz klucze API z 3 źródeł.⁶

Archiwizowane do ręcznego przeglądu: zadania cron, pluginy, hooki/webhooki, backend pamięci (QMD), konfiguracja rejestru skills, UI/tożsamość, logowanie, konfiguracja multi-agent, 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 config → ~/.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

Historia zmian

Źródła