LLM とモデルプロバイダ

このページでは、Hermes Agent 向けの推論プロバイダを設定する方法を扱います。OpenRouter や Anthropic のようなクラウド API から、Ollama や vLLM のような自前ホストのエンドポイント、さらに高度なルーティングやフォールバックの設定までを取り上げます。Hermes を使うには、少なくとも 1 つのプロバイダを設定しておく必要があります。

推論プロバイダ

LLM につなぐ手段が少なくとも 1 つ必要です。hermes model を使うとプロバイダとモデルを対話的に切り替えられますし、直接設定することもできます。

組み込みの OpenCode 系 2 プロバイダはいずれも、会話ごとに変わる不透明な x-opencode-session ヘッダをすべてのリクエストに付けて送ります（全トランスポートのメインのやり取りに加えて、圧縮、タイトル生成、承認の確認、スキルハブの照会、/btw の脇道の質問といった補助的な呼び出しにも付きます。やり取りが終わったあとに裏で走るものも含みます。ヘッドレスで動く Kanban の specify/decompose と、ダッシュボードの見積もり呼び出しでは、タスクごとのキーを使います）。OpenCode はこれを使って 1 つの会話を同じバックエンドに固定し、プロンプトキャッシュを温かいまま保ちます。値は Hermes のセッション ID（または Kanban のタスク ID）から導出したもので、個人情報は含みません。

組み込みの OpenCode 系 2 プロバイダは、それぞれ opencode.ai 上の自分の中継先に固定されています（opencode-zen は /zen/v1、opencode-go は /zen/go/v1）。別の中継先のまま残った model.base_url は、選んだプロバイダの中継先に直されます。どの中継先を使うかは選んだモデル（-m、/model、フォールバックの項目、チャンネルごとの上書き）で決まるので、Zen のモデルから Go にしかないモデルへ切り替えても、リクエストが Zen へ送られることはありません。このモデルごとの振り分けは、セッションを再開したとき（hermes --resume、/resume、TUI やデスクトップアプリの再開経路）にも適用し直されます。そのセッションが別の OpenCode モデルで動いていたあいだに記録された通信形式や中継先の URL が、再開後のモデルに持ち越されることはありません。ID に -vision の印が付く OpenCode のモデル（たとえば deepseek-v4-flash-vision-exp）は、models.dev に載る前から画像を扱えるものとして扱われるので、agent.image_input_mode: auto なら supports_vision を上書きしなくても画像がそのまま添付されます。providers: の下に自分で定義したプロバイダの名前がこの系統のスラッグで始まる場合（たとえば opencode-go-bridge）、モデルごとの API モードの振り分けと /v1 の扱いはその系統のものが適用されますが、base_url は書いたとおりに使われます。実際に指している中継先に合わせて名前を付けてください。補助的な処理（auxiliary.compression、タイトル生成、画像認識、MoA）を OpenCode のプロバイダに向けた場合も同じモデルごとの表に従うので、gpt-5.6-luna のような Responses 専用のモデルや、minimax-m2.5 のような Anthropic 方式のモデルも、メインの会話とまったく同じように動きます。

公式の API キーを使う経路については、Google Gemini ガイドを参照してください。

Nous Portal

Nous Portal は Nous Research が提供する統合サブスクリプションのゲートウェイで、Hermes Agent を動かす方法としておすすめです。OAuth で 1 回ログインすれば、300 以上のフロンティア級エージェントモデル（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok、…）と Tool Gateway（ウェブ検索、画像生成、TTS、ブラウザ自動化）が使えます。料金はプロバイダごとに別のアカウントを持つのではなく、Nous のサブスクリプションにまとめて請求されます。

hermes setup --portal     # fresh install — OAuth + provider + gateway in one command
hermes model              # existing install — pick "Nous Portal" from the list
hermes portal info        # inspect login + routing at any time

まだサブスクリプションが無い場合は portal.nousresearch.com/manage-subscription から契約できます。

詳しくは: 専用の Nous Portal 連携ページ（サブスクリプションに含まれるもの、モデルカタログ、トラブルシューティング）と、手順を追った Nous Portal で Hermes Agent を動かすガイドを参照してください。

クライアントの識別。 Hermes Agent から Portal へ送るリクエストにはすべて client=hermes-client-v<version> のタグが付き（例: client=hermes-client-v0.13.0）、インストール済みのリリースに自動で合わせられます。これは Portal を通る全経路（メインのチャットループ、補助的な呼び出し、圧縮の要約、ウェブ抽出）で送られ、Portal 側のテレメトリが Hermes からのトラフィックを他のクライアントと区別できるようにします。設定は不要で、hermes update すればタグも自動で更新されます。

JWT 認証（自動）。 Hermes は Portal へのリクエストに、スコープ付きの inference:invoke JWT を優先して使い、従来の不透明なセッションキー経路はフォールバックとして残しています。設定は不要で、認証情報は OAuth フローが管理し、意識せずローテーションされます。失効したリフレッシュトークンは隔離され、再送のループに陥らないようになっています。

モデル管理の 2 つのコマンド

Hermes には目的の違う 2 つのモデル関連コマンドがあります。

まだ設定していないプロバイダに切り替えようとしている場合（たとえば OpenRouter だけを設定した状態で Anthropic を使いたいとき）は、/model ではなく hermes model が必要です。いったんセッションを抜け（Ctrl+C か /quit）、hermes model を実行してプロバイダの設定を済ませてから、新しいセッションを始めてください。

サブスクリプションのプラン: 契約で何が支払われるのか

いくつかのプロバイダでは、API キーの代わりに個人向けサブスクリプション（Claude Max、ChatGPT、SuperGrok / X Premium+、…）で Hermes にサインインできます。その契約が実際に何を支払い、何を支払わないのかはプロバイダごとに違い、課金の想定外が生まれるいちばんの原因になっています。下の表は要点だけをまとめたもので、詳細は各プロバイダの節にあります。

> *現時点で文書化されていません* と書かれたセルは、文字どおりの意味です。Hermes のドキュメントがまだその挙動を明記していない、ということです。決めつけずに、プロバイダの課金ダッシュボードを確認し、未解決の疑問として扱ってください。

Anthropic。 OAuth の経路は Anthropic アカウントに対して Claude Code として通り、追加利用クレジットを購入済みの Claude Max プランでのみ動きます。Max の基本枠が Hermes に使われることはなく、上乗せした追加 / 超過分のクレジットだけが減ります。Claude Pro の契約者はこの経路を使えません。代わりに使えるのは ANTHROPIC_API_KEY で、そのキーが属する組織に対して標準の API 料金でトークン従量課金されます。下の Anthropic（ネイティブ）を参照してください。

OpenAI Codex。 Hermes は ChatGPT のデバイスコード OAuth で認証し、認証情報を ~/.hermes/auth.json に保存します。既存の Codex CLI の認証情報が ~/.codex/auth.json にあれば取り込めます。どの ChatGPT プランが対象になるのか、Hermes の利用がプランの Codex の上限にどう計上されるのかは、現時点で文書化されていません。Nous Portal の下にある Codex の注記が扱っているのは、認証とトークン更新の挙動だけです。

xAI（SuperGrok / X Premium+）。 ブラウザでの OAuth は、有効な SuperGrok の契約か、連携した X アカウントの X Premium+ の契約のどちらかで動きます。同じベアラートークンは xAI へ直接つなぐツール（TTS、画像生成、動画生成、文字起こし、X Search）でも再利用されます。ログインに成功したのに推論が HTTP 403 を返す場合、それはトークンが古いのではなく xAI 側のティア / 権限の制限です。回避策は XAI_API_KEY に切り替えることです。下の xAI（Grok）と xAI Grok OAuth ガイドを参照してください。

Google Gemini。 いまのところ、個人向けの Gemini サブスクリプションで Hermes にサインインする方法はありません。gemini プロバイダは API キーを取り、Google Vertex AI は GCP プロジェクトに課金されます。エージェント用途では課金を有効にした Google Cloud プロジェクトをおすすめします。無料枠は長く走るエージェントのセッションには小さすぎます。Google Gemini ガイドを参照してください。

Anthropic（ネイティブ）

Claude のモデルを Anthropic API 経由で直接使います。OpenRouter を挟む必要はありません。3 つの認証方法に対応しています。

環境変数の認証情報を明示的に選んでいない場合、認証情報のプールにある Hermes 自身の OAuth の 許可が、借りてきた Claude Code のログインより優先されます。自前の OAuth の許可が無いときだけ、 借りてきたログインが控えとして使われます。ただし auth.adopt_external_logins: false を設定した 場合は別で、このとき Hermes は Claude Code の認証情報を読むことも更新することもしません （借りてきた CLI のログイン を参照して ください）。補助的な認証の復旧処理は、失敗したリクエストで使った 認証情報を更新するだけで、無関係な周辺のログインには触りません。借りてきたログインを回すと、 その持ち主のリフレッシュトークンを無効にしてしまうおそれがあるからです。

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

# Preferred: authenticate through `hermes model`
# Hermes will use Claude Code's credential store directly when available
hermes model

# Manual override with a setup-token (fallback / legacy)
export ANTHROPIC_TOKEN=***  # setup-token or manual OAuth token
hermes chat --provider anthropic

# Auto-detect Claude Code credentials (if you already use Claude Code)
hermes chat --provider anthropic  # reads Claude Code credential files automatically

hermes model で Anthropic の OAuth を選ぶと、Hermes はトークンを ~/.hermes/.env にコピーするのではなく、Claude Code 自身の認証情報ストアを優先して使います。こうすることで、更新可能な Claude の認証情報が更新可能なまま保たれます。

恒久的に設定する場合は次のようにします。

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

GitHub Copilot

Hermes は GitHub Copilot を第一級のプロバイダとして扱い、2 つのモードを用意しています。

copilot — Copilot API に直接つなぐ方式（おすすめ）。GitHub Copilot の契約を使って、Copilot API 経由で GPT-5.x、Claude、Gemini などのモデルにアクセスします。

hermes chat --provider copilot --model gpt-5.4

認証の選択肢（この順に確認されます）:

1. COPILOT_GITHUB_TOKEN 環境変数
2. GH_TOKEN 環境変数
3. GITHUB_TOKEN 環境変数
4. gh auth token の CLI へのフォールバック

トークンが見つからない場合、hermes model が OAuth デバイスコードログインを案内します。Copilot CLI や opencode と同じフローです。

API のルーティング: GPT-5 以降のモデル（gpt-5-mini を除く）は自動的に Responses API を使います。それ以外のモデル（GPT-4o、Claude、Gemini など）は Chat Completions を使います。モデルは Copilot の最新カタログから自動で検出されます。

copilot-acp — Copilot ACP のエージェントバックエンド。ローカルの Copilot CLI をサブプロセスとして起動します。

hermes chat --provider copilot-acp --model copilot-acp
# Requires the GitHub Copilot CLI in PATH and an existing `copilot login` session

恒久的な設定:

model:
  provider: "copilot"
  default: "gpt-5.4"

第一級の API キープロバイダ

これらのプロバイダは専用のプロバイダ ID を持ち、組み込みで対応しています。API キーを設定して --provider で選んでください。

# Fireworks AI
hermes chat --provider fireworks --model accounts/fireworks/models/kimi-k2p6
# Requires: FIREWORKS_API_KEY in ~/.hermes/.env

# NovitaAI Model API
hermes chat --provider novita --model moonshotai/kimi-k2.5
# Requires: NOVITA_API_KEY in ~/.hermes/.env

# Ramp Router (model IDs come from your account's live catalog)
hermes chat --provider router --model gpt-5.4-mini
# Requires: RAMP_ROUTER_API_KEY in ~/.hermes/.env

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

# Kimi / Moonshot AI (international: api.moonshot.ai)
hermes chat --provider kimi-coding --model kimi-for-coding
# Requires: KIMI_API_KEY in ~/.hermes/.env

# Kimi / Moonshot AI (China: api.moonshot.cn)
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# Requires: KIMI_CN_API_KEY in ~/.hermes/.env

# MiniMax (global endpoint)
hermes chat --provider minimax --model MiniMax-M2.7
# Requires: MINIMAX_API_KEY in ~/.hermes/.env

# MiniMax (China endpoint)
hermes chat --provider minimax-cn --model MiniMax-M2.7
# Requires: MINIMAX_CN_API_KEY in ~/.hermes/.env

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

# Xiaomi MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# Requires: XIAOMI_API_KEY in ~/.hermes/.env

# Tencent TokenHub (Hy4 preview)
hermes chat --provider tencent-tokenhub --model hy4-preview
# Requires: TOKENHUB_API_KEY in ~/.hermes/.env

# Tencent TokenPlan (Hy4 preview via Anthropic Messages endpoint)
hermes chat --provider tencent-tokenplan --model hy4-preview
# Requires: TOKENPLAN_API_KEY in ~/.hermes/.env

# Arcee AI (Trinity models)
hermes chat --provider arcee --model trinity-large-thinking
# Requires: ARCEEAI_API_KEY in ~/.hermes/.env

# Meta Model API (Muse Spark family)
hermes chat --provider meta-ai --model muse-spark-1.2
# Requires: MODEL_API_KEY in ~/.hermes/.env

# GMI Cloud
# Use the exact model ID returned by GMI's /v1/models endpoint.
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
# Requires: GMI_API_KEY in ~/.hermes/.env

# Nebius Token Factory
hermes chat --provider nebius --model deepseek-ai/DeepSeek-V4-Pro
# Requires: NEBIUS_API_KEY in ~/.hermes/.env

Fireworks は accounts/fireworks/models/kimi-k2p6 のような、スラッシュ区切りのネイティブなカタログ ID を使います。hermes model を実行して Fireworks AI を選び、最新のカタログから選ぶか、別の Fireworks のモデル ID を入力してください。既定のエンドポイントは https://api.fireworks.ai/inference/v1 です。別のエンドポイントを使いたい場合は、.env ではなく config.yaml の model.base_url で設定します。

config.yaml でプロバイダを恒久的に設定することもできます。

model:
  provider: "gmi"
  default: "zai-org/GLM-5.1-FP8"

ベース URL は NOVITA_BASE_URL、GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL、XIAOMI_BASE_URL、GMI_BASE_URL、META_BASE_URL、TOKENHUB_BASE_URL の各環境変数で上書きできます。

xAI（Grok）— Responses API + プロンプトキャッシュ

xAI は Responses API（codex_responses トランスポート）経由でつながっており、Grok 4 系のモデルでは推論が自動で有効になります。reasoning_effort パラメータは不要で、サーバー側が既定で推論します。~/.hermes/.env に XAI_API_KEY を設定して hermes model で xAI を選ぶか、/model grok-4-fast-reasoning のように grok を近道として指定してください。

SuperGrok と X Premium+ の契約者は、API キーの代わりにブラウザでの OAuth でサインインできます。hermes model で xAI Grok OAuth (SuperGrok / Premium+) を選ぶか、hermes auth add xai-oauth を実行してください。同じ OAuth のベアラートークンは、xAI へ直接つなぐツール（TTS、画像生成、動画生成、文字起こし）でも自動的に再利用されます。フロー全体は xAI Grok OAuth ガイドを参照してください。Hermes をリモートのホストで動かしている場合は、必要になる ssh -L のトンネルについて SSH 越しの OAuth / リモートホストも参照してください。

xAI をプロバイダとして使っているとき（ベース URL に x.ai を含む場合）、Hermes は毎回のリクエストに x-grok-conv-id ヘッダを付けてプロンプトキャッシュを自動で有効にします。これにより、1 つの会話セッション内のリクエストが同じサーバーへ振り分けられ、xAI 側の基盤がキャッシュ済みのシステムプロンプトや会話履歴を再利用できます。

設定は不要です。xAI のエンドポイントが検出され、セッション ID が使える状態であればキャッシュは自動的に働きます。これによって、複数ターンの会話の待ち時間とコストが下がります。

xAI は専用の TTS エンドポイント（/v1/tts）も提供しています。hermes tools → Voice & TTS で xAI TTS を選ぶか、設定については Voice & TTS のページを参照してください。

廃止される xAI モデルの移行（2026 年 5 月 15 日）: xAI は grok-4*、grok-3、grok-code-fast-1、grok-imagine-image-pro を 2026-05-15 に廃止します。hermes doctor と hermes chat の起動時のどちらでも、廃止される参照を指したままの設定を検出し、推奨される置き換え先を表示します。設定を一度に書き換えるには hermes migrate xai を使ってください。既定はドライランで、--apply を付けると変更が書き込まれます（書き込みの前に、直前の設定のタイムスタンプ付きの控えが backups/config/ に置かれます）。

hermes migrate xai          # preview replacements
hermes migrate xai --apply  # rewrite ~/.hermes/config.yaml in place

xAI のウェブ検索バックエンド。 ウェブ検索のツールセットを有効にしているとき、web.backend: xai にすると、同じ XAI_API_KEY / OAuth の認証情報を使って xAI のホスト型検索エンドポイントへ検索が流れます。xAI をすでにプロバイダとして設定していれば、追加の設定は要りません。

NovitaAI

NovitaAI は、開発者とエージェントのための AI ネイティブなクラウドです。3 つの製品ラインがあり、200 以上のモデルを扱う Model API、AI エージェントを組み立てて動かす Agent Sandbox、スケールする計算資源を提供する GPU Cloud が、1 つのプラットフォームから使えます。

# Use any available model
hermes chat --provider novita --model moonshotai/kimi-k2.5
# Requires: NOVITA_API_KEY in ~/.hermes/.env

# Short alias
hermes chat --provider novita-ai --model deepseek/deepseek-v3-0324

config.yaml で恒久的に設定することもできます。

model:
  provider: "novita"
  default: "moonshotai/kimi-k2.5"
  base_url: "https://api.novita.ai/openai/v1"

API キーは novita.ai/settings/key-management で取得できます。ベース URL は NOVITA_BASE_URL で上書きできます。

Ollama Cloud — マネージドな Ollama モデル、OAuth + API キー

Ollama Cloud は、ローカルの Ollama と同じオープンウェイトのカタログを、GPU を用意せずに使えるようにしたものです。hermes model で Ollama Cloud を選び、ollama.com/settings/keys の API キーを貼り付ければ、使えるモデルは Hermes が自動で見つけてくれます。

hermes model
# → pick "Ollama Cloud"
# → paste your OLLAMA_API_KEY
# → select from discovered models (gpt-oss:120b, glm-4.6:cloud, qwen3-coder:480b-cloud, etc.)

config.yaml に直接書く場合は次のとおりです。

model:
  provider: "ollama-cloud"
  default: "gpt-oss:120b"

モデルのカタログは ollama.com/v1/models から動的に取得され、1 時間キャッシュされます。model:tag の記法（例: qwen3-coder:480b-cloud）は正規化を通しても保たれます。ハイフンに置き換えないでください。

DeepInfra

DeepInfra（--provider deepinfra、DEEPINFRA_API_KEY）は、そのカタログからモデルをその場で取得します。推論は DeepInfra のトップレベルの reasoning_effort フィールドで制御するため、agent.reasoning_effort、/reasoning <level>、--reasoning、モデルごとの agent.reasoning_overrides が どちらの向きにも 効きます。既定で思考がオフのモデル（DeepSeek-V4.x）は努力度を指定すればオンになり、既定でオンのモデル（GLM-4.6、Qwen3-Thinking）は /reasoning none でオフにできます。推論を指定しなければ DeepInfra のモデルごとの既定値のままです。xhigh はそのまま使え、ultra は max として送られます。

AWS Bedrock

Anthropic Claude、Amazon Nova、DeepSeek v3.2、Meta Llama 4 などのモデルを AWS Bedrock 経由で使えます。AWS SDK（boto3）の認証情報チェーンを使うため、API キーは不要で、標準的な AWS の認証だけで済みます。

# Simplest — named profile in ~/.aws/credentials
hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6

# Or with explicit env vars
AWS_PROFILE=myprofile AWS_REGION=us-east-1 hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6

config.yaml で恒久的に設定する場合は次のとおりです。

model:
  provider: "bedrock"
  default: "us.anthropic.claude-sonnet-4-6"
bedrock:
  region: "us-east-1"          # or set AWS_REGION
  # profile: "myprofile"       # or set AWS_PROFILE
  # discovery: true            # auto-discover region from IAM
  # guardrail:                 # optional Bedrock Guardrails
  #   guardrail_identifier: "your-guardrail-id"
  #   guardrail_version: "DRAFT"

認証には標準の boto3 のチェーンを使います。明示的な AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY、~/.aws/credentials の AWS_PROFILE、EC2/ECS/Lambda の IAM ロール、IMDS、SSO のいずれかです。AWS CLI ですでに認証済みなら、環境変数は不要です。

Bedrock は内部で Converse API を使います。リクエストは Bedrock のモデル非依存の形に変換されるので、同じ設定が Claude、Nova、DeepSeek、Llama のいずれのモデルでも使えます。BEDROCK_BASE_URL を設定するのは、既定以外のリージョンのエンドポイントを呼ぶときだけです。

IAM の設定、リージョンの選び方、リージョン横断の推論については、AWS Bedrock ガイドの手順を参照してください。

Google Vertex AI

Google Cloud Vertex AI 上の Gemini モデルを、Vertex の OpenAI 互換エンドポイント経由で使います。認証は OAuth2 で、サービスアカウントの JSON か Application Default Credentials（ADC）から発行される短命（1 時間ほど）のアクセストークンを使います。静的な API キーはありません。トークンの発行と自動更新は Hermes が行い、セッションの途中で 401 が返った場合も発行し直します。

# Service account JSON (recommended for servers / gateways)
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env
# or Application Default Credentials
gcloud auth application-default login

hermes model   # → "Google Vertex AI" → project → region → model

config.yaml に書く場合は次のとおりです（プロジェクトとリージョンは秘密ではないのでここに置き、認証情報のパスは .env に残します）。

model:
  provider: "vertex"
  default: "google/gemini-3-flash-preview"   # Vertex requires the google/ prefix
vertex:
  project_id: "my-gcp-project"   # blank → use the project embedded in the credentials
  region: "global"               # required for the Gemini 3.x previews

VERTEX_PROJECT_ID / VERTEX_REGION の環境変数は config.yaml の値を上書きします。Hermes は初回利用時に google-auth を遅延インストールします。管理されたインストールの修復が必要なら hermes setup を実行してください。手順の全体は Google Vertex AI ガイドを、静的な API キーを使う AI Studio の経路は Google Gemini ガイドを参照してください。

Qwen Portal（OAuth）

ブラウザでの OAuth ログインに対応した Alibaba の Qwen Portal です。hermes model で Qwen OAuth (Portal) を選んでブラウザでサインインすると、Hermes がリフレッシュトークンを保存します。

hermes model
# → pick "Qwen OAuth (Portal)"
# → browser opens; sign in with your Alibaba account
# → confirm — credentials are saved to ~/.hermes/auth.json

hermes chat   # uses portal.qwen.ai/v1 endpoint

config.yaml で設定する場合は次のとおりです。

model:
  provider: "qwen-oauth"
  default: "qwen3-coder-plus"

HERMES_QWEN_BASE_URL を設定するのは、ポータルのエンドポイントが移転した場合だけです（既定: https://portal.qwen.ai/v1）。

Alibaba Cloud（Coding Plan）

Alibaba の Coding Plan（標準の DashScope API とは別の料金 SKU）を契約している場合、Hermes はそれを独立した第一級のプロバイダ alibaba-coding-plan として提供します。エンドポイントは https://coding-intl.dashscope.aliyuncs.com/v1 です。通常の alibaba プロバイダと同じく OpenAI 互換ですが、ベース URL と課金の面が異なります。

model:
  provider: alibaba_coding     # alias for alibaba-coding-plan
  model: qwen3-coder-plus

CLI から使う場合は次のとおりです。

hermes chat --provider alibaba_coding --model qwen3-coder-plus

alibaba_coding は alibaba の設定で使っているのと同じ DASHSCOPE_API_KEY を使うので、別のキーは要りません。振り分け先が違うだけです。このプロバイダが登録される前は、config.yaml に provider: alibaba_coding と書いたユーザーは黙って OpenRouter のルーティングに落ちていました。

中国本土向けのエンドポイント（alibaba-coding-plan-cn、https://coding.dashscope.aliyuncs.com/v1）を使うには ALIBABA_CODING_PLAN_CN_API_KEY を設定します。CN のプロバイダも ALIBABA_CODING_PLAN_API_KEY / DASHSCOPE_API_KEY にフォールバックしますが、共有キーだけを設定した状態では /model の選択肢に国際版の行しか出ません。CN 用のキーを設定する（または config.yaml に provider: alibaba-coding-plan-cn と書く）と CN の行が現れます。同じことが alibaba-token-plan-cn と ALIBABA_TOKEN_PLAN_CN_API_KEY にも当てはまります。

MiniMax（OAuth）

MiniMax-M2.7 をブラウザの OAuth ログインで使えます。API キーは不要です。hermes model で MiniMax (OAuth) を選んでブラウザでサインインすると、Hermes がアクセストークンとリフレッシュトークンを保存します。内部では Anthropic Messages 互換のエンドポイント（/anthropic）を使います。

hermes model
# → pick "MiniMax (OAuth)"
# → browser opens; sign in with your MiniMax account (global or CN region)
# → confirm — credentials are saved to ~/.hermes/auth.json

hermes chat   # uses api.minimax.io/anthropic endpoint

config.yaml で設定する場合は次のとおりです。

model:
  provider: "minimax-oauth"
  default: "MiniMax-M2.7"

対応モデルは MiniMax-M2.7（メイン）と MiniMax-M2.7-highspeed（既定の補助モデルとして組み込まれています）です。OAuth の経路では MINIMAX_API_KEY / MINIMAX_BASE_URL は無視されます。

NVIDIA NIM

NVIDIA NIM プロバイダを使うと、Nemotron をはじめとするオープンソースのモデルを、NVIDIA がホストするサービスまたはローカルの NIM エンドポイント経由で使えます。ホスト型エンドポイントのモデル識別子と、ローカルへの導入手順は build.nvidia.com/models にまとまっています。

どちらの方法でも config.yaml に保存され、モデル・プロバイダ・ベース URL についてはこれが正になります。

/model でモデルを切り替える

カスタムエンドポイントを 1 つでも設定すれば、セッションの途中でモデルを切り替えられます。

/model custom:qwen-2.5          # Switch to a model on your custom endpoint
/model custom                    # Auto-detect the model from the endpoint
/model openrouter:claude-sonnet-4 # Switch back to a cloud provider

名前付きのカスタムプロバイダ（後述）を設定している場合は、3 つ組の記法を使います。

/model custom:local:qwen-2.5    # Use the "local" custom provider with model qwen-2.5
/model custom:work:llama3       # Use the "work" custom provider with llama3

プロバイダを切り替えると、Hermes はベース URL とプロバイダを設定に保存するので、再起動しても切り替えは残ります。カスタムエンドポイントから組み込みのプロバイダへ切り替えたときは、古いベース URL が自動で消えます。

以下はすべて同じ形の繰り返しです。URL とキーとモデル名を変えるだけです。

Ollama — ローカルのモデルを設定なしで

Ollama は、オープンウェイトのモデルをコマンド 1 つでローカルに動かします。向いている用途は、手早いローカルでの試行、プライバシーに配慮したい作業、オフラインでの利用です。OpenAI 互換 API 経由のツール呼び出しにも対応しています。

# Install and run a model
ollama pull qwen2.5-coder:32b
ollama serve   # Starts on port 11434

続けて Hermes を設定します。

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:11434/v1
# Skip API key (Ollama doesn't need one)
# Enter model name (e.g. qwen2.5-coder:32b)

config.yaml を直接書く場合は次のとおりです。

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000   # See warning below

コンテキストが正しく設定されたか確認する:

ollama ps
# Look at the CONTEXT column — it should show your configured value

vLLM — GPU での高性能な推論

vLLM は、本番での LLM 提供の定番です。向いている用途は、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

続けて Hermes を設定します。

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8000/v1
# Skip API key (or enter one if you configured vLLM with --api-key)
# Enter model name: meta-llama/Llama-3.1-70B-Instruct

コンテキスト長: vLLM は既定でモデルの max_position_embeddings を読みます。それが GPU のメモリを超える場合はエラーになり、--max-model-len を小さくするよう促されます。--max-model-len auto を使えば、収まる最大値を自動で見つけてくれます。--gpu-memory-utilization 0.95（既定は 0.9）にすると、VRAM にもう少しコンテキストを詰め込めます。

ツール呼び出しには明示的なフラグが必要です:

対応しているパーサーは hermes（Qwen 2.5、Hermes 2/3）、llama3_json（Llama 3.x）、mistral、deepseek_v3、deepseek_v31、xlam、pythonic です。これらのフラグが無いとツール呼び出しは動かず、モデルはツール呼び出しをテキストとして出力してしまいます。

Qwen の推論パーサー: OpenAI 互換のサーバーが reasoning、reasoning_content、ストリーミングされる推論の差分といった構造化された推論のメタデータを返す場合、Hermes はそれを保持します。このメタデータは推論・思考の痕跡として扱われ、アシスタントが見せる答えの代わりにはなりません。vLLM で提供する Qwen の推論モデルでは、利用者に見える最終的な応答が content に入っていることを確かめてください。--reasoning-parser qwen3 を使うと content が空になる環境では、そのパーサーを無効にするか、extra_body 経由で chat_template_kwargs.enable_thinking: false のようなサーバーが対応するリクエストオプションを渡してください。

SGLang — RadixAttention による高速な提供

SGLang は vLLM の代わりになる選択肢で、KV キャッシュを再利用する RadixAttention を備えています。向いている用途は、複数ターンの会話（接頭辞キャッシュ）、制約付きデコード、構造化された出力です。

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

続けて Hermes を設定します。

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:30000/v1
# Enter model name: meta-llama/Llama-3.1-70B-Instruct

コンテキスト長: SGLang は既定でモデルの設定から読み取ります。上書きするには --context-length を使います。モデルが宣言している最大値を超えたい場合は SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 を設定してください。

ツール呼び出し: --tool-call-parser に、モデルの系統に合ったパーサーを指定します。qwen（Qwen 2.5）、llama3、llama4、deepseekv3、mistral、glm です。このフラグが無いと、ツール呼び出しはただのテキストとして返ってきます。

llama.cpp / llama-server — CPU と Metal での推論

llama.cpp は、量子化したモデルを CPU、Apple Silicon（Metal）、コンシューマ向け GPU で動かします。向いている用途は、データセンター級の GPU が無い環境での実行、Mac ユーザー、エッジでの運用です。

# Build and start llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 64000 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

コンテキスト長（-c）: 最近のビルドの既定は 0 で、GGUF のメタデータからモデルの学習時のコンテキストを読みます。128k 以上の学習コンテキストを持つモデルでは、KV キャッシュを丸ごと確保しようとしてメモリ不足になることがあります。Hermes 向けには -c を明示して、少なくとも 64,000 トークンにしてください。並列スロット（-np）を使う場合、コンテキストの総量はスロット間で分割されます。-c 64000 -np 4 なら 1 スロットあたり 16k しかなく、Hermes が 1 セッションに必要とする最小値を下回ります。

続けて、そこを向くように Hermes を設定します。

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:8080/v1
# Skip API key (local servers don't need one)
# Enter model name — or leave blank to auto-detect if only one model is loaded

これでエンドポイントが config.yaml に保存され、セッションをまたいで残ります。

LM Studio — ローカルのモデルを動かすデスクトップアプリ

LM Studio は、ローカルのモデルを GUI で動かすデスクトップアプリです。向いているのは、視覚的なインターフェースを好む人、モデルを手早く試したい場合、macOS / Windows / Linux の開発者です。

サーバーは LM Studio アプリから起動する（Developer タブ → Start Server）か、CLI を使います。

lms server start                        # Starts on port 1234
lms load qwen2.5-coder --context-length 64000

続けて Hermes を設定します。

hermes model
# Select "LM Studio"
# Press Enter to use http://localhost:1234/v1
# Pick one of the discovered models
# If LM Studio server auth is enabled, enter LM_API_KEY when prompted

Hermes は、すでに読み込まれている LM Studio のインスタンスのコンテキストをそのまま使います。既定の explicit モードで未読み込みのモデルを使う場合、Hermes 側でコンテキストを設定していなければ context_length を送らないので、LM Studio が自分のモデル設定を適用できます。その後 Hermes は、読み込み後に LM Studio が報告したコンテキスト長だけを使います。

LM Studio でコンテキスト長を変えるには次のようにします。

1. モデル選択の横にある歯車のアイコンをクリックします
2. 「Context Length」を、快適に使うには少なくとも 64000 に設定します
3. 変更を反映させるためにモデルを読み込み直します
4. 64000 が手元のマシンに収まらない場合は、より小さくてコンテキストの大きいモデルを検討してください

あるいは CLI を使います: lms load model-name --context-length 64000

モデルが収まるかどうかは CLI で見積もれます: lms load model-name --context-length 64000 --estimate-only

モデルごとの既定値を恒久的に設定するには、My Models タブ → モデルの歯車アイコン → コンテキストサイズを設定します。

:::

LM Studio の Just-In-Time 読み込み / Auto-Evict を使っていて、通常のチャットのリクエストからモデルの読み込みと解放を LM Studio に任せたい場合は、Hermes の明示的な事前読み込みの手順を飛ばせます。

hermes config set model.lmstudio_load_mode jit

既定の明示的な事前読み込みに戻すには次のようにします。

hermes config set model.lmstudio_load_mode explicit

ツール呼び出し: LM Studio 0.3.6 以降で対応しています。ネイティブにツール呼び出しを学習したモデル（Qwen 2.5、Llama 3.x、Mistral、Hermes）は自動で検出され、ツールのバッジ付きで表示されます。それ以外のモデルは汎用のフォールバックを使うため、信頼性は落ちるかもしれません。

WSL2 のネットワーク（Windows ユーザー向け）

Hermes Agent は Unix 環境を必要とするため、Windows ユーザーは WSL2 の中で動かします。モデルのサーバー（Ollama、LM Studio など）が Windows ホスト側で動いている場合、ネットワークの隔たりを埋める必要があります。WSL2 は独自のサブネットを持つ仮想ネットワークアダプタを使うので、WSL2 の中の localhost は Windows ホストではなく Linux の VM を指します。

方法 1: ミラーモード（おすすめ）

Windows 11 22H2 以降で使えるミラーモードは、Windows と WSL2 の間で localhost を双方向に通します。いちばん簡単な解決策です。

1. %USERPROFILE%\.wslconfig（例: C:\Users\YourName\.wslconfig）を作るか編集します。

[wsl2]
networkingMode=mirrored

1. PowerShell から WSL を再起動します。

wsl --shutdown

1. WSL2 の端末を開き直します。これで localhost から Windows 側のサービスに届きます。

curl http://localhost:11434/v1/models   # Ollama on Windows — works

方法 2: Windows ホストの IP を使う（Windows 10 / 古いビルド）

ミラーモードが使えない場合は、WSL2 の中から Windows ホストの IP を調べて、localhost の代わりにそれを使います。

# Get the Windows host IP (the default gateway of WSL2's virtual network)
ip route show | grep -i default | awk '{ print $3 }'
# Example output: 172.29.192.1

その IP を Hermes の設定に使います。

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1   # Windows host IP, not localhost

サーバーの待ち受けアドレス（NAT モードでは必須）

方法 2（ホストの IP を使う NAT モード）を使う場合、Windows 側のモデルサーバーは 127.0.0.1 の外からの接続を受け付けなければなりません。既定では、たいていのサーバーは localhost しか待ち受けません。NAT モードの WSL2 からの接続は別の仮想サブネットから来るため、拒否されます。ミラーモードなら localhost がそのまま対応づくので、既定の 127.0.0.1 の待ち受けで問題ありません。

Windows での Ollama（詳細）: Ollama は Windows のサービスとして動きます。OLLAMA_HOST を設定するには次のようにします。

1. システムのプロパティ → 環境変数 を開きます
2. システム環境変数として OLLAMA_HOST = 0.0.0.0 を追加します
3. Ollama のサービスを再起動します（または再起動します）

Windows ファイアウォール

Windows ファイアウォールは、NAT モードでもミラーモードでも WSL2 を別のネットワークとして扱います。上の手順を踏んでも接続できない場合は、モデルサーバーのポートに対するファイアウォールの規則を追加してください。

# Run in Admin PowerShell — replace PORT with your server's port
New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434

よく使うポート: Ollama は 11434、vLLM は 8000、SGLang は 30000、llama-server は 8080、LM Studio は 1234 です。

手早い確認

WSL2 の中から、モデルサーバーに届くかどうかを確かめます。

# Replace URL with your server's address and port
curl http://localhost:11434/v1/models          # Mirrored mode
curl http://172.29.192.1:11434/v1/models       # NAT mode (use your actual host IP)

モデルの一覧が JSON で返ってくれば大丈夫です。その同じ URL を Hermes の設定の base_url に使ってください。

ローカルモデルのトラブルシューティング

ここで挙げる問題は、Hermes と使うすべてのローカル推論サーバーに当てはまります。

WSL2 から Windows 上のモデルサーバーへの「Connection refused」

Hermes を WSL2 の中で、モデルサーバーを Windows ホストで動かしている場合、WSL2 の既定の NAT ネットワークでは http://localhost:<port> は通りません。直し方は上の WSL2 のネットワークを参照してください。

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

モデルが {"name": "web_search", "arguments": {...}} のようなものを、ツールを実際に呼ぶ代わりにメッセージとして出力してしまう症状です。

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

モデルが文脈を忘れる、応答がちぐはぐになる

原因: コンテキストウィンドウが小さすぎます。会話がコンテキストの上限を超えると、たいていのサーバーは古いメッセージを黙って捨てます。Hermes のシステムプロンプトとツールのスキーマだけで 4k〜8k トークンを使うことがあります。

切り分け方:

# Check what Hermes thinks the context is
# Look at startup line: "Context limit: X tokens"

# Check your server's actual context
# Ollama: ollama ps (CONTEXT column)
# llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM: check --max-model-len in startup args

直し方: エージェント用途では、コンテキストを少なくとも 64,000 トークンに設定してください。指定するフラグは、上の各サーバーの節を参照してください。

ローカルのエンドポイント（127.0.0.1、LAN、Docker のサービス名）に対して起動時に拒否されたときは、そのサーバーが実際に提供しているウィンドウの大きさと、直し方が表示されます。これは Ollama だけでなく、OpenAI 互換のサーバー全般に当てはまります。サーバー側のコンテキストを広げる（llama.cpp なら -c 64000、vLLM なら --max-model-len、Ollama なら OLLAMA_CONTEXT_LENGTH か Modelfile の num_ctx）か、config.yaml の model.ollama_num_ctx に、そのサーバーが本当に提供しているウィンドウの大きさ（最低でも 64K）を書いてください。model.ollama_num_ctx はどのローカルエンドポイントでも効きます。その裏側にある自動検出だけが Ollama の /api/show を使います。

起動時に「Context limit: 2048 tokens」と出る

Hermes はサーバーの /v1/models エンドポイントからコンテキスト長を自動検出します。サーバーが小さな値を返す（あるいは何も返さない）場合、Hermes はモデルが宣言している上限を使いますが、それが誤っていることがあります。

直し方: config.yaml で明示的に設定します。

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

応答が文の途中で切れる

考えられる原因:

1. サーバー側の出力の上限が小さい — サーバー側の生成の既定値を設定してください（SGLang なら --default-max-tokens です）。Hermes に出力トークンの上限を決める設定はありません。応答の長さと、会話のコンテキストウィンドウ（context_length）は別の話です。
2. コンテキストの枯渇 — モデルがコンテキストウィンドウを使い切りました。model.context_length を増やすか、Hermes のコンテキスト圧縮を有効にしてください。

LiteLLM プロキシ — 複数プロバイダのゲートウェイ

LiteLLM は、100 以上の LLM プロバイダを 1 つの API の背後にまとめる OpenAI 互換のプロキシです。向いている用途は、設定を変えずにプロバイダを切り替えること、負荷分散、フォールバックの連鎖、予算の管理です。

# Install and start
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000

# Or with a config file for multiple models:
litellm --config litellm_config.yaml --port 4000

続けて hermes model → Custom endpoint → http://localhost:4000/v1 で Hermes を設定します。

フォールバック付きの litellm_config.yaml の例は次のとおりです。

model_list:
  - model_name: "best"
    litellm_params:
      model: anthropic/claude-sonnet-4
      api_key: sk-ant-...
  - model_name: "best"
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...
router_settings:
  routing_strategy: "latency-based-routing"

ClawRouter — コスト最適化のルーティング

BlockRunAI による ClawRouter は、問い合わせの難しさに応じてモデルを自動で選ぶローカルのルーティングプロキシです。リクエストを 14 の軸で分類し、そのタスクをこなせるいちばん安いモデルへ振り分けます。支払いは USDC の暗号資産で行い、API キーは使いません。

# Install and start
npx @blockrun/clawrouter    # Starts on port 8402

続けて hermes model → Custom endpoint → http://localhost:8402/v1 → モデル名 blockrun/auto で Hermes を設定します。

ルーティングのプロファイル:

その他の互換プロバイダ

OpenAI 互換の API を持つサービスなら何でも使えます。よく使われるものをいくつか挙げます。

いずれも hermes model → Custom endpoint で設定できますし、config.yaml に書くこともできます。

model:
  default: meta-llama/Llama-3.1-70B-Instruct-Turbo
  provider: custom
  base_url: https://api.together.xyz/v1
  api_key: your-together-key

コンテキスト長の検出

Hermes は、モデルとプロバイダに合ったコンテキストウィンドウを見つけるために、複数の情報源をたどる解決の連鎖を使います。

1. 設定による上書き — config.yaml の model.context_length（最優先）。これは明示的な固定なので、プロバイダ側のメタデータより必ず優先されます。そのため Hermes は、ウィンドウの大きさを表示する場所（起動時のバナー、/model、/usage、ステータスバー）では (pinned) と添えて示し、固定した値がプロバイダの公表しているウィンドウと食い違う場合は起動時に警告を 1 回だけ出します。モデル、プロバイダ、ベース URL を切り替えると、この固定は自動的に外れます。
2. カスタムプロバイダのモデル単位の設定 — providers.<name>.models.<id>.context_length
3. 永続キャッシュ — 過去に判明した値（再起動しても残ります）
4. エンドポイントの /models — サーバーの API に問い合わせます（ローカル / カスタムのエンドポイント）
5. Anthropic の /v1/models — Anthropic の API に max_input_tokens を問い合わせます（API キー利用者のみ）
6. OpenRouter の API — OpenRouter の最新のモデルのメタデータ
7. Nous Portal — Nous のモデル ID を OpenRouter のメタデータと接尾辞で照合します
8. models.dev — 100 以上のプロバイダ、3800 以上のモデルについて、プロバイダごとのコンテキスト長を持つコミュニティ運営のレジストリ
9. フォールバックの既定値 — モデル系統ごとの大まかなパターン（既定は 128K）

たいていの環境では、これでそのまま動きます。仕組みはプロバイダを意識していて、同じモデルでも提供元によってコンテキストの上限は変わります（たとえば claude-opus-4.6 は Anthropic 直なら 1M ですが、GitHub Copilot 経由では 128K です）。

コンテキスト長を明示するには、モデルの設定に context_length を足します。

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

カスタムエンドポイントでは、モデルごとにコンテキスト長を設定することもできます。

providers:
  my-local-llm:
    api: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 64000
      deepseek-r1:70b:
        context_length: 65536

hermes model は、カスタムエンドポイントを設定するときにコンテキスト長を尋ねます。自動検出に任せるなら空のままにしてください。

名前付きのカスタムプロバイダ

複数のカスタムエンドポイントを使い分けている場合（たとえばローカルの開発サーバーとリモートの GPU サーバー）、config.yaml の providers: の辞書に、プロバイダ名をキーとして名前付きのカスタムプロバイダを定義できます。

providers:
  local:
    api: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  work:
    api: https://gpu-server.internal.corp/v1
    key_env: CORP_API_KEY
    transport: chat_completions   # set explicitly by `hermes model` → Custom Endpoint wizard; auto-detection still happens as a fallback
  anthropic-proxy:
    api: https://proxy.example.com/anthropic
    key_env: ANTHROPIC_PROXY_KEY
    transport: anthropic_messages  # for Anthropic-compatible proxies

各エントリが受け付けるのは、api（エンドポイントのベース URL。base_url/url も別名として使えます）、name（任意の表示名。既定は辞書のキー）、key_env かインラインの api_key か key_cmd（後述）、transport（chat_completions / anthropic_messages / codex_responses）、default_model、models、context_length、discover_models、extra_body、extra_headers、session_affinity_header（会話 ID を載せるヘッダーの名前。セッションを意識するプロキシ向けで、設定しないかぎり無効です）、ssl_ca_cert / ssl_verify、catalog_provider（後述）、そしてエントリを消さずに隠すための enabled: false です。

コマンドで発行する認証情報（key_cmd）

画像認識、思考、ネイティブのローカルモデルの機能確認では、認証ヘッダーを組み立てる前に、 チャットで使うのと同じ呼び出し可能な認証情報を用意します。チャット側の呼び出しを差し替えることなく、 コマンドが返したトークンのキャッシュを使い回します。コマンドが文字列のトークンを発行できない場合、 これらのできる範囲での確認は、オブジェクトの表現や優先度の低い設定済みの認証情報を送るのではなく、 ベアラーを付けずに送ります。ネイティブのローカルモデルの確認では、明示的に指定した呼び出しが失敗したとき、 引き継いだ Authorization を外し、それ以外の設定済みヘッダーはそのまま残します。チャット側の エラー処理は今までどおりです。

企業向けのゲートウェイでは、静的な API キーではなく短命のベアラートークンを発行することがよくあります（SSO/OIDC のブローカー、クラウドの IAM、社内の認証プロキシなど）。そのため .env にコピーしたトークンはセッションの途中で期限切れになり、リクエストが 401 を返し始めます。key_cmd には、トークンを*表示する*コマンドを指定します。Hermes はそれを実行し、期限の少し前まで結果をキャッシュするので、長いセッションでも再起動なしで動き続けます。

providers:
  my-gateway:
    base_url: "https://gateway.internal.example.com/v1"
    api_mode: chat_completions
    key_cmd: "my-auth-cli print-token --profile prod"

トークンを表示するものであれば、どんな補助コマンドでも使えます。databricks auth token、gcloud auth print-access-token、az account get-access-token、vault read、あるいは Claude Code 形式の apiKeyHelper のスクリプトなどです。

コマンドは標準出力にトークンだけを出す必要があります。素のトークンか、access_token フィールドを持つ JSON のどちらかです（expires_in は考慮されます。expiry/expiresOn の絶対時刻の ISO タイムスタンプも同様です）。複数行の出力は推測せずに拒否されます。期限が示されていない場合、トークンは一定の間隔で発行し直されます。

優先順位: 明示的な --api-key フラグが常に勝ちます。それ以外では、同じエントリ内では key_cmd が静的な api_key/key_env より優先されます。発行された認証情報は、メインのエージェントのやり取りにも、補助タスク（タイトル生成、圧縮、画像認識、埋め込み）にも同じように使われます。

モデルの検出も、providers: と旧来の custom_providers: の両方のエントリで key_cmd を尊重します。hermes model での設定時も同じです。補助コマンドが動くのは、認証付きでカタログをその場に問い合わせる必要があるときだけです。検出を無効にしている場合や、温まったカタログのキャッシュを読むだけの場合は、トークンを発行しません。カタログはコマンドの身元ごとに分けて持つので、ベアラートークンを入れ替えてもカタログは無効になりません。問い合わせ用の補助コマンドは、推論クライアントのトークンキャッシュではなく、自前の短命なトークンを使います。発行されたベアラートークンが config.yaml に保存されることはありません。補助コマンドが失敗した場合、検出は設定済みのモデルへ戻り、補助コマンドの出力を表に出すことはありません。

secrets.command とは別物です。あちらは起動時に一度だけ補助コマンドを実行して、プロセス全体の環境変数を用意するものです。多くのシークレットをまとめて返す vault / キーチェーンの補助にはあちらを、1 つのプロバイダの認証情報をセッションの*途中で*発行し直す必要があるときには key_cmd を使ってください。

codex_responses のプロキシでのコンテキストウィンドウ。 transport: codex_responses を指定したカスタムの項目（たとえばローカルの Codex プロキシ）では、Codex OAuth のモデル（gpt-6-astra、gpt-5.6-sol/-terra/-luna、gpt-5.5 など）のコンテキストウィンドウを、直接 API のカタログの 1.05M ではなく、Codex OAuth の表（ほとんどのスラッグで 272K）から解決します。こうすることで、Codex のバックエンドの上限と 272K の課金区分に達する前に圧縮が走ります。この判断はホスト名ではなくトランスポートに従うので、HERMES_CODEX_BASE_URL や model.base_url の後ろにいる openai-codex でも同じです。モデルごとの models.<id>.context_length、項目単位の context_length、model.context_length を指定した場合は、そちらが優先されます。自分で選ぶ -900k 付きの派生は、確認済みの 900K のままです。

カスタムエンドポイントでの推論の深さ。 設定した reasoning_effort（/reasoning max、agent.reasoning_effort）は、chat_completions と codex_responses のどちらのトランスポートでも、そのままカスタムエンドポイントへ届きます。max まで届き、Hermes 内部だけの ultra が max に丸められるだけです。例外は 2 つあり、いずれも項目ではなく接続先のホストに従います。api.openai.com を指したカスタムの項目は OpenAI のモデルごとの段階を保ち（そこでは max は gpt-5.6 だけの段階です）、モデルごとの語彙を公開しているプロバイダ（Ramp Router）を指した項目は、そのカタログに丸められます。その段階を受け付けないエンドポイントは、Hermes が黙って落とすのではなく、HTTP 400 を返します。推論の深さをまったく設定していないときは、chat_completions のリクエストに reasoning_effort: medium が付きます。Nous Portal や OpenRouter の経路と同じ既定値で、エンドポイント側の既定に任せることはしません（kimi-k3 の既定は max で、medium の約 3 倍の推論トークンを使います）。カタログや model_overrides で supports_reasoning: false とされたモデルと、thinking の機能を持たない Ollama のモデルでは、この項目は付きません。

OpenAI 互換のエンドポイントの中には、プロバイダ固有のリクエストボディのフィールドを必要とするものがあります。該当するカスタムプロバイダに extra_body のマップを足すと、Hermes はそのエンドポイント向けの各チャット補完のリクエストにそれを混ぜ込みます。

providers:
  gemma-local:
    api: http://localhost:8080/v1
    default_model: google/gemma-4-31b-it
    extra_body:
      enable_thinking: true
      reasoning_effort: high

サーバーが文書化している形に合わせてください。たとえば vLLM の Gemma 構成や一部の NVIDIA NIM のエンドポイントでは、enable_thinking を extra_body のトップレベルではなく chat_template_kwargs の下に置くことを期待します。

extra_body:
  chat_template_kwargs:
    enable_thinking: true

vLLM で提供する Qwen の推論モデルでは、推論パーサーが生成テキストをすべて推論のフィールドへ振り分けてアシスタントの content を空にしてしまう場合に、同じ形で思考を無効にできます。

extra_body:
  chat_template_kwargs:
    enable_thinking: false

設定した extra_body は、どこへ行ってもプロバイダについて回ります。エージェントの構築時に混ぜ込まれ、ゲートウェイのやり取りをまたいでも残り（/fast が service_tier/speed の上書きを重ねるやり取りでも、それらは extra_body を置き換えるのではなく上に重ねます）、/model の切り替えのたびに導出し直されます。名前付きのカスタムプロバイダへ切り替えればその extra_body が適用され、別へ切り替えればクリアされるので、他のプロバイダへ漏れることはありません。

hermes model → Custom Endpoint のウィザードは、API のモードを明示的に尋ねて、その答えを config.yaml に保存するようになりました（プロバイダのエントリの transport として保存されます）。この項目を空にした場合は、URL による自動検出（たとえば /anthropic のパスなら anthropic_messages）がフォールバックとして働きます。

カスタムプロバイダのモデルでのネイティブな画像入力。 カスタムエンドポイントが models.dev に載っていない画像対応のモデルを提供している場合、model.supports_vision: true を設定すると、Hermes は添付された画像を vision_analyze で前処理せず、ネイティブに（image_url のパートとして）渡します。この 1 つのつまみだけで済み、agent.image_input_mode: native を併せて設定する必要はありません。

model:
  provider: custom
  base_url: http://localhost:8080/v1
  default: qwen3.6-35b-a3b
  supports_vision: true   # send images natively; otherwise vision_analyze pre-describes them

同じキーは名前付きプロバイダのモデル単位でも有効で（providers.<name>.models.<id>.supports_vision）、標準的な YAML の真偽値（true/false/yes/no/on/off/1/0）を受け付けます。

カタログが知らないモデルについて、メタデータ（たとえば context_window）を直すだけの model_overrides のエントリを書いた場合、画像認識と推論の対応可否は不明のままになります。vision_analyze、video_analyze、推論の強さを選ぶ画面はそのまま使えます。そのモデルをテキスト専用、あるいは推論なしとして扱うのは、上書きの中で supports_vision: false / supports_reasoning: false を明示したときだけです。

カタログに載っているベンダーのメタデータを引き継ぐ（catalog_provider）。 名前付きのカスタムプロバイダ（ゲートウェイ、プロキシ、再販業者）が、Hermes が組み込みのプロバイダとしてすでに知っているモデルを提供している場合は、そのベンダーをエントリに指定すると、カタログにあるコンテキスト長・出力の上限・画像認識と推論の対応可否をそのまま引き継げます。model_overrides は要りません。

providers:
  my-gateway:
    api: https://gateway.example.com/v1
    key_env: GATEWAY_API_KEY
    catalog_provider: deepseek   # metadata lookups use DeepSeek's catalog entries

catalog_provider には Hermes のプロバイダ ID（deepseek、anthropic、openai など）か models.dev の ID を指定できます。影響するのはメタデータの参照先だけで、リクエストはこれまでどおり自分の api の URL へ自分の認証情報で送られます。同じモデルについて model_overrides を明示した場合は、そちらが優先されます。

セッションの途中で切り替えるには、3 つ組の記法を使います。

/model custom:local:qwen-2.5       # Use the "local" endpoint with qwen-2.5
/model custom:work:llama3-70b      # Use the "work" endpoint with llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4  # Use the proxy

名前付きのカスタムプロバイダは、対話的な hermes model のメニューからも選べます。

レシピ集: Together AI、Groq、Perplexity

その他の互換プロバイダに挙げたクラウドのプロバイダは、いずれも OpenAI の REST 方言を話すので、providers: の辞書の下で同じように設定できます。以下に 3 つの実例を挙げます。どれも ~/.hermes/config.yaml に書き、対応する API キーは ~/.hermes/.env に置きます。

Together AI

オープンウェイトのモデル（Llama、MiniMax、Gemma、DeepSeek、Qwen）を、一次プロバイダの API よりかなり安く提供しています。複数のモデルを併用する構成の既定として良い選択です。

# ~/.hermes/config.yaml
providers:
  together:
    api: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
    # transport: chat_completions  # default — no need to set

model:
  default: MiniMaxAI/MiniMax-M2.7   # or any model from together.ai/models
  provider: custom:together

# ~/.hermes/.env
TOGETHER_API_KEY=your-together-key

セッションの途中でモデルを切り替えます。

/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo
/model custom:together:google/gemma-4-31b-it
/model custom:together:deepseek-ai/DeepSeek-V3

Together の /v1/models エンドポイントは使えるので、hermes model が利用できるモデルを自動で見つけられます。

Groq

非常に高速な推論です（Llama-3.3-70B でおよそ 500 tok/s）。カタログは小さいものの、待ち時間が気になる対話的な用途には強い選択肢です。

# ~/.hermes/config.yaml
providers:
  groq:
    api: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY

model:
  default: llama-3.3-70b-versatile
  provider: custom:groq

# ~/.hermes/.env
GROQ_API_KEY=your-groq-key

Perplexity

ライブのウェブ検索と引用を自動でやってくれるモデルが欲しいときに便利です。使えるモデルの制約が厳しいので、現在の一覧は perplexity.ai/settings/api で確認してください。

# ~/.hermes/config.yaml
providers:
  perplexity:
    api: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: sonar
  provider: custom:perplexity

# ~/.hermes/.env
PERPLEXITY_API_KEY=your-perplexity-key

Perplexity の Agent API（api_mode: codex_responses で api: https://api.perplexity.ai/v1）は、web_search、search_files、fetch_url、people_search、finance_search という関数名を、自前の組み込みの道具のために予約しています。Hermes は同じ名前の自分の道具を、通信の上では hermes_<name> に改名し、呼び出す直前に元へ戻します。メインのエージェントのループでも、補助的な呼び出し（タイトル生成、圧縮、MoA の集約）でも同じ扱いで、OpenCode の /v1/responses のエンドポイントに対するのと同じやり方です。

1 つの設定に複数のプロバイダを入れる

3 つのレシピは組み合わせられます。全部をまとめて設定し、ターンごとに /model custom:<name>:<model> で切り替えられます。

providers:
  together:
    api: https://api.together.xyz/v1
    key_env: TOGETHER_API_KEY
  groq:
    api: https://api.groq.com/openai/v1
    key_env: GROQ_API_KEY
  perplexity:
    api: https://api.perplexity.ai
    key_env: PERPLEXITY_API_KEY

model:
  default: MiniMaxAI/MiniMax-M2.7
  provider: custom:together      # boot to Together; switch freely after

構成の選び方

任意の API キー

Firecrawl を自前でホストする

Hermes は既定で、ウェブ検索とスクレイピングに Firecrawl のクラウド API を使います。Firecrawl をローカルで動かしたい場合は、代わりに自前ホストのインスタンスへ Hermes を向けられます。設定手順の全体は Firecrawl の SELF_HOST.md を参照してください。

得られるもの: API キーが不要になり、レート制限もページ単位の費用もなく、データを自分で完全に管理できます。

失うもの: クラウド版は、ボット対策を突破する Firecrawl 独自の「Fire-engine」（Cloudflare、CAPTCHA、IP のローテーション）を使います。自前ホスト版は基本的な fetch と Playwright を使うので、保護のかかったサイトでは失敗することがあります。検索は Google ではなく DuckDuckGo を使います。

設定手順:

1. Firecrawl の Docker スタックをクローンして起動します（API、Playwright、Redis、RabbitMQ、PostgreSQL の 5 コンテナで、4〜8 GB ほどのメモリが必要です）。

git clone https://github.com/firecrawl/firecrawl
cd firecrawl
# In .env, set: USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002
docker compose up -d

1. Hermes をそのインスタンスへ向けます（API キーは不要です）。

hermes config set FIRECRAWL_API_URL http://localhost:3002

自前ホストのインスタンスで認証を有効にしている場合は、FIRECRAWL_API_KEY と FIRECRAWL_API_URL の両方を設定することもできます。

OpenRouter のプロバイダルーティング

OpenRouter を使うときは、リクエストをどのプロバイダへ振り分けるかを制御できます。~/.hermes/config.yaml に provider_routing のセクションを足してください。

provider_routing:
  sort: "throughput"          # "price" (default), "throughput", or "latency"
  # only: ["anthropic"]      # Only use these providers
  # ignore: ["deepinfra"]    # Skip these providers
  # order: ["anthropic", "google"]  # Try providers in this order
  # require_parameters: true  # Only use providers that support all request params
  # data_collection: "deny"   # Exclude providers that may store/train on data
  # models:                   # Per-model pins (same keys; unset keys fall through)
  #   "openai/gpt-6-astra": {only: ["openai"]}
  #   "anthropic/claude-fable-5.1": {only: ["anthropic"]}

近道: モデル名の末尾に :nitro を付けるとスループット順（例: anthropic/claude-sonnet-4:nitro）、:floor を付けると価格順になります。モデルごとの詳細は プロバイダルーティングを参照してください。

OpenRouter の Pareto Code ルーター

OpenRouter は openrouter/pareto-code で、コーディング向けの実験的なモデルルーターを提供しています。コーディングの品質の基準（Artificial Analysis のランキングに基づく）を満たすなかで、いちばん安いモデルへリクエストを自動で振り分けます。このモデルを選んだうえで、~/.hermes/config.yaml の min_coding_score のつまみを調整してください。

model:
  provider: openrouter
  model: openrouter/pareto-code

openrouter:
  min_coding_score: 0.65   # 0.0–1.0; higher = stronger (more expensive) coders. Default 0.65.

補足:

• min_coding_score が送られるのは、model.model が openrouter/pareto-code のときだけです。他のモデルでは何の効果もありません。
• 空文字にする（または行を消す）と、OpenRouter が使えるなかで最も強いコーダーを選びます。プラグインのブロックを省いたときの、文書化された挙動です。
• ある日のあるスコアに対する選択は決定的ですが、実際に選ばれるモデルはパレートフロンティアの移動（新しいモデルの登場、ベンチマークの更新）につれて変わります。
• ルーターの挙動の全体は OpenRouter の Pareto Router のドキュメントを参照してください。
• メインのエージェントではなく特定の補助タスク（圧縮、画像認識など）で Pareto Code ルーターを使うには、そのタスクの下に extra_body.plugins を設定します。補助モデル → 補助タスクでの OpenRouter のルーティングと Pareto Codeを参照してください。

フォールバックのプロバイダ

メインのモデルが失敗したとき（レート制限、サーバーエラー、認証の失敗）に、Hermes が順に試す予備のプロバイダの連鎖を設定できます。正式な書き方は、トップレベルの fallback_providers: のリストです。

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: anthropic
    model: claude-sonnet-4
    # base_url: http://localhost:8000/v1    # optional, for custom endpoints
    # api_mode: chat_completions           # optional override (`transport:` is an accepted alias)

providers.<name> のブロックを名前で指す項目（provider: my-relay や provider: custom:my-relay）は、その項目自身が何も指定していなければ、ブロック側の transport / api_mode を引き継ぎます。そのため、Responses 専用や Anthropic Messages の中継先も、宣言した通信方式のままフォールバックされます。上書きしたいときは、項目側に api_mode を書いてください。

旧来の 1 組だけを書く fallback_model: の辞書も、後方互換のために受け付けられます。

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

フォールバックが働くと、会話を失わずにセッションの途中でモデルとプロバイダが入れ替わります。連鎖は 1 件ずつ順に試され、発動は 1 セッションにつき 1 回だけです。

対応するプロバイダ: openrouter、nous、novita、openai-codex、copilot、copilot-acp、anthropic、gemini、qwen-oauth、huggingface、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、xai-oauth、ollama-cloud、bedrock、ai-gateway、azure-foundry、opencode-zen、opencode-go、commandcode、commandcode-anthropic、kilocode、xiaomi、arcee、gmi、actual、stepfun、lmstudio、alibaba、alibaba-coding-plan、tencent-tokenhub、tencent-tokenplan、nebius-token-factory、router、custom。

関連ページ

• 設定 — 全般的な設定（ディレクトリ構成、設定の優先順位、端末のバックエンド、メモリ、圧縮など）
• 環境変数 — すべての環境変数の一覧