Hermes Agent：実践者のためのリファレンス（2026年）

TL;DR: Hermes Agentは、Nous Researchによるオープンソースの自己改善型AIエージェントです。CLIとしても、マルチプラットフォームのメッセージングgatewayとしても動作し、永続的なアイデンティティと継続的なメモリをディスクに保存し、使うほど改善されるskillを集約します。また、OpenAI互換の任意のLLMプロバイダー（Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok、または自分でセルフホストしたエンドポイント）で利用できます。¹²¹⁹ v0.14.0（2026年5月16日）時点で、Hermesにはgrok-4.3 1Mコンテキスト対応のSuperGrok OAuth、OAuthプロバイダー向けのOpenAI互換ローカルプロキシ（hermes proxy）、ファーストクラスのx_search、PyPIインストール対応、遅延依存関係インストール、LINEとSimpleX Chatを含む22のメッセージングプラットフォーム、/handoff、書き込み後のLSPセマンティック診断、統合されたvideo_generate、非Anthropicプロバイダー向けのcua-driver経由computer_use、ネイティブWindowsベータ、そして12件のP0 / 50件のP1クローズが追加されています。¹⁹ ほとんどの新規ユーザーにとって最も難しいのは、プロバイダー認証です。Hermesは約20のファーストクラスプロバイダーとカスタムエンドポイントに対応しており、認証経路も3つ（.envのAPIキー、hermes model経由のOAuth、またはconfig.yamlのカスタムエンドポイント）に分かれています。まず学ぶべきなのは、この認証モデルです。それ以外はすべて、どのプロバイダーが解決されるかに依存します。

Hermes Agentはチャットラッパーではなく、完全なエージェントランタイムとして動作します。 ファイルシステムを読み取り、サンドボックス化されたバックエンドでコマンドを実行し、Webをスクレイピングし、サブエージェントを起動し、スケジュールされたcronジョブを実行し、単一のgatewayプロセスからTelegram/Discord/Slack/WhatsApp/Signal/Emailとやり取りし、経験から独自のskillを作成します。¹ CLIは、run_agent.pyの会話ループ上に構築されたターミナルUIです。gatewayは、メッセージングプラットフォームからのメッセージを同じ会話ループへルーティングする、長時間実行されるプロセスです。³

Hermesを気軽に使う場合と熟練して使う場合の違いは、5つのシステムを理解しているかどうかです。 これらを習得すると、Hermesは大きな力になります。

1. Provider resolution: 認証フローがどのようにAPI呼び出しへ対応するか
2. Configuration hierarchy: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset system: エージェントが何をできるか、プラットフォームごとにどう制限されるか
4. Skills system: エージェントが作成し進化させる手続き的メモリ
5. Gateway + cron + profiles: いまいる場所だけでなく、普段使っている場所でHermesを動かす仕組み

重要ポイント

• プロバイダー認証は1つではなく、3つの経路があります。 .envのAPIキー、hermes model/hermes auth経由のOAuth、またはconfig.yamlのカスタムエンドポイントです。慣れている方法ではなく、プロバイダーに合った経路を選んでください。
• プロバイダーの切り替えは1つのコマンドでできます。 hermes modelは、OAuthログインを含む対応済みプロバイダーを対話的に案内します。また、/model provider:modelを使えば、履歴を失わずにセッション途中で切り替えられます。²
• ユーザーが編集する設定面は2つのファイルです。 ~/.hermes/config.yamlには設定が入り、~/.hermes/.envにはシークレットが入ります。auth.json、SOUL.md、MEMORY.md、skills/はHermesが直接管理します。SOUL.mdは手動で編集できますが、それ以外はエージェント自身が扱います。⁴
• HermesはOpenClawの後継です。 移行する場合、hermes claw migrateが30以上のカテゴリの状態を自動でインポートします。⁵
• サービス品質は補助モデルに左右されます。 Vision、Web要約、圧縮、メモリフラッシュはいずれも別の補助LLMを使います。デフォルトでは自動検出（OpenRouter → Nous → Codex）によるGemini Flashです。これらが設定されていない場合、補助スロットをメインプロバイダーに向けるまで、該当機能は静かに劣化します。⁴

v0.14で変わったこと

v0.14.0は、目玉機能が1つあるというよりも、Hermesを実行できる場所を広げながら、セットアップの手間を減らすリリースです。¹⁹ 主な運用上の変更は次のとおりです。

• インストールと起動が軽くなりました。 pip install hermes-agentでPyPIからインストールでき、重いアダプターは初回使用時に遅延インストールされます。また、起動パスで十分な処理を後回しにすることで、コールドスタートが約19秒短縮されています。
• サブスクリプションをローカルAPIエンドポイントにできます。 hermes proxyは、Claude Pro、ChatGPT Pro、SuperGrokなどのOAuthベースのプロバイダーを、Codex、Aider、Cline、Continueのようなツール向けのOpenAI互換ローカルエンドポイントに変換します。
• gatewayの対応範囲が広がりました。 LINEとSimpleX Chatによりプラットフォーム数は22になり、Microsoft Teamsはエンドツーエンドで接続され、Discord履歴バックフィルはデフォルトで有効になりました。また、Telegram/Discordのclarifyプロンプトはネイティブボタンを使うようになっています。
• 書き込み時の検証が改善されました。 編集後、Hermesは次のターンの前に、ターンごとのファイル変更サマリーと言語サーバーのセマンティック診断を表示できます。これにより、エビデンス主導のエージェント作業に近づいています。
• デスクトップとメディア系ツールが広がりました。 computer_useは非Anthropicプロバイダー向けにcua-driver経由で動作し、video_generateはプラガブルなバックエンドの背後に統合され、vision_analyzeは実際に画像を認識できるモデルへ生ピクセルを送ります。

以下の各セクションは、アップストリームのドキュメントであるhermes-agent.nousresearch.com/docsと、ソースツリーのgithub.com/NousResearch/hermes-agentに基づいています。すべての事実主張には、その情報が由来する具体的なアップストリームページへの脚注を付けています。

目的別ガイド

Hermesの仕組み: メンタルモデル

Hermesは、どのエントリーポイントからでも呼び出せる単一の会話ループを中心に構成されています。エントリーポイントには、CLI（cli.py）、メッセージングgateway（gateway/run.py）、エディタ連携用のACP adapter、batch runner、そしてAPI serverがあります。³ これらは最終的にすべて、run_agent.py内のAIAgent.run_conversation()を呼び出します。これは次の処理を行います。

1. prompt_builder.pyを通じて、SOUL.md、MEMORY.md、USER.md、skills、context files、tool guidanceからsystem promptを構築します³
2. runtime_provider.pyを通じてruntime providerを解決します。このステップでauth、base URL、API modeが選ばれます³
3. chat_completions、codex_responses、anthropic_messagesの3つのAPI modeのいずれかでproviderを呼び出します³
4. 返されたtool callsをmodel_tools.pyと中央tool registry（tools/registry.py）経由でdispatchします³
5. modelが最終応答を生成するまでループし、その後sessionをFTS5付きのSQLiteに永続化します³

このループを理解することが重要なのは、personalities、memory、skills、compression、fallbackといったすべての機能が、これらのいずれかのstageに接続されているためです。config keyを読んで「これは何をするのか」と迷ったとき、答えはたいてい「上のループのstage 1、2、3、または4にあるノブです」となります。

プラットフォーム非依存のcore。 1つのAIAgent classが、CLI、gateway、ACP、batch、API serverを担当します。プラットフォームごとの差異はエントリーポイントにあり、agentそのものにはありません。³ そのため、terminalでもTelegramでも同じslash commandsが動きます。これらはhermes_cli/commands.py内の共有COMMAND_REGISTRYからdispatchされるからです。⁶

ディレクトリ構造そのものがsystemです。 Hermesはすべてを~/.hermes/（またはデフォルト以外のprofileでは$HERMES_HOME）配下に保存します。⁴

~/.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)

上の各ファイルには固有の役割があり、役割の重複はありません。「HermesはXをどこに保存するのか」を探しているなら、この中のどれかです。

v0.18.0の新機能（The Judgment Release）

Hermes Agent v0.18.0（tag v2026.7.1、2026年7月1日）は、judgmentにちなんで名付けられています。agentが成功を主張するのではなく自分の作業を検証すること、そして実際に確認できるensemble reasoningがテーマです。また、P0/P1 backlog全体もクローズされました。およそ692件の最優先項目が12日間で解決されています。²²

• first-class modelとしてのMixture-of-Agents。 MoAはすべてのinterfaceで他のmodelと同じように選択できるようになり、ensemble reasoningも可視化されました。各reference modelの完全な出力が、それぞれラベル付きblockとしてrenderされ、live answer streamingも行われます。不透明にmergeされたanswerを受け取るのではなく、ensembleが考える様子を見られます。²²
• /goalのcompletion contracts。 goal完了を報告する前に、agentがprojectのchecksを実行して自分の作業を検証します。成功を主張するのではなく、自分自身にjudgmentを適用します。²²
• /learn — 何でも説明してskillにできます。 workflowを説明するだけで、再利用可能なskillに変換できます。生成されたskillsは、repoのCONTRIBUTING.md conventionsに自動で準拠します。²²
• /journey timeline。 memoryとskillsの時系列のvisual historyです。編集機能に加え、desktopではmemory graphも利用できます。²²
• background subagent fan-out。 conversationをblockせずに、並行実行される複数のtaskをdelegateできます。v0.17.0の単一background subagentがfleetになります。²²
• Desktop Projects。 project/repo/laneのorganization modelを備えた、first-classなcoding Projectsです。²²
• scale-to-zero gateway。 Gatewaysはidle時に休止でき、seamless deploymentsのためにdrainを調整できます。Hermesを常時稼働serviceとして運用する人には意味のある変更です。²²
• Google Vertex AI support。 GCP service accounts経由でGeminiにアクセスでき、OAuth2 token refreshも自動で行われます。provider catalogに加わりました。²²
• /prompt editor command。 input lineと格闘する代わりに、multi-line promptsを作成するために$EDITORを開きます。²²

v0.17.xからupgradeする場合、ここでCLIが壊れることはありません。upgradeする主な理由は、completion contracts（自分自身を検証するgoals）、inspect可能なensembleを備えたfirst-class MoA、そしてskill captureのための/learnです。

v0.17.0の新機能（The Reach Release）

Hermes Agent v0.17.0（tag v2026.6.19、2026年6月19日）は、agentが届く範囲が広がったことにちなんで名付けられています。新しいmessaging channels、新しいmodel providers、そしてより深いdesktopとdashboard controlが追加されました。v0.16.xへのadditiveな更新であり、CLI surfaceは変わっていません。²¹

• 新しいmessaging channels。 iMessageはMac relayなしで動作するようになりました。Photon Spectrum（device-code OAuth、hermes photon login）を使います。WhatsApp Business Cloud APIは、bridge-process要件を置き換える公式Meta adapterです。SimpleXにはgroups、native attachments、text batching、auto-acceptが追加されました。さらにRaftが、privacy-by-contract wake-channel designを備えたbundled platform pluginとして加わりました。²¹
• 新しいmodelsとproviders。 catalogにz-ai/glm-5.2（1M context）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra、grok-composer-2.5-fast（xAI OAuth経由のCursor model、200k context）が追加されました。xAIのdefaultはgrok-build-0.1に移り、Anthropic adaptive modelsはmodern thinking contractに従うようになりました（reasoning fieldは送信されません）。²¹
• Desktopとdashboard。 Desktopには、delegated activityをliveな「watch-windows」でstreamingするbackground subagents（delegate_task(background=true)）、Composer model selector、再バインド可能なkeyboard shortcuts、native OS notifications、threadごとのcomposer drafts、VS Code Marketplace themes、日本語と繁体字中国語UIが追加されました。dashboardには、config.yamlを編集せずにmodel/skills/MCPsを設定できるfull profile builder、global profile switcher、security scan付きに刷新されたSkills Hub、Automation Blueprints（form、slash command、conversation、docsをまたぐparameterized templates）、そしてOAuth gateの背後で401を返すsecure loginが追加されました。²¹
• Skillsとtools。 image_generateは、すべての対応image providerで、source imageのeditとtransformもできるようになりました。最初から画像を生成するだけではありません。memory toolには、1回のcallでatomic batch add/replace/removeを行うためのoperations arrayが追加されました。新しいsimplify-code skillは、Chesterton’s-Fence risk tierでgateされた、parallel three-agent review-and-cleanup passを実行します。また、tri-stateのwrite_modeはbooleanのwrite_approvalに置き換えられました。²¹
• Architecture。 Background subagentsはhandleを即座に返し、その結果を新しいturnとして再投入します。MCP elicitation handlerにより、tool call中のconfirmationが可能になりました。また、遅れて接続されたMCP toolsはturn間で公開されます（cache-safe）。cronはChronos managed-cron providerを備えたpluggable CronSchedulerになりました。さらに新しいManaged scope（/etc/hermes）により、administratorがuser-immutable configを固定できるようになり、multi-gateway topologies向けのGateway-Gateway relayも追加されました。²¹
• 新しいcommands。 /version、/billing（interactive terminal billing）、hermes photon login（iMessage auth）、hermes curator run --consolidateです。consolidationはopt-inになったため、通常のbackground curationはtoken costがゼロです。²¹
• Security。 v0.17.0では、shell-escape denylist bypassを閉じ、approval modulesやown-policy gateway adaptersがない場合はfail closedし、cron job-script subprocessesのenvironmentをsanitizeし、request debug dumps内のsecretsをredactし、MCP stdio configsのexfil patternsをscreeningし、urllib3とPyJWTを更新してCVEsを解消しています。²¹

v0.16.xからupgradeする場合、ここでCLIが壊れることはありません。同じagentの周囲に、新しいchannels、models、surfacesが追加されています。relay-free iMessage、公式WhatsApp adapters、administrator向けのManaged scopeが、upgradeする主な理由です。

v0.16.0 の新機能（The Surface Release）

Hermes Agent v0.16.0（タグ v2026.6.5、2026年6月5日）は、CLI ファーストの agent の前面に新しい操作面を追加したことから名付けられています。最大のポイントは、Hermes がもはや terminal 専用ではなくなったことです。²⁰

• ネイティブ desktop アプリ。 Hermes Desktop は、macOS、Linux、Windows 向けの新しい Electron アプリです。ワンクリック install とアプリ内 self-update に対応しています。ストリーミング chat window、drag-and-drop files、clipboard image paste、Cmd+K palette、archive と search 付きの session list、status-bar model picker を利用できます。secure WebSocket 経由で remote Hermes gateway に接続でき、OAuth または username/password で認証します。profile ごとの remote hosts と、cross-profile @session references で結ばれた concurrent multi-profile sessions にも対応しています。desktop UI には、typed i18n layer（display.language。default は English のまま）による完全な Simplified Chinese（简体中文）翻訳も同梱されています。²⁰
• Browser admin panel。 local web dashboard は status view から本格的な administration panel へ進化しました。MCP catalog と enable/disable toggles、credential management、webhook と hook creation、memory configuration、gateway controls、さらに check-before-update と one-click Debug Share を備えた System page を利用できます。新しい Channels page では、すべての gateway messaging platform（Telegram、Discord、Slack など）を browser から設定できます。Auth は pluggable になり、username/password login、generic self-hosted OIDC provider、self-hosted OAuth client 用の hermes dashboard register、refresh-token session rotation に対応しました。²⁰
• 新しい CLI と slash commands。 /undo [N] は直近 N 回の user turns を prefill と soft-delete 付きで戻せます。CLI、TUI、messaging platforms 全体で動作します。設定可能な default interface（cli と tui）が入り、--cli override も使えます。TUI には統合された /model command と Sessions overlay が追加されました。hermes portal は Nous Portal onboarding flow の人間が読みやすい alias です。first-run path として Quick Setup と Full Setup が追加され、hermes prompt-size と hermes sessions optimize という 2 つの diagnostics も加わりました。²⁰
• 新しい models と providers。 picker には deepseek-v4-flash、MiniMax-M3（1M context、native MiniMax providers）、qwen3.7-plus（Nous + OpenRouter）、gemini-3.5-flash（Gemini OAuth + API key）が追加されました。first-class な xAI Grok OAuth provider が desktop launcher に加わり、model picker はすべての surface で fuzzy に使えるようになりました。multi-endpoint providers は 1 行にまとめられ、catalog refresh は daily から hourly に変更されています。²⁰
• より軽量な skills と progressive disclosure。 default skill set からは、重複した skill や使われなくなった skill が削除されました（Spotify は native plugin へ、Linear は hermes mcp install linear へ移り、古い entries もいくつか削除されています）。より多くが optional に移され、environments: frontmatter relevance gate（kanban/docker/s6）が追加されました。これにより、context-specific skills は要求されるまで index に出ません。NVIDIA/skills は、OpenAI、Anthropic、HuggingFace と並ぶ default trusted Skills Hub tap になりました。MCP と plugin tools には progressive（scoped）tool disclosure が追加され、token が取得されていないのに OAuth 成功と誤って報告する MCP bug も修正されています。²⁰
• Security。 v0.16.0 は CVE-2026-48710（BadHost）対応済みの patched Starlette（≥1.0.1）を pin し、async paths では SSRF URL checks を event loop から外しました。また、Bedrock inference bearer token を subprocess env から除去し、bws_cache.json を file-safety read guard に追加し、dangerous-pattern list に docker restart/stop/kill を加え、vetted skill content 内の invisible-unicode を sanitize します。この release では 2 件の P0 と 62 件の P1 issues が close され、そのうち 16 件には security tag が付いていました。²⁰

v0.15.x から upgrading する場合、これらは CLI 自体に対する breaking change ではありません。同じ agent の周辺に surfaces と providers を追加する変更です。non-terminal users 向けに Hermes を動かしたい場合や、browser から remote gateway を管理したい場合は、desktop app と admin panel が upgrade する理由になります。

Installation

ほとんどの users には、one-line installer が引き続き guided path です。Python、uv、Node.js、ripgrep、ffmpeg、repo clone、virtual environment、global hermes command まで処理します。⁷ v0.14.0 では実際の PyPI package も提供されているため、すでに Python environment を管理している場合は、pip install hermes-agent で直接 install する方法も現実的になりました。¹⁹

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

pip install hermes-agent
hermes

Linux、macOS、WSL2、Android/Termux で動作します（installer は Termux を auto-detect し、tested Android bundle に切り替えます）。⁷ v0.14.0 では PowerShell installer による native Windows support が early beta として追加されていますが、Windows path が成熟するまでは、production use では WSL2 を推奨するほうが安全です。¹⁹

完了したら、次を実行します。

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

唯一の prerequisite は git です。installer は uv 経由で Python 3.11（sudo 不要）、Node.js v22（browser automation と WhatsApp bridge 用）、ripgrep、ffmpeg を auto-provision します。⁷

install を確認する

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 は、何が不足しているか、どう直せばよいかを正確に教えてくれます。⁷ hermes dump は、help を求めるときに GitHub issue や Discord thread へ貼るための diagnostic command です。secrets は redacted された、setup 全体の plain-text summary になります。⁸

Manual installation

custom Python version、specific extras、Nix/NixOS integration など、完全な control が必要な場合は、upstream installation guide に manual flow が step-by-step で記載されています。⁷ uv pip install -e ".[<extras>]" と組み合わせられる主な optional extras は次のとおりです。

Termux install command は異なります。uv pip ではなく、constraints file 付きの pip を使います。

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

これは、Android で .[all] を使うと voice extra 経由で faster-whisper が取り込まれ、それが Android 向けに publish されていない ctranslate2 wheels に依存しているためです。⁷

認証と Providers

Hermes は、約19のファーストクラス providers と custom endpoints、そして3つの認証パスに対応しています。ここでは認証まわり全体をパス別に整理し、手元の環境に合うものを見つけやすくしています。

3つの認証パス

Hermes のすべての provider は、次の3つの認証パターンのいずれかに当てはまります。

Path 1 — .env の API key。 key を ~/.hermes/.env に入れると、Hermes が起動時に読み込みます。OpenRouter、AI Gateway、z.ai/GLM、Kimi/Moonshot、MiniMax（MiniMax China を含む）、Alibaba Cloud/DashScope、Kilo Code、OpenCode Zen、OpenCode Go、DeepSeek、Hugging Face、Google/Gemini、そして大半のサードパーティ providers で使います。²

Path 2 — hermes model または hermes auth 経由の OAuth。 デバイスコードフローを起動し、ブラウザを開き、認証情報を ~/.hermes/auth.json に保存します（Claude Code や Codex CLI などのツールから既存の認証情報をインポートすることもできます）。Nous Portal、OpenAI Codex（ChatGPT アカウント）、GitHub Copilot、Anthropic（Claude Pro/Max）で使います。²

Path 3 — config.yaml の custom endpoint。 OpenAI 互換の API なら何でも対象です。Ollama、vLLM、SGLang、llama.cpp、LM Studio、LiteLLM proxy、Together AI、Groq、Azure OpenAI、自前のセルフホストサーバーなどです。hermes model → Custom endpoint で一度設定すると、config.yaml に保存されます。²

Full Provider Matrix

これは、ファーストクラス providers の完全な一覧と、それぞれの正確なセットアップフローです。²

Anthropic: 3つの認証方法

Anthropic は独立したセクションで扱います。Hermes は Claude への3つの異なるパスに対応しており、適切なものを選ぶことが重要だからです。upstream docs では次のように説明されています。²

# 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

hermes model から Anthropic OAuth を選ぶと、Hermes は token を ~/.hermes/.env にコピーするよりも、Claude Code 自身の credential store を優先します。これにより、更新可能な Claude credentials を更新可能なまま保てます。² 同じマシンで既に Claude Code を使っているなら、これが最もすっきりしたパスです。

Anthropic を config.yaml に恒久的に固定するには、次のようにします。

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

--provider claude と --provider claude-code も、--provider anthropic の短縮形として使えます。²

GitHub Copilot: 2つのモード

Copilot は2つのモードに対応しています。直接の Copilot API（推奨）と Copilot ACP（ローカルの Copilot CLI を subprocess として起動）です。²

# 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

upstream docs によると、認証は次の順序で確認されます。² 1. COPILOT_GITHUB_TOKEN environment variable 2. GH_TOKEN environment variable 3. GITHUB_TOKEN environment variable 4. gh auth token CLI fallback 5. hermes model による OAuth デバイスコード login

Token type が重要です。 Copilot API は classic Personal Access Tokens（ghp_*）に対応していません。対応しているのは、OAuth tokens（gho_*）、fine-grained PATs（Copilot Requests permission 付きの github_pat_*）、GitHub App tokens（ghu_*）です。gh auth token が ghp_* token を返す場合は、代わりに hermes model で OAuth 経由の認証を行ってください。²

Chinese AI Providers（ファーストクラス対応）

Hermes は、z.ai/GLM、Kimi/Moonshot、MiniMax（global + China endpoints）、Alibaba Cloud に組み込み対応しており、それぞれ専用の provider IDs があります。²

# 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

Base URLs は、GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL environment variables で上書きできます。²

Z.AI は endpoint を自動検出します。 z.ai/GLM provider を使う場合、Hermes は複数の endpoints（global、China、coding variants）をプローブし、手元の API key を受け付けるものを探します。動作する endpoint は自動的にキャッシュされるため、多くのユーザーは GLM_BASE_URL を指定する必要がありません。²

xAI (Grok) は prompt caching を自動で有効にします。 base URL に x.ai が含まれる場合、Hermes は会話セッション内で同じサーバーにルーティングするため、すべてのリクエストに x-grok-conv-id header を送信します。これにより、キャッシュ済みの system prompts と history を再利用できます。² 自動で行われるため、設定は不要です。

hermes auth Command

hermes auth は、pools と OAuth credentials を管理するための credential management command です。⁶

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

Credential pools は、同じ provider に対して複数の API keys や OAuth tokens をローテーションする仕組みです。コードを変更せずに、複数の keys に rate limits を分散したい場合に便利です。⁶ 旧来の hermes login / hermes logout commands は削除されています。代わりに hermes auth を使ってください。⁶

Custom & Self-Hosted Endpoints

Hermes は、OpenAI 互換の API endpoint なら何でも動作します。サーバーが /v1/chat/completions を実装していれば、Hermes の向き先にできます。²

Interactive setup（推奨）:

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

手動の config.yaml:

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

どちらの方法でも config.yaml に保存されます。これは main-model、provider、base URL の single source of truth です。² 旧来の env vars OPENAI_BASE_URL と LLM_MODEL は、main-model configuration ではもう読み込まれません。hermes model を使うか、config.yaml を直接編集してください。²（OPENAI_BASE_URL + OPENAI_API_KEY は、補助的な provider: "main" ルーティングパスの fallback としては引き続き尊重されます。そこで使っている場合は、むやみに削除しないでください。）⁴

セッション中に custom endpoints を切り替える:

/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（単独で、model name なし）は endpoint の /v1/models API を照会し、読み込まれている model がちょうど1つなら自動選択します。単一 model を動かしている local servers に便利です。²

Local LLM Servers（セットアップテンプレート）

upstream docs には、Ollama、vLLM、SGLang、llama.cpp、LM Studio の完全なセットアップガイドがあります。ここでは実際に実行する主要コマンドを示します。いずれも、Hermes の向き先にできる動作する endpoint を作るように設計されています。²

Ollama — 最も簡単なローカルパス、設定不要:

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

重要な Ollama の注意点: Ollama のデフォルト context lengths は非常に低く設定されています（24GB VRAM 未満では 4,096 tokens）。OLLAMA_CONTEXT_LENGTH または Modelfile で引き上げる必要があります。OpenAI 互換の API は client から context length を受け付けないため、Hermes 側では設定できません。² agent 用途では、少なくとも 16k〜32k に設定してください。

vLLM — 高性能な GPU serving:

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

Tool calling には --enable-auto-tool-choice と --tool-call-parser <name> が必要です。対応 parsers は、hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic です。これらの flags がない場合、tool calls は plain text として返ってきます。²

SGLang — KV cache reuse 向け RadixAttention による高速 serving:

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

SGLang の注意点: デフォルトの max_tokens は 128 です。応答が途中で切れる場合は、server 側で --default-max-tokens を設定するか、config.yaml の model.max_tokens を設定してください。²

llama.cpp / llama-server — CPU と 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

tool calling には --jinja が必須です。 これがないと、llama-server は tools parameter を完全に無視し、model は応答テキスト内に JSON を書いて tools を呼び出そうとします。Hermes はそれを実際の tool calls として解析できません。²

LM Studio — GUI 付きデスクトップアプリ:

LM Studio アプリから server を開始します（Developer tab → Start Server）。または CLI から lms server start（port 1234 で起動）と lms load qwen2.5-coder --context-length 32768 を実行します。² その後、hermes model を http://localhost:1234/v1 に向けます。

重要な LM Studio の注意点: LM Studio は model metadata から context length を読み込みますが、多くの GGUF models はデフォルトとして 2048 または 4096 を報告します。LM Studio の model settings で、必ず context length を明示的に設定してください。model picker の横にある gear icon をクリックし、”Context Length” を少なくとも 16384（できれば 32768）に設定して、model を再読み込みします。²

Named Custom Providers

複数の custom endpoints（たとえば local dev server と remote GPU server）を使う場合は、config.yaml で named custom providers として定義します。²

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

その後、triple syntax でセッション中に切り替えられます。

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

interactive な hermes model menu から named custom providers を選ぶこともできます。²

Pluggable Provider Architecture（v0.13.0+）

v0.13.0 では、ProviderProfile ABC と plugins/model-providers/ directory が同梱され、サードパーティ inference providers を core modifications なしで追加できるようになりました。¹⁸ provider が OpenAI、Anthropic、または Codex 互換の API mode を話せるなら、auth path、base URL、model catalog、caching headers を宣言する ProviderProfile subclass を実装できます。Hermes は組み込み providers と同じ runtime_provider.py パスでそれを解決します。これが v0.13.0 の provider 拡張の背後にあるアーキテクチャ変更です。provider を追加するために core code を編集するのではなく、plugin として出荷できます。

OpenAI-Compatible Local Proxy（v0.14.0+）

hermes proxy は、Hermes が既にサインインしている OAuth provider（Claude Pro、ChatGPT Pro、SuperGrok、または別の互換設定済み provider）をバックエンドにした OpenAI 互換の local endpoint を公開します。¹⁹ つまり、Codex CLI、Aider、Cline、Continue、custom scripts など、OpenAI 形式の API を期待する tools が、別個の API key なしで、サブスクリプションに紐づく Hermes auth を再利用できます。この proxy は local developer infrastructure として扱ってください。意図して bind し、広く公開せず、provider 固有の terms を念頭に置きます。

Context Length Detection

upstream docs によると、次の2つの設定はよく混同されます。²

• context_length — context window 全体（input + output token budget の合計。例: Claude Opus 4.7 なら 1,000,000、Sonnet 4.6 なら 200,000）。Hermes はこれを使って history を圧縮するタイミングを判断します。
• model.max_tokens — output cap（model が1回の response で生成できる最大 tokens）。history length とは無関係です。

自動検出が window size を誤る場合は、context_length を設定します。

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

Hermes は、context windows を検出するために複数ソースの解決チェーンを使います。config override → custom provider per-model → persistent cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev（3800以上の models に対応する community-maintained registry）→ fallback defaults（128K）です。² このシステムは provider-aware なので、同じ model でも提供元によって context limits が異なる場合があります（例: claude-opus-4.6 は Anthropic direct では 1M ですが、GitHub Copilot では 128K です）。²

Provider Rotation & Fallback

Credential pools。 同じ provider に複数の API keys がある場合は、hermes auth で rotation strategy を設定します。これにより、複数の keys に rate limits を分散できます。⁶

Fallback model。 primary model が失敗したとき（rate limits、server errors、auth failures）に Hermes が自動的に切り替える backup provider:model を設定します。²

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 は会話を失わずに、セッション中に model と provider を切り替えます。発火するのは1セッションにつき最大1回です。² fallback 対応 providers は、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 です。²

Auxiliary Models

Hermes は、image analysis、web page summarization、browser screenshot analysis、dangerous command approval classification、context compression、session search summarization、skill matching、MCP tool dispatch、memory flush などの補助タスクに、軽量な “auxiliary” models を使います。⁴ デフォルトでは、自動検出（OpenRouter → Nous → Codex）経由の Gemini Flash が使われます。

各 auxiliary task が使う model と provider は設定できます。 すべての auxiliary slot は、同じ3つの knobs、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 }

"main" provider option は「main agent が使っている provider を使う」という意味です。これは auxiliary:、compression:、fallback_model: configs の中でのみ 有効です。top-level の model.provider 設定では使えません。main model として custom OpenAI-compatible endpoint を使う場合は、model: section で provider: custom を設定してください。⁴

これが重要な理由: Anthropic OAuth だけを設定している場合（OpenRouter key なし）、vision、web summarization、compression は品質低下または失敗します。デフォルトの auxiliary fallback chain が OpenRouter を最初に試すためです。auxiliary tasks 用に OPENROUTER_API_KEY を追加するか、各 auxiliary slot を main provider を使うよう再設定してください。

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

これは、新規 Hermes ユーザーに最もよくある「機能が黙って動かない」注意点です。

設定システム

Hermesには階層化された設定システムがあります。上位の層が下位の層を上書きし、その層の1つにはconfig.yamlからは見えないグローバルな provider レジストリが含まれるため、優先順位を理解しておくことが重要です。

設定ファイルの構成

上流ドキュメントによると、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 と .env — 両方が設定されている場合、secret 以外の設定では config.yaml が優先されます。⁴ ルールは次のとおりです。 - Secrets（API keys、bot tokens、passwords）→ .env - それ以外すべて（model、terminal backend、compression settings、memory limits、toolsets）→ config.yaml

Secrets は、shell 形式の補間を使って config.yaml から参照できます:⁴

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

設定の管理

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

例:⁴

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 と hermes config migrate は、hermes update のたびに実行するコマンドです。まだファイルに存在しない、新しく追加された設定オプションを検出できます。⁶

設定の優先順位

Hermesは複数のソースから設定を読み込みます。同じ値が複数のソースで設定されている場合、優先度の高いソースが勝ちます:⁴

1. CLI arguments — hermes chat --model anthropic/claude-sonnet-4（呼び出しごとの上書き）
2. 環境変数 — プロセス起動時に適用されます
3. config.yaml — 主要な設定ファイル
4. .env — secrets のみ
5. 組み込みのデフォルト — 他に値が設定されていない場合に適用されます

CLI flags は、その1回の呼び出しでは常に最優先されます。config.yaml は長期的な信頼できる設定元です。

ローカライズ（v0.13.0+）

v0.13.0では、CLI と gateway メッセージ向けに 7つの locale が追加されました。中国語（簡体字）、日本語、ドイツ語、スペイン語、フランス語、ウクライナ語、トルコ語です。¹⁸ v0.14.0では、すべての gateway コマンドと web dashboard がローカライズされ、さらに8つの locale が追加され、合計は16になりました。¹⁹ 現在、ドキュメントのローカライズは zh-Hans のみです。Locale は LC_ALL / LANG 環境変数、または config.yaml 内の明示的な locale: key から解決されます。英語は引き続きデフォルトであり、翻訳がまだ対応していない文字列については信頼できる元になります。

Profiles — 分離された複数の Hermes インスタンス

Profiles を使うと、それぞれ独自の config、sessions、skills、memory、gateway PID を持つ、分離された複数の Hermes インスタンスを利用できます。これにより、「仕事用 Hermes」と「個人用 Hermes」を並行して実行しつつ、互いの状態が見えないようにできます。⁶

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

各 profile には独自の HERMES_HOME（デフォルトでは ~/.hermes-<name>/）が割り当てられるため、複数の profile で gateway を同時に実行しても互いに干渉しません。⁶³

CLI コマンド

このセクションは、トップレベルの CLI コマンドを実務で参照するためのものです。コード由来の正式な参照情報については、 upstream の CLI Commands Reference をご覧ください。⁶

グローバルオプション

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

トップレベルコマンド

hermes chat — メインのエントリーポイント

引数なしで hermes を実行すると、インタラクティブチャットに入ります。hermes chat は、オプション付きの明示的な形式です。⁶

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"

主なオプション:

hermes setup — フルウィザード

フルセットアップウィザードを実行するか、特定のセクションに直接移動します。⁶

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 — 構造化ログクエリ

hermes logs は、level、session ID、time range によるフィルタリングを同時にサポートするため、ログファイルに対する tail -f よりも強力です。⁶

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

ログファイルは ~/.hermes/logs/ にあります。⁶ - agent.log — すべての agent activity（API calls、tool dispatch、session lifecycle、INFO+） - errors.log — warning と error のみ（agent.log のフィルタリング済みサブセット） - gateway.log — messaging gateway activity（platform connection、dispatch、webhook）

ローテーションは Python の RotatingFileHandler によって自動的に行われます — agent.log.1、agent.log.2 などを確認してください。⁶

hermes doctor — 診断

hermes doctor [--fix] は、何か問題が起きたときに最初に実行するコマンドです。設定の妥当性、依存関係の有無、API key の利用可否、service status を確認し、--fix による自動修復も試行できます。⁶

診断結果をほかの人と共有する場合は、hermes dump を使います。API key が秘匿されたコンパクトなプレーンテキスト概要を生成し、GitHub issue や Discord thread にそのまま貼り付けられます。⁶

Slash Commands

Slash commandsは、アクティブなチャットセッション（CLIまたはメッセージングプラットフォーム）内で実行されます。hermes_cli/commands.pyの共有COMMAND_REGISTRYからディスパッチされるため、ほとんどのコマンドは各サーフェスで同じように動作します。⁹

セッション制御

設定とModel

/modelコマンドは、セッション途中でproviderを切り替えるための主力です。⁹

/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

ツール、Skills、情報

動的なSkill Slash Commands

インストール済みの各skillは、自動的にslash commandとして公開されます。⁹

/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

config.yamlでquick commandsを定義し、短い名前を長いpromptのaliasにすることもできます。⁹

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"

その後、CLIで/review、/deploy、または/morningと入力します。

Prefix Matching

コマンドはprefix matchingに対応しています。/hと入力すると/helpに、/modは/modelに解決されます。prefixが曖昧な場合は、registry順で最初に登録されたものが優先されます。完全なコマンド名と登録済みaliasは、常にprefix matchesより優先されます。⁹

メッセージング専用コマンド

一部のコマンドは、メッセージングプラットフォーム（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）でのみ動作します。⁹

• /status — セッション情報を表示します
• /sethome（alias /set-home） — 現在のチャットをplatform homeとして設定します
• /approve [session|always] — 保留中の危険なコマンドを承認します
• /deny — 保留中の危険なコマンドを拒否します
• /update — Hermes Agentをlatestへ更新します
• /commands [page] — すべてのコマンドとskillsを閲覧します（ページ分割）

また、CLI専用のものもあります: /skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins。⁹

Tools と toolsets

Hermes には、web 検索、browser automation、terminal 実行、ファイル編集、memory、delegation、RL training、messaging delivery、Home Assistant integration などをカバーする幅広い組み込みツールレジストリが同梱されています。¹⁰ Tools は論理的な toolsets に整理されており、プラットフォームごとに有効化または無効化できます。

上位カテゴリ

一般的な toolset 名には、web、terminal、file、browser、vision、image_gen、moa、skills、tts、todo、memory、session_search、cronjob、code_execution、delegation、clarify、homeassistant、rl があります。¹⁰

Tools の管理

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

Tools はセッション中にも /tools disable <name> と /tools enable <name> で切り替えられます。これによりセッションがリセットされ、新しい tool set が反映されます。⁹

Terminal バックエンド

terminal ツールは、6 種類の環境でコマンドを実行できます。¹⁰

バックエンドは hermes config set terminal.backend <name>、または config.yaml で切り替えます。

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

SSH バックエンド（セキュリティ上推奨です。agent が自身のコードを変更できません）:¹⁰

terminal:
  backend: ssh

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

Docker バックエンド:

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

コンテナリソース（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

container_persistent: true を設定すると、インストール済みパッケージ、ファイル、設定がセッションをまたいで保持されます。¹⁰

すべてのコンテナバックエンドは、セキュリティ強化を有効にして実行されます。読み取り専用 root filesystem（Docker）、DAC_OVERRIDE、CHOWN、FOWNER を除くすべての Linux capabilities の削除、権限昇格なし、PID 制限（256 プロセス）、完全な namespace isolation、volumes による永続 workspace が含まれます。¹⁰

Background Processes

terminal ツールは、明示的なプロセス管理を伴う background execution をサポートしています。¹⁰

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

PTY mode（pty=true）では、Codex や Claude Code のようなインタラクティブな CLI ツールを利用できます。¹⁰

Sudo

コマンドに sudo が必要な場合、Hermes はパスワードの入力を求めます（セッション中はキャッシュされます）。または、~/.hermes/.env に SUDO_PASSWORD を設定します。¹⁰

Multi-Agent Kanban（v0.13.0+）

v0.13.0 では、multi-agent collaboration が第一級のプリミティブになります。つまり、agents 間および再起動をまたいでタスク、ステータス、worker identity を追跡する durable Kanban board です。¹⁸ この board によって、Hermes workers の swarm は、途切れた引き継ぎで停止するのではなく、実際に作業を完了できるようになります。

Kanban board は、ターゲット側では /goal（locked-target Ralph loop）と自然に組み合わさり、spawn semantics では既存の delegate_task ツールと組み合わさります。その結果、すべての agent が「次に何をするか」「誰がそれを担当しているか」「何が詰まっているか」について、1 つの信頼できる情報源を共有する swarm pattern が実現します。

Skills System

skillは、必要なときにagentが読み込めるオンデマンドの知識ドキュメントです。トークン使用量を最小限に抑えるためにprogressive disclosureパターンに従っており、agentskills.ioのオープン標準と互換性があります。¹¹

すべてのskillは~/.hermes/skills/にあります — ここが主要ディレクトリであり、信頼できる唯一の情報源です。新規インストール時には、同梱skillがrepoからコピーされます。Hubからインストールしたskillやagentが作成したskillも、ここに配置されます。¹¹

Progressive Disclosure

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は、実際に必要になったときだけskillの全文を読み込みます。¹¹

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.

条件付き有効化

skillは、利用可能なツールに応じて自身を表示または非表示にできます。これはfallback skillで特に有用です。つまり、有料ツールが利用できない場合にだけ表示されるべき、無料またはローカルの代替手段です。¹¹

例: 組み込みのduckduckgo-search skillは、fallback_for_toolsets: [web]を使用します。FIRECRAWL_API_KEYが設定されている場合、web toolsetが利用可能になり、agentはweb_searchを使用します。そのためDuckDuckGo skillは非表示のままです。API keyがない場合、DuckDuckGo skillがfallbackとして自動的に表示されます。¹¹

Agent管理のskill

agentは、skill_manageツールを通じて自身のskillを作成、更新、削除できます。これはagentのprocedural memoryです。複雑なworkflowを見つけたとき、その手順を今後再利用できるようskillとして保存します。¹¹

agentがskillを作成するタイミング:¹¹ - 複雑なタスク（5回以上のツール呼び出し）を正常に完了した後 - エラーや行き止まりに遭遇し、動作する手順を見つけたとき - ユーザーがagentの進め方を修正したとき - 自明ではないworkflowを発見したとき

アクション:¹¹

Skill Hub

オンラインregistryからskillを閲覧、検索、インストール、管理できます。⁶¹¹

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

統合済みhubソース:¹¹

デフォルトのGitHub taps（設定なしで閲覧可能）: openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack。¹¹

Security Scanning

Hubからインストールされたすべてのskillは、data exfiltration、prompt injection、破壊的コマンド、supply-chain signals、その他の脅威を確認するsecurity scannerを通過します。¹¹

信頼レベル:¹¹

--forceは、community skillに対する危険ではないポリシーブロックを上書きできます。ただし、dangerousのscan verdictは上書きしません。¹¹

外部skillディレクトリ

Hermesに追加のskillディレクトリを指定し、ローカルのディレクトリと一緒にスキャンできます。¹¹

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

pathは~展開と${VAR}環境変数置換に対応しています。外部ディレクトリは読み取り専用です。agentがskillを作成または編集する場合、常に~/.hermes/skills/へ書き込みます。両方の場所に同じskill名が存在する場合は、ローカルが優先されます。¹¹

永続メモリ

Hermesには、セッションをまたいで保持される、範囲を絞って整理されたメモリがあります。エージェントのメモリは2つのファイルで構成され、どちらも~/.hermes/memories/に保存されます:¹²

どちらも、セッション開始時点の固定スナップショットとしてシステムプロンプトに注入されます。エージェントはmemoryツールを使い、add、replace、removeによって自分のメモリを管理します。¹²

固定スナップショットパターン: システムプロンプトへの注入はセッション開始時に1回だけ取得され、セッション中に変わることはありません。これは意図的な設計です。パフォーマンスのためにLLMのプレフィックスキャッシュを維持するためです。セッション中に加えた変更はすぐにディスクへ保存されますが、次のセッションまでシステムプロンプトには反映されません。¹²

保存すべき内容

保存するもの（エージェントが能動的に行います）:¹² - ユーザーの好み: 「JavaScriptよりTypeScriptが好み」→ user - 環境情報: 「このサーバーはDebian 12とPostgreSQL 16で動作している」→ memory - 修正事項: 「Dockerコマンドにsudoは使わない。ユーザーはdockerグループに所属している」→ memory - 慣例: 「プロジェクトではタブ、120文字の行幅、Googleスタイルのdocstringを使う」→ memory - 完了した作業: 「2026年1月15日にデータベースをMySQLからPostgreSQLへ移行した」→ memory

保存しないもの:¹² - 些細な情報、明らかな情報 - 簡単に再発見できる事実 - 生データのダンプ（メモリには大きすぎます） - セッション固有の一時的な情報 - すでにコンテキストファイルにある情報

セッション検索

MEMORY.mdとUSER.mdに加えて、エージェントはsession_searchツールで過去の会話を検索できます。すべてのCLIセッションとメッセージングセッションはSQLite（~/.hermes/state.db）に保存され、FTS5全文検索を利用できます。クエリは、Gemini Flashによる要約付きで関連する過去の会話を返します。¹²

外部メモリプロバイダー

MEMORY.mdとUSER.mdを超える、より深い永続メモリのために、Hermesには8つの外部メモリプロバイダープラグインが付属しています: Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemory。¹²

外部プロバイダーは組み込みメモリを置き換えるのではなく、並行して動作します。ナレッジグラフ、セマンティック検索、自動的な事実抽出、セッション横断のユーザーモデリングといった機能を追加できます:⁶¹²

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)

有効にできる外部プロバイダーは一度に1つだけです。組み込みメモリは常に有効です。⁶

セッション自動再開（v0.13.0以降）

v0.13.0では、エージェント実行中の中断から復帰できるようになりました。gatewayは再起動後に中断されたセッションを自動再開します。/updateによる再起動ではアップグレード中もセッション状態が保持され、開発中のソースファイル再読み込みでも、新しいセッションを強制せずにアクティブなセッションを維持します。¹⁸ 実用上の効果として、長時間実行されるgateway作業やcron駆動のジョブは、プロセス再起動時にコンテキストウィンドウをリセットしなくなります。

Checkpoints v2（v0.13.0以降）

v0.13.0では、状態の永続化が実際の枝刈り、ディスク保護、孤立したシャドウリポジトリなしの単一ストア設計として書き直されました。¹⁸ 以前のcheckpointシステムは、長時間実行されるprofileでディスク上に状態を蓄積していました。v2ストアでは、ローカルcheckpointストレージに厳格な上限を設け、その増加を招いていた重複した記録管理を削除しています。ユーザー向けの設定変更は不要です。次回のcheckpoint書き込みからv2のパスが使われます。

パーソナリティとSOUL.md

SOUL.mdはHermesインスタンスの主要なアイデンティティです。システムプロンプトのスロット#1を占め、ハードコードされたデフォルトのアイデンティティを置き換えます。¹³

Hermesは、デフォルトのSOUL.mdを~/.hermes/SOUL.md（カスタムprofileでは$HERMES_HOME/SOUL.md）に自動で作成します。既存のユーザーファイルが上書きされることはありません。HermesはHERMES_HOMEからのみSOUL.mdを読み込みます。現在の作業ディレクトリは参照しません。これにより、プロジェクトをまたいでもパーソナリティが予測しやすくなります。¹³

SOUL.mdに入れるべき内容

継続的な声やパーソナリティの指針に使います:¹³ - トーン - コミュニケーションスタイル - 率直さの度合い - デフォルトの対話スタイル - 文体上避けるべきこと - 不確実性、意見の相違、曖昧さへのHermesの向き合い方

あまり向いていないもの:¹³ - 単発のプロジェクト指示 - ファイルパス - リポジトリの慣例 - 一時的なワークフロー詳細

それらはSOUL.mdではなく、AGENTS.mdに入れるべきです。

SOUL.mdとAGENTS.md

Hermesのアイデンティティ管理で最も重要な違いは次のとおりです:¹³

SOUL.md — アイデンティティ、トーン、スタイル、コミュニケーションのデフォルト、パーソナリティレベルの振る舞い。

AGENTS.md — プロジェクトアーキテクチャ、コーディング規約、ツールの好み、リポジトリ固有のワークフロー、コマンド、ポート、パス、デプロイメモ。

便利な判断基準はこうです。どこへ行っても持ち歩くべきものはSOUL.mdへ。プロジェクトに属するものはAGENTS.mdへ入れます。¹³

組み込みパーソナリティ

Hermesには、/personalityで切り替えられる組み込みパーソナリティがあります:¹³

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.

その後、/personality codereviewerで切り替えます。

SOUL.mdと/personality

SOUL.mdはベースラインの声です。/personalityはセッションレベルのオーバーレイです。¹³ 実用的なデフォルトのSOUL.mdを保ちつつ、チュートリアルの会話では/personality teacher、ブレインストーミングでは/personality creativeを使うとよいでしょう。

Nous Tool Gateway（v0.10.0以降）

Hermes Agent v0.10.0（2026年4月16日）以降、有料のNous Portal購読者は、既存のPortal認証情報を使って、管理されたツール群へアクセスできます。追加のAPIキーを管理する必要はありません。²⁶ Hermes CLI自体はMITライセンスのままで、完全にオープンソースです。変わったのは、Portal認証でモデル推論以外も利用できるようになった点です。

gatewayに含まれるもの

仕組み

gatewayは、新しいuse_gateway設定フィールドにより、ツールごとにオプトインします。hermes authにPortal認証情報があり、かつ対象ツールでgatewayを有効にしている場合、そのツールの呼び出しはPortal経由になります。それ以外の場合は、直接設定されたAPIキー（存在する場合）が使われます。

# 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

実行時の優先順位: gatewayが利用可能で、ツールにuse_gateway: trueが設定されている場合、Hermesは直接のAPIキーも設定されていてもgatewayを優先します。これは課金に関わります。gateway呼び出しは直接のAPIキーの残高ではなく、Portalサブスクリプションから消費されます。

gatewayを有効にする

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

別途hermes subscribeやhermes login --portalコマンドはありません。サブスクリプションは、hermes authにすでにあるPortal OAuth認証情報から自動的に検出されます。

価格とアクセス

価格とティア名は、Nous Portalの価格ページ（https://portal.nousresearch.com/pricing）で公開されています。このガイドではティアを列挙しません。ティアはHermes CLIではなくPortal製品側の責任範囲であり、Hermesのリリースとは独立して変更されるためです。https://portal.nousresearch.com/で登録し、最新のティアは価格ページで確認してください。

非推奨のお知らせ

• HERMES_ENABLE_NOUS_MANAGED_TOOLS環境変数はv0.10.0で削除されました。管理ツールは現在、ツールごとのuse_gateway設定フィールドで有効化され、Portalサブスクリプションの状態によって制御されます。²⁶

位置づけ: このリリースがそうではないもの

Hermes Agent CLIは、サブスクリプションの背後に制限されているわけではありません。プロジェクトは引き続きMITライセンスで、すべてのコア機能（CLI、skills、memory、messaging gateway、cron、MCP、local dashboard、すべてのプロバイダー向けBYOK）は、誰にも支払わずにエンドツーエンドで動作します。v0.10.0は、すでにNous Portalに支払っているユーザー向けに便利な経路を追加するものです。無料の経路から何かを取り除くものではありません。

Messaging Gateway

Hermes は、単一の gateway プロセスから 22 の messaging platforms に接続する長時間実行の 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、汎用 Webhook adapter です。^325171819 v0.9.0 では、BlueBubbles 経由の iMessage（auto-webhook 登録、setup wizard、クラッシュ耐性）と、enterprise apps 向けの WeCom callback mode を備えた iLink Bot API 経由の native WeChat support が追加されました。¹⁶ v0.11.0 では QQBot が追加されました。²⁵ v0.12.0 では Microsoft Teams と Tencent Yuanbao が追加されました。¹⁷ v0.13.0 では 20 番目の platform として Google Chat が追加され、同じ pluggable adapter architecture を利用しています。IRC と Microsoft Teams も、新しい adapter pattern に移行され、汎用 env_enablement_fn / cron_deliver_env_var plugin hooks に対応しました。¹⁸ v0.14.0 では LINE と SimpleX Chat が追加され、Microsoft Teams stack も Graph auth、webhook listener、pipeline runtime、outbound delivery まで end-to-end で完成しました。¹⁹ v0.17.0（2026年6月19日）では Photon Spectrum 経由の relay-free iMessage（hermes photon login による device-code OAuth、Mac/BlueBubbles relay は不要）、official WhatsApp Business Cloud API adapter（bridge-process requirement を置き換え）、SimpleX groups と native attachments、さらに bundled platform plugin として Raft が追加されました。²¹

セットアップ

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)

interactive setup では、各 platform の接続を順に設定できます。API tokens、bot IDs、channel mappings、allowlists などを設定します。⁶

メッセージの流れ

upstream architecture docs では、次のように説明されています。³

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

すべての messaging platform は、CLI と同じ AIAgent conversation loop を通ります。 そのため slash commands はどちらでも同じように動作し、Telegram で scheduled された cron job の出力を Discord に配信できます。platform の違いは edge にあるだけです。³

ユーザー認可と Pairing

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

Pairing codes によって、見知らぬ相手が gateway に話しかけるのを防げます。ユーザーが messaging platform から pairing code を送信し、hermes pairing approve で承認します。その後、そのユーザーは authorized になります。⁶

Scheduled Tasks (Cron)

Hermes には first-class な cron system があり、jobs は shell commands ではなく agent tasks です。各 scheduled job は、設定された prompt、任意で attached skills を持つ新しい AIAgent を通じて実行され、結果を任意の 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

または、messaging chat の中で会話形式で作成できます。

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

agent は tools を使って cron job を設定します。Jobs は JSON に永続化され、再起動後も保持されます。³

MCP Integration

Hermes は Model Context Protocol を client と server の両方としてサポートしています。⁶

client として — Hermes を外部 MCP servers に接続し、tool surface を拡張できます。

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

または config.yaml で手動設定します。¹⁴

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

server として — Hermes conversations を他の agents に公開できます。

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes は、長い conversations を自動的に圧縮し、model の context window 内に収めます。compression summarizer は独立した LLM call です。任意の provider や endpoint を指定できます。⁴

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

Provider options:⁴

summary_model は、main model と少なくとも同じ大きさの context length をサポートしている必要があります。compression のために conversation の full middle section を受け取るためです。⁴

Budget Pressure Warnings

agent が多くの tool calls を伴う複雑な task に取り組むと、気づかないうちに iteration budget（default: 90 turns）を使い切ることがあります。Budget pressure は model に自動で警告します。⁴

Stream Timeouts

LLM streaming connection には、local providers（localhost、LAN IPs）向けに自動調整される 2 つの timeout layers があります。⁴

local endpoints では、large contexts の prefill に数分かかり、最初の token が出るまで時間がかかることがあります。そのため、socket read timeout は local LLMs 向けに 30 分へ引き上げられます。⁴

Local Web Dashboard（v0.9.0+）

Hermes Agent をローカルで管理するための browser-based dashboard です。config files や terminal に触れずに、設定の変更、sessions の監視、skills の閲覧、gateway の管理ができます。¹⁶ hermes dashboard で起動します。GUI を好む新規ユーザーにとって、最も簡単な onboarding path です。

Background Process Monitoring（v0.9.0+）

watch_patterns では、background process output を監視する patterns を設定し、一致したときに real-time で通知を受け取れます。¹⁶ errors の監視、特定 events（”listening on port”）の待機、build logs の監視を、polling なしで実行できます。v0.8.0 の notify_on_complete（background task completion を通知）と組み合わせることで、Hermes には完全な background process observability layer が備わりました。¹⁵

Pluggable Context Engine（v0.9.0+）

Context management は、hermes plugins を通じた pluggable slot になりました。agent が各 turn で見る内容を制御する custom context engines に差し替えられます。filtering、summarization、domain-specific context injection などに対応できます。¹⁶ これにより context strategy が core agent loop から切り離され、project ごと、domain ごとの context customization が可能になります。

Backup & Restore（v0.9.0+）

hermes backup は、config、sessions、skills、memory の完全な archive を作成します。hermes import は backup archive から復元します。¹⁶ machines 間の移行、大きな変更前の snapshots 作成、teammates との known-good configuration の共有に利用できます。

Termux / Android Support（v0.9.0+）

Hermes は Termux 経由で Android 上に native に動作します。調整済みの install paths、mobile screens 向けの TUI optimizations、voice backend support、/image command が on-device で動作します。¹⁶

Security Hardening（v0.13.0+）

v0.13.0では8件のP0セキュリティ問題が解消され、ユーザーに有利な形でデフォルトが1つ変更されました。¹⁸ 続くv0.14.0では、さらに12件のP0と50件のP1が解消されています。sudoブルートフォース / sudo-stdinのハードニング、危険なコマンドのバイパス修正、モデルへの再注入前のtoolエラーサニタイズ、dashboard plugin API auth、skills-hub SSRF対応、インストール時のサプライチェーンadvisoryスキャンなどが含まれます。¹⁹

Hermes deploymentを保守している場合、v0.13.0とv0.14.0は単なる機能追加ではなく、セキュリティ上重要なアップグレードとして扱ってください。v0.13.0ではDiscordのcross-guild bypassと2つのTOCTOU windowが解消されています。v0.14.0では、sudo処理、tool-error再注入、plugin API、skills-hub SSRF、dependency advisoryにわたって、さらにハードニングが加えられています。

実務者向けアーキテクチャ

このセクションは、内部で何が起きているかを理解し、デバッグ、拡張、パフォーマンスの推論ができるようになりたい人向けです。upstreamのarchitecture docsを統合した内容です。³

Entry Points → AIAgent

Hermesのすべてのentry pointは、最終的に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    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

図はupstreamのarchitecture docsをもとにしています。³

バナーに表示される「28 tools」に対する「47 tools / 20 toolsets」について。 「47 tools」という数は、upstream repository全体のtool registryの合計です。つまり、Hermesがソースコードとして同梱しているすべてのtoolset across every toolsetの全tool数を指します。実際に起動しているCLIのstartup bannerには、もっと小さい数が表示されます（このガイドで検証したインストールでは28 tools / 89 skillsと表示されました）。これはバグではありません。多くのtoolsetはオプトインであり、messaging platform adapters、browser automation、より重いscraping toolsなどは、config.yamlのtoolsets:で明示的に有効化する必要があります。registry totalは「利用可能なもの」、banner numberは「現在のprofileで有効なもの」です。有効なtoolsetはhermes tools --listで確認できます。個別のtoolsetの有効化・無効化は、~/.hermes/config.yamlのtoolsets:ブロック、または実行中のsession内で/tools list / /tools enable <name> / /tools disable <name>を使って行えます。toolを削除するとsession resetが発生し、agentがtool manifestを再構築します。

3つのAPIモード

Hermesはproviderごとの差異を3つのAPIモードに抽象化し、実行時に自動選択します。³

runtime_provider.pyのresolverは、18以上のproviderについて(provider, model) tupleを(api_mode, api_key, base_url)へマッピングし、OAuthフロー、credential pool、alias resolutionを処理します。³

CLI SessionにおけるData Flow

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

upstream architecture pageより。³

Prompt Assembly Order

prompt stackには次が含まれます。¹³

1. SOUL.md（agent identity。利用できない場合はbuilt-in fallback）
2. tool-aware behavior guidance
3. memory/user context（MEMORY.md、USER.md）
4. skills guidance
5. context files（AGENTS.md、.cursorrules）
6. timestamp
7. platform-specific formatting hints
8. /personalityなどのoptional system-prompt overlays

SOUL.mdが土台です。それ以外はすべて、その上に積み重なります。¹³

Session Storage

SQLiteベースのsession storageで、FTS5 full-text searchを備えています。sessionにはlineage tracking（compressionをまたぐparent/child）、platformごとのisolation、contention handling付きのatomic writesがあります。³

Plugin System

discovery sourceは3つあります。~/.hermes/plugins/（user）、.hermes/plugins/（project）、pip entry pointsです。pluginはcontext APIを通じて、tool、hook、CLI commandを登録します。memory providerはplugins/memory/配下の特殊なplugin typeです。³

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

Design Principles

upstream architecture pageより。³

OpenClawからの移行

Hermes AgentはOpenClawの後継です。既存のOpenClaw installationから移行する場合は、次のようにします。⁶⁵

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はデフォルトで~/.openclawから読み込み（legacyの~/.clawdbotおよび~/.moldbotディレクトリも自動検出します）、~/.hermesへ書き込みます。⁶

直接importされるもの（30以上のcategory）: SOUL.md、MEMORY.md、USER.md、AGENTS.md、4つのsource directoryからのskills、default model、custom providers、MCP servers、messaging platform tokensとallowlists（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、agent defaults（reasoning effort、compression、human delay、timezone、sandbox）、session reset policies、approval rules、TTS config、browser settings、tool settings、exec timeout、command allowlist、gateway config、3つのsourceからのAPI keys。⁶

手動確認用にarchiveされるもの: cron jobs、plugins、hooks/webhooks、memory backend（QMD）、skills registry config、UI/identity、logging、multi-agent setup、channel bindings、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API key resolutionは、優先順位順に3つのsourceを確認します。config values → ~/.openclaw/.env → auth-profiles.json。⁶

トラブルシューティング

“API key not set”

hermes model を実行してプロバイダーを対話的に設定するか、hermes config set OPENROUTER_API_KEY your_key を実行してください。hermes doctor コマンドで、不足しているキーを正確に確認できます。⁷

起動時に “Context limit: 2048 tokens” と表示される（ローカルモデル）

Hermes はサーバーの /v1/models エンドポイントからコンテキスト長を自動検出しますが、多くのローカルサーバーは低いデフォルト値を返します。config.yaml で明示的に設定してください。²

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

ツール呼び出しが実行されず、テキストとして表示される

サーバー側でツール呼び出しが有効になっていないか、そのモデルがサーバー実装経由のツール呼び出しに対応していません。²

応答が文の途中で切れる

考えられる原因は 2 つあります。²

1. サーバー側の出力上限（max_tokens）が低い場合。SGLang はデフォルトで応答あたり 128 tokens です。サーバー側で --default-max-tokens を設定するか、config.yaml で model.max_tokens を設定してください。
2. コンテキスト枯渇。モデルがコンテキストウィンドウを使い切っています。model.context_length を増やすか、Hermes でコンテキスト圧縮を有効にしてください。

WSL2 から Windows 上のモデルサーバーへ接続すると “Connection refused” になる

WSL2 は独自のサブネットを持つ仮想ネットワークアダプターを使います。つまり、WSL2 内の localhost は Windows ホストではなく Linux VM を指します。方法は 2 つあります。²

ミラーネットワーク（Windows 11 22H2 以降）: %USERPROFILE%\.wslconfig を編集します。

[wsl2]
networkingMode=mirrored

その後、wsl --shutdown を実行して再起動します。これで localhost が双方向に機能します。

ホスト IP フォールバック（古い Windows）: WSL2 内から Windows ホスト IP を取得し、localhost の代わりに使います。

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

また、モデルサーバーは 127.0.0.1 ではなく 0.0.0.0 にバインドする必要があります。Ollama では OLLAMA_HOST=0.0.0.0 を設定し、llama-server/SGLang では --host 0.0.0.0 を追加します。LM Studio では “Serve on Network” を有効にしてください。²

すべての場所はどこですか？

ここでは hermes status と hermes dump が役立ちます。hermes logs list はすべてのログファイルとサイズを表示します。hermes config path は設定ファイルの場所を出力します。hermes config env-path は .env の場所を出力します。⁶

FAQ

Hermes Agent と Claude Code の違いは何ですか？

Claude Code は Anthropic 公式の CLI で、Anthropic モデルに固定されています。Hermes Agent は Nous Research によるオープンソースのエージェントフレームワークで、OpenAI 互換プロバイダーならどれでも動作します。Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google、または自分でホストしたエンドポイントを利用できます。¹² また Hermes には、Claude Code にはない Telegram/Discord/Slack/WhatsApp/Signal 向けのメッセージング gateway も含まれています。

Anthropic の API key で Hermes を使えますか？

はい。方法は 3 つあります。²

1. ~/.hermes/.env に ANTHROPIC_API_KEY を設定し、hermes chat --provider anthropic --model claude-sonnet-4-6 を実行します
2. hermes model を実行して Anthropic を選択します。利用可能な場合、Hermes は Claude Code の認証情報ストアを使用します
3. フォールバックとして手動の ANTHROPIC_TOKEN（setup-token または OAuth token）を設定します

同じマシンですでに Claude Code を使っている場合は、方法 2 がおすすめです。更新可能な Claude 認証情報を更新可能なまま保てます。

会話を失わずにプロバイダーを切り替えるには？

セッション内で /model provider:model を使います。会話履歴、メモリ、skills はすべて引き継がれます。⁹

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

Anthropic を設定したのに vision/web/compression が動きません

補助モデルのフォールバックに当たっています。Vision、Web 要約、圧縮、その他のサイドタスクでは、別の補助 LLM が使われます。デフォルトでは、自動検出による Gemini Flash（OpenRouter → Nous → Codex）です。これらがどれも設定されておらず、Anthropic だけを設定している場合、これらの機能は静かに劣化します。⁴

修正方法: 補助タスク用に OPENROUTER_API_KEY を追加するか、補助スロットをメインプロバイダーに合わせて再設定します。なお、コンテキスト圧縮は独自のトップレベル compression: ブロックにあり、auxiliary.compression.provider ではなく summary_provider を受け取ります。auxiliary.compression スロットが公開しているのは timeout だけです。完全な修正例:

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

compression:
  summary_provider: "main"

SOUL.md と AGENTS.md の違いは何ですか？

SOUL.md はエージェントのアイデンティティです。トーン、スタイル、コミュニケーションのデフォルトを定義します。~/.hermes/SOUL.md に置かれ、どこでも適用されます。AGENTS.md はプロジェクト固有です。アーキテクチャ、規約、コマンド、パスなどを記述し、プロジェクトディレクトリに置きます。¹³ どこでも適用したい内容なら SOUL.md、プロジェクトに属する内容なら AGENTS.md です。

複数の Hermes インスタンスを並べて実行するには？

Profiles を使います。各 profile は独自の HERMES_HOME、設定、メモリ、セッション、gateway PID を持ちます。⁶

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

Hermes はローカル LLMs に対応していますか？

はい。カスタムエンドポイント経由で対応しています。Hermes は OpenAI 互換サーバーならどれでも動作します。Ollama、vLLM、SGLang、llama.cpp/llama-server、LM Studio、LocalAI、Jan、または自前のサーバーを利用できます。² サーバーごとの設定は カスタム & セルフホストエンドポイント を参照してください。

起動バナーに表示されるツール数が、ガイドに書かれている Hermes のツール数より少ないのはなぜですか？

ガイドでは、上流のアーキテクチャレジストリに基づいて 47 tools / 20 toolsets と記載しています。これは、Hermes が全 toolset にわたってソースコードとして同梱しているツールの総数です。実行中のインストールでは、バナーにそれより少ない数が表示されます（このガイドで使った参照インストールでは 28 tools）。理由は、Hermes が起動時にデフォルトの toolset セットだけを有効にするためです。多くの toolsets はオプトインです。メッセージング gateway アダプター、ブラウザー自動化、重めのスクレイピングスタック、いくつかの専門的な統合は、読み込まれる前に ~/.hermes/config.yaml の toolsets: に明示的に列挙する必要があります。レジストリ合計 = 「有効にすれば利用可能なもの」。バナー合計 = 「現在の profile が実際に読み込んだもの」です。どの toolsets が有効で、どれが利用可能だが無効なのかは hermes tools --list で確認できます。実行時には /tools enable <name> と /tools disable <name> で個別の toolsets を切り替えられます（無効化するとセッションがリセットされ、エージェントは新しい形でツールマニフェストを再構築します）。

プライマリプロバイダーが失敗したとき、Hermes はモデルフォールバックをどう扱いますか？

config.yaml に fallback_model ブロックを設定します。²

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

プライマリが失敗した場合（レート制限、サーバーエラー、認証失敗）、Hermes は会話履歴を失わずに、セッション途中でフォールバックへ切り替えます。発火するのは 1 セッションにつき最大 1 回です。

エージェントは時間とともに自分の skills を改善できますか？

はい。これが Hermes Agent の「自己改善」部分です。エージェントは skill_manage ツールを使って skills を作成、更新、削除できます。非自明なワークフローを把握すると、そのアプローチを将来の再利用に向けて skill として保存します。¹¹ エージェントは、複雑なタスク（5 回以上のツール呼び出し）の後、エラーに遭遇して動作する手順を見つけたとき、ユーザーがアプローチを修正したとき、または非自明なワークフローを発見したときに skills を作成します。

IDE 統合はありますか？

はい。Hermes は VS Code、Zed、JetBrains 向けの ACP（Agent Client Protocol）サーバーとして実行できます。⁶

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

変更履歴

参照