Hermes Agent Wiki 非公式・日本語wiki

Open WebUI との連携

目次

Open WebUI（126k★）は、自分のサーバーで動かせる AI 向けチャット画面としてもっとも広く使われているものです。Hermes Agent に組み込まれた API サーバーを使えば、Open WebUI をエージェントの洗練された Web の入口として利用できます。会話の管理、ユーザーアカウント、今どきのチャット画面が一式そろっています。

全体の構成

flowchart LR
    A["Open WebUI<br/>browser UI<br/>port 3000"]
    B["hermes-agent<br/>gateway API server<br/>port 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE streaming response| A

Open WebUI は、OpenAI につなぐときとまったく同じやり方で Hermes Agent の API サーバーにつながります。Hermes は自分の道具一式（ターミナル、ファイル操作、Web 検索、記憶、スキル）を使ってリクエストを処理し、最終的な応答を返します。

Open WebUI と Hermes はサーバー同士で通信するため、この連携に API_SERVER_CORS_ORIGINS は必要ありません。

すぐに動かす

1. API サーバーを有効にする

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY your-secret-key

hermes config set は、フラグを config.yaml に、秘密の値を ~/.hermes/.env に自動で振り分けます。ゲートウェイがすでに動いている場合は、変更を反映させるために再起動してください。

hermes gateway stop && hermes gateway

2. Hermes Agent のゲートウェイを起動する

hermes gateway

次のような表示が出るはずです。

[API Server] API server listening on http://127.0.0.1:8642

3. API サーバーにつながるか確かめる

curl -s http://127.0.0.1:8642/health
# {"status": "ok", ...}

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# {"object":"list","data":[{"id":"hermes-agent", ...}]}

/health が失敗する場合、ゲートウェイが API_SERVER_ENABLED=true を読み込めていません。再起動してください。/v1/models が 401 を返す場合は、Authorization ヘッダーの値が API_SERVER_KEY と一致していません。

4. Open WebUI を起動する

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  -e ENABLE_OLLAMA_API=false \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

ENABLE_OLLAMA_API=false は、既定で有効な Ollama のバックエンドを止めるための指定です。そのままにしておくと空の項目がモデル選択欄に並んで邪魔になります。実際に Ollama を併用しているなら、この行は外してください。

初回の起動には 15〜30 秒かかります。Open WebUI が最初の起動時に sentence-transformer の埋め込みモデル（約 150MB）をダウンロードするためです。docker logs open-webui の出力が落ち着いてから画面を開いてください。

5. 画面を開く

http://localhost:3000 にアクセスします。管理者アカウントを作成してください（最初のユーザーが管理者になります）。モデルの選択欄にエージェントが表示されているはずです（名前はプロファイル名、既定のプロファイルなら hermes-agent になります）。あとは話しかけるだけです。

Docker Compose での構成

継続的に使うなら、docker-compose.yml を用意します。

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

そのうえで次を実行します。

docker compose up -d

管理画面から設定する

環境変数ではなく画面から接続設定をしたい場合は、次の手順で行います。

  1. http://localhost:3000 で Open WebUI にログインします
  2. プロフィールのアイコン → Admin Settings をクリックします
  3. Connections を開きます
  4. OpenAI API の欄で、レンチのアイコン（Manage）をクリックします
  5. + Add New Connection をクリックします
  6. 次の内容を入力します:
  • URL: http://host.docker.internal:8642/v1
  • API Key: Hermes 側の API_SERVER_KEY とまったく同じ値
  1. チェックマークをクリックして接続を確認します
  2. Save します

これでモデルの選択欄にエージェントが表示されます（名前はプロファイル名、既定のプロファイルなら hermes-agent になります）。

API の種類: Chat Completions と Responses

Open WebUI がバックエンドにつなぐときの API の形式は 2 種類あります。

種類 形式 使いどころ
Chat Completions（既定） /v1/chat/completions おすすめ。そのままで動きます。
Responses（実験的） /v1/responses previous_response_id を使い、会話の状態をサーバー側で持たせたい場合。

これが既定で、追加の設定は要りません。Open WebUI が OpenAI 形式のリクエストを送り、Hermes Agent がそれに応じて返します。リクエストごとに会話の履歴が丸ごと含まれます。

Responses API を使う

Responses API の形式を使うには、次のようにします。

  1. Admin Settings → Connections → OpenAI → Manage を開きます
  2. hermes-agent の接続設定を編集します
  3. API Type を "Chat Completions" から "Responses (Experimental)" に変更します
  4. 保存します

Responses API では、Open WebUI が Responses 形式（input の配列と instructions）でリクエストを送り、Hermes Agent は previous_response_id を通じてツール呼び出しの履歴をターンをまたいで保てます。stream: true のときは、仕様どおりの function_call と function_call_output の項目も逐次送られるので、Responses のイベントを描画できるクライアントであれば、ツール呼び出しの独自の表示を作れます。

動作の流れ

Open WebUI でメッセージを送ると、次のことが起こります。

  1. Open WebUI が、入力したメッセージと会話の履歴を載せて POST /v1/chat/completions を送ります
  2. Hermes Agent が、API サーバーのプロファイル、モデルやプロバイダーの設定、記憶、スキル、API サーバー用に設定されたツール群を使って、サーバー側に AIAgent のインスタンスを作ります
  3. エージェントがリクエストを処理します。その過程で API サーバーのホスト上のツール（ターミナル、ファイル操作、Web 検索など）を呼ぶことがあります
  4. ツールが動いている間、進行状況が画面に随時流れるので、エージェントが何をしているかが分かります（例: ` 💻 ls -la , 🔍 Python 3.12 release `）
  5. エージェントの最終的なテキスト応答が Open WebUI に流れてきます
  6. Open WebUI がその応答をチャット画面に表示します

エージェントが使えるのは、その API サーバーの Hermes インスタンスと同じツールと機能です。API サーバーが別のマシンにあるなら、ツールもそちら側で動きます。

いま手元の作業環境に対してツールを動かしたいのであれば、Hermes をローカルで動かし、その向き先を純粋な LLM プロバイダーか、純粋な OpenAI 互換のモデルプロキシ（vLLM、LiteLLM、Ollama、llama.cpp、OpenAI、OpenRouter など）にしてください。「頭脳は遠隔、手元は手元」という分離実行の仕組みは #18715 で検討中で、現在の API サーバーの動きではありません。

設定の一覧

Hermes Agent（API サーバー）

変数 既定値 説明
API_SERVER_ENABLED false API サーバーを有効にします
API_SERVER_PORT 8642 HTTP サーバーのポート
API_SERVER_HOST 127.0.0.1 待ち受けるアドレス
API_SERVER_KEY _(必須)_ 認証用のベアラートークン。OPENAI_API_KEY と一致させます。

Open WebUI

変数 説明
OPENAI_API_BASE_URL Hermes Agent の API の URL（/v1 まで含めます）
OPENAI_API_KEY 空にはできません。API_SERVER_KEY と一致させます。

困ったときは

モデルの選択欄に何も出ない

  • URL の末尾に /v1 が付いているか確認する: http://host.docker.internal:8642/v1 です（:8642 だけでは足りません）
  • ゲートウェイが動いているか確認する: curl http://localhost:8642/health が {"status": "ok"} を返すはずです
  • モデルの一覧を確認する: curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models が hermes-agent を含む一覧を返すはずです
  • Docker のネットワーク: Docker の中から見た localhost は、ホストではなくコンテナー自身です。host.docker.internal か --network=host を使ってください。
  • 空の Ollama のバックエンドが選択欄を覆っている: ENABLE_OLLAMA_API=false を付けていないと、Hermes のモデルの上に空の Ollama の欄が表示されます。-e ENABLE_OLLAMA_API=false を付けてコンテナーを起動し直すか、Admin Settings → Connections で Ollama を無効にしてください。

接続テストは通るのにモデルが読み込まれない

ほぼ確実に /v1 の付け忘れです。Open WebUI の接続テストはつながるかどうかを見るだけで、モデルの一覧が取れるかまでは確かめません。

応答に時間がかかる

Hermes Agent が最終的な応答を作る前に、複数のツール（ファイルの読み取り、コマンドの実行、Web 検索など）を動かしているのかもしれません。込み入った依頼では普通のことです。エージェントが終えた時点で、応答がまとめて表示されます。

「Invalid API key」と出る

Open WebUI 側の OPENAI_API_KEY が、Hermes Agent の API_SERVER_KEY と一致しているか確認してください。

プロファイルを使った複数人での利用

利用者ごとに設定・記憶・スキルを分けた Hermes を動かすには、プロファイルを使います。プロファイルごとに別のポートで API サーバーが動き、Open WebUI にはプロファイル名がモデル名として自動で表示されます。

1. プロファイルを作って API サーバーを設定する

API_SERVER_* は YAML の設定キーではなく環境変数なので、それぞれのプロファイルの .env に書きます。ポートは、既定のプラットフォームが使う範囲（8644 は webhook アダプター、8645 は wecom-callback、8646 は msgraph-webhook）を避けて、8650+ のあたりを選んでください。

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. それぞれのゲートウェイを起動する

hermes -p alice gateway &
hermes -p bob gateway &

3. Open WebUI に接続を追加する

Admin Settings → Connections → OpenAI API → Manage で、プロファイルごとに接続をひとつずつ追加します。

接続 URL API キー
Alice http://host.docker.internal:8650/v1 alice-secret
Bob http://host.docker.internal:8651/v1 bob-secret

モデルの選択欄には alice と bob が別々のモデルとして並びます。管理画面から Open WebUI の利用者にモデルを割り当てれば、それぞれに独立した Hermes のエージェントを持たせられます。

Linux の Docker（Docker Desktop なし）

Docker Desktop を使わない Linux では、host.docker.internal は既定では名前解決できません。次のいずれかで対応します。

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...