Hermes Agent:ホームサーバーユーザー向けセルフホストセットアップガイド

Eva Wong は テクニカルライター であり、 生粋の技術好き としてZimaSpaceで活動しています。ホームラボやオープンソースソフトウェア をこよなく愛する生粋のギークで、複雑な技術概念をわかりやすく、実践的なガイド にまとめることを得意としています。Evaは、セルフホスティングは難しいものではなく、楽しむものだと考えています。チュートリアルを通じて、初めてのNAS構築からDockerコンテナの使いこなしまで、コミュニティがハードウェアのセットアップをわかりやすく理解できるよう 支援しています。、初めてのNAS構築からDockerコンテナの習得まで。

簡単な回答

モデルプロバイダーに接続し、ツールを使い、Telegramなどのメッセージングゲートウェイを通じて通信するAIエージェントを使いたい場合、Hermes Agentをホームサーバーでセルフホストできます。ほとんどの初心者にとって難しいのは、アプリを動かすことだけではありません。それぞれの操作がどこで行われるのか、つまりホストサーバー上なのか、コンテナ内なのか、アプリの実行環境内なのか、メッセージングプラットフォーム経由なのかを理解することです。

安全にセルフホスト環境を構築するには、問題のトラブルシューティングを始める前に、次の6つの質問に答えられるようにしておきましょう。

  • ホスト上で作業していますか、それともコンテナ内ですか?
  • アプリの設定、ログ、ダウンロード、実行時データはどこに保存されますか?
  • ファイルの所有者とアプリの実行ユーザーは誰ですか?
  • アプリはモデルプロバイダーやメッセージングAPIに接続できますか?
  • APIキー、ボットトークン、許可リストは保護されていますか?
  • 再起動後もエージェントが動作していることを確認するには?

こうした境界を明確にしておけば、Hermes Agentの設定が理解しやすくなり、検証や問題の修正も容易になります。

セルフホスト型ホームサーバー環境におけるHermes Agentとは?

Hermes Agentは、モデルプロバイダーに接続してツールを使用し、ターミナルやメッセージングチャネルを通じて操作できる、セルフホスト型のAIエージェントワークフローです。ホームサーバーでは、多くの場合、AIモデル、サーバー環境、Webダッシュボードやボットゲートウェイなどの通信インターフェースをつなぐ役割を担います。

重要なのは、セルフホスト型エージェントは単なるチャットボットではないという点です。設定によっては、ファイル、ターミナルツール、モデルAPI、メッセージングプラットフォーム、実行時データとやり取りする可能性があります。そのため、パス、権限、アクセス範囲の境界を明確にすることが重要です。

AIとのやり取りやメッセージングにおけるHermes Agentの役割

Hermes Agentは、モデルプロバイダーへの接続、会話の開始、ツールの使用、メッセージングゲートウェイへの接続を設定できます。Hermes Agentのクイックスタート手順では、Hermesのインストール、モデルプロバイダーの設定、最初の会話の開始、ターミナルツールの使用、さらにゲートウェイを介したメッセージングプラットフォームへの接続方法が説明されています。

ホームサーバーのユーザーにとって、これはHermesを、自分で管理するデバイス上で常時稼働するAIアシスタントにできるということです。一方で、モデルの認証情報、アプリの実行環境、ゲートウェイの設定、アクセス権限など、新たな設定項目が加わることもあります。

WebUIの設定で十分な場合

アプリのダッシュボードから必要な設定をすべて行える場合は、通常WebUIで十分です。コンテナのターミナルを開かずに済み、設定が不足している、または正常に動作しない場合にのみアクセスすればよいため、ほとんどのユーザーにとって最も安全な方法です。

次のような場合は、WebUIを優先する方法が適しています。

  • アプリを問題なくインストールできる
  • インターフェースからモデルプロバイダーを設定できる
  • シェルにアクセスせずにメッセージングゲートウェイを接続できる
  • ダッシュボードにステータスがわかりやすく表示される
  • ログに権限またはネットワークのエラーが表示されていないこと。

ダッシュボードに必要なオプションがある場合は、まずそれを使いましょう。コンテナーターミナルの設定は、すべてのユーザーが最初に行う標準手順ではなく、代替手段または上級者向けの方法として扱ってください。

コンテナーターミナルの設定が必要な場合

ダッシュボードに必要なオプションがない場合、アプリがコンテナー内でセットアップウィザードを実行する必要がある場合、またはトラブルシューティングでログ、実行環境、アプリ固有のコマンドへのアクセスが必要な場合は、コンテナーターミナルの設定が必要になることがあります。

ここで戸惑うユーザーは少なくありません。ホストのシェルで実行したコマンドは、コンテナー内のアプリには影響しない場合があります。コンテナー内で見えるファイルが、ホスト上の同じパスに存在するとは限りません。権限エラーは、モデルプロバイダーやボットトークンではなく、アプリを実行しているユーザーが原因の場合があります。

コンテナーターミナルを使う前に、現在どのシェルを使っているか、どのユーザーとして実行しているかを正確に確認してください。

開始前に必要なもの

セルフホスト型エージェントのセットアップには、サーバーを稼働させるだけでは不十分です。正常なネットワーク経路、モデルへのアクセス、メッセージングの認証情報、そして誤って別のファイルを変更せずにアプリを管理するための十分な権限が必要です。

インターネットに接続できるホームサーバー

クラウドモデルプロバイダーやメッセージングAPIを利用する場合、ホームサーバーがインターネットに接続できる必要があります。ローカルモデルエンドポイントを利用する場合でも、サーバーからローカルネットワークまたはコンテナーネットワーク経由でそのエンドポイントにアクセスする必要があります。

エージェントが正しくインストールされているように見えても応答しない場合があるため、ネットワークへのアクセスは重要です。たとえば、モデルプロバイダーへの接続、メッセージングゲートウェイ、ダッシュボードは、それぞれ異なるネットワーク経路を使用する場合があります。

まず、次の点を確認してください。

  • サーバーが安定したLAN接続を確保していること。
  • サーバーからモデルエンドポイントまたはプロバイダーにアクセスできること。
  • サーバーからメッセージングAPIにアクセスできること。
  • ブラウザーからダッシュボードのポートにアクセスできること。
  • ゲートウェイをブロックするファイアウォールルールがないこと。

モデルプロバイダーまたはローカルモデルエンドポイント

Hermesが有用な応答を生成するには、モデルとの接続が必要です。クラウドプロバイダー、APIキー、またはOpenAI互換エンドポイントを利用できます。ハードウェアとモデルスタックが対応していれば、ローカルモデルサービスを接続することもできます。

重要なのは、モデルの設定とメッセージングの設定は別々だということです。ボットが正しく接続されていてもモデルプロバイダーが間違っている場合があり、モデルプロバイダーが動作していてもボットゲートウェイが機能しない場合があります。

セットアップを始める前に、モデルのベースURL、APIキー、モデル名、コンテキスト設定を整理しておきましょう。

メッセージングアカウントとボットトークン

Telegramなどのメッセージングプラットフォームを通じてエージェントとやり取りするには、メッセージングアカウントと、ボットまたはゲートウェイの認証情報が必要です。Telegramの場合、通常はボットを作成してトークンを保存します。

ボットトークンはパスワードと同様に扱ってください。Telegramの説明によると、各ボットにはBot APIへのリクエストを認証するための一意のトークンが付与されます。リクエストには、Telegramボットトークンの認証方式に従い、APIパスにトークンを含めます。

ボットトークンを公開チャット、スクリーンショット、ログ、GitHubのissue、共有ドキュメントに貼り付けないでください。トークンが漏えいした場合は、メッセージングプラットフォームの公式手順で再発行してください。

ホストのIPアドレス、ログインアクセス、コンテナの権限

サーバーダッシュボードへのアクセスやSSH接続には、ホストのIPアドレスが必要です。また、アプリを安全に管理できるログインアクセスも必要です。

コンテナベースのセットアップでは、権限は複数のレイヤーに分かれていることがよくあります。

権限レイヤー 制御する対象 よくある間違い 安全な確認方法
ホストユーザー / SSHアカウント ホームサーバーのファイルシステム、Dockerコマンド、サーバーダッシュボードへのアクセス。 ホストの権限がコンテナ内にも自動的に適用されると思い込む。 ログイン中のアカウントと、サーバーレベルで実行できる操作を確認してください。
コンテナユーザー コンテナ内でアプリのプロセスを実行し、アプリファイルを書き込むユーザー。 通常は非rootユーザーで実行するアプリのセットアップをrootで行う。 アプリデータを作成または編集する前に、想定されるコンテナユーザーを確認してください。
マウントされたホストフォルダー コンテナに公開されるホストフォルダーまたはDockerボリューム。 アプリが読み取るパスにマウントされていないホストフォルダーを編集する。 ホスト側のソースパスとコンテナ側の宛先パスを確認してください。
アプリのランタイムパス 設定、ログ、ダウンロード、セッション、一時データが保存される場所。 誤ったレイヤーのファイルを変更したり、再起動後に設定が失われたりする。 再起動後もパスが保持され、アプリユーザーが書き込めることを確認してください。

rootが常に正しいとは限りません。適切でない場面でrootを使うと、後からアプリユーザーが変更できないroot所有のファイルが作成されることがあります。

ホストのパスとコンテナのパスとアプリデータのパス

この記事で最も重要な概念です。Hermes Agentのセットアップで起こる問題の多くは、ホストのパス、コンテナのパス、アプリデータのパス、ログ、ダウンロード、マウントされたボリュームを混同することから生じます。

コマンドを実行したり、問題をデバッグしたりする前に、エージェントコンテナ制御マップを確認してください。

レイヤー 確認すること 検証の目安 よくある障害
ホストシステム サーバー、ダッシュボード、SSHセッション、コンテナマネージャーにアクセスできますか? ダッシュボードまたはSSHセッションが開き、コンテナが実行中として表示されます。 アプリはインストールされているようですが、サーバーまたはコンテナに実際には接続できません。
コンテナランタイム 正しいコンテナ内にいて、想定されるユーザーを使用していますか? シェル、作業ディレクトリ、ユーザーはアプリのセットアップパスと一致しています。 コマンドはホストのシェルで実行され、コンテナ内のアプリには影響しません。
アプリデータのパス 設定、ログ、ダウンロード、ランタイムファイルはどこにありますか? 再起動後も設定とログが保持され、アプリユーザーが書き込める。 再起動後に設定が消える、またはアプリに権限拒否エラーが表示される。
ネットワーク経路 コンテナからモデルプロバイダー、ローカルエンドポイント、メッセージングAPIに接続できますか? 想定されるレイヤーからプロバイダーの確認、ゲートウェイへの接続、ダッシュボードへのアクセスが正常に行える。 アプリが正しくインストールされているように見えても、モデルまたはボットが動作しない。
認証情報とアクセス権 APIキー、ボットトークン、許可リストに登録されたユーザーは安全に設定されていますか? プライベートなテストメッセージが機能し、ログにトークンやアクセスのエラーが表示されない。 ボットトークンが無効、漏えいしている、または許可ユーザーIDが間違っている。
再起動後の動作確認 ゲートウェイまたはサービスの再起動後もセットアップは動作しますか? ボットが応答し、ダッシュボードが正常で、再起動後もログに問題がない。 古い設定が引き続き有効になっている、または新しい設定が保存されない。

ホストシステムから見えるもの

ホストシステムとは、ホームサーバーを動かしている実際のオペレーティングシステムです。ホスト上のフォルダー、Dockerコンテナ、ネットワークインターフェース、ストレージデバイス、システムレベルのサービスにアクセスできます。

アプリがDockerで実行されている場合、ホストからは、コンテナから見えるのと同じようにはアプリの内部パスが見えないことがあります。ホストから見えるのは、Dockerボリューム、バインドマウントされたフォルダー、またはコンテナのメタデータである可能性があります。

そのため、/opt/dataや/app/configのようなパスは、ホスト上とコンテナ内で同じ意味とは限りません。

コンテナから見えるもの

コンテナからは、独自のファイルシステムが見えます。また、コンテナにマウントされたホストのフォルダーも見える場合があります。コンテナのパスとは、アプリから見たパスです。

Dockerの説明によると、バインドマウントはホストマシン上のファイルまたはディレクトリをコンテナ内にマウントします。一方、Dockerボリュームはホスト上のDockerストレージディレクトリ内に作成され、Dockerのバインドマウントストレージモデルを通じてDockerによって管理されます。

この違いが重要なのは、コンテナがアクセスできるホストのパスは、コンテナにマウントされたものに限られるためです。アプリがファイルを見つけられない場合、ホスト上にはファイルが存在していても、想定されるコンテナのパスにマウントされていない可能性があります。

アプリの設定とランタイムデータの一般的な保存場所

アプリの設定、ログ、ダウンロード、ランタイムデータの保存場所は、アプリのパッケージ方法によって異なる場合があります。データの一部はコンテナ内に、一部はDockerボリュームに、また一部はホストからバインドマウントされた場所に保存されることがあります。

セルフホスト型エージェントで扱う一般的なデータの種類は次のとおりです。

  • モデルプロバイダーの設定;
  • ゲートウェイの設定;
  • ボットトークンまたはメッセージングの設定;
  • ログとセッションの状態;
  • 一時ダウンロード;
  • ツールの出力;
  • アプリ固有のランタイムデータ。

重要なのは「ファイルはどこにあるか」だけでなく、「このファイルを管理しているレイヤーはどれか、どのユーザーが変更できるか」です。

セットアップ中にモデルプロバイダーを選択するHermes Agentの画面

パスの混同が権限やデータの問題を引き起こす理由

パスの混同は、よくある問題を2つ引き起こします。1つ目は、ホスト上でファイルを編集しているのに、コンテナは別のパスにある異なるファイルを読み込んでいることです。2つ目は、rootとしてセットアップを実行し、後からアプリのユーザーが変更できないファイルを作成してしまうことです。

ホストのフォルダーを、ファイルがすでに存在するコンテナ内のディレクトリにマウントすると、バインドマウントによって既存のコンテナ内ファイルが見えなくなることもあります。その場合、ファイルはマウントによって隠れているだけなのに、見つからないように見えることがあります。

アプリのデータに関する問題を解決する前に、ランタイム層、マウントされたパス、ファイルの所有者、コンテナユーザーを確認してください。

セルフホストエージェントの設定方法:手順ガイド

セルフホストエージェントの設定は、リスクの低い確認から始め、次に設定を行い、その後に検証するのが基本です。どの層で問題が起きているかを把握する前に、権限を変更したりサービスを再起動したりしないでください。

ステップ1:サーバーのダッシュボードからアプリをインストールするか開く

ホームサーバーでサポートされている最も簡単なインストール方法またはアプリの起動方法から始めてください。サーバーにアプリのダッシュボードがある場合は、そこからHermes Agentがインストール済みで、表示され、実行中であることを確認します。

この段階では、アプリが必要としない限りコンテナに入らないでください。まず、ダッシュボード上のステータス、表示されていればアプリのバージョン、設定ページが利用できるかどうかを確認します。

アプリがまったく起動しない場合は、設定ファイルを変更する前にログを確認してください。

ステップ2:ホストのIPアドレスとネットワーク接続を確認する

ホストのIPアドレスを確認し、ブラウザーやターミナルからサーバーに接続できることを確かめてください。設定によっては、ダッシュボード、SSH、ローカルゲートウェイへのアクセスに同じIPアドレスを使用します。

次に、外部ネットワークに接続できることを確認してください。コンテナからメッセージングAPIに接続できなければメッセージングボットは応答せず、サーバーからモデルのエンドポイントに接続できなければモデルプロバイダーも動作しません。

この確認により、「アプリの設定失敗」と「ネットワーク接続の失敗」を切り分けられます。

ステップ3:正しいユーザーでコンテナに入る

コンテナ内でのターミナル設定が必要な場合は、アプリが想定するユーザーでコンテナに入ってください。誤ったユーザーで作成したファイルは、後で権限エラーの原因になることがあります。

ホストのシェルとコンテナのシェルを同じ環境として扱わないでください。ホストで使えるコマンドがコンテナ内にはない場合や、コンテナ内のファイルパスがホスト上には存在しない場合があります。

セットアップコマンドを実行する前に、次の点を確認してください。

  1. 正しいコンテナ内にいる。
  2. 指定されたコンテナユーザーを使用している。
  3. 想定される作業ディレクトリにいる。
  4. 必要なアプリのコマンドを実行できる。
  5. コンテナを終了して再度入る方法を理解している。

ステップ4:セットアップコマンドを実行する前にアプリ環境を有効化する

セルフホストアプリの中には、仮想環境やアプリ専用のシェル設定を使用するものがあります。環境が有効化されていないと、アプリのコマンドが見つからなかったり、誤った依存関係で実行されたりすることがあります。

このステップは単なる形式的なものではありません。セットアップウィザード、ゲートウェイコマンド、モデル設定コマンドが、アプリと同じ実行環境で動作していることを確認できます。

コマンドが予期せず失敗した場合は、何かを再インストールする前に、正しいコンテナ内にいるか、アプリの環境が有効になっているかを確認してください。

ステップ5: モデルプロバイダーまたはローカルモデルサービスに接続する

モデルプロバイダー、カスタムエンドポイント、またはローカルモデルサービスを設定します。ベースURL、APIキー、モデル名、コンテキスト関連の設定を、使用するプロバイダーに合わせてください。

モデル設定に失敗した場合は、次の順番で確認してください。

  • APIキーは正しいですか?
  • コンテナからベースURLにアクセスできますか?
  • エンドポイントはそのモデル名に対応していますか?
  • アプリには長いコンテキストを扱えるモデルが必要ですか?
  • コンテナ内でネットワークまたはDNSの問題が発生していますか?

モデルのエラーとメッセージングのエラーを混同しないでください。Telegramボットが応答しない場合とモデルプロバイダーの障害は、ワークフローを完了するためにエージェントが両方を必要とするという点でのみ関係しています。

ステップ6: メッセージングゲートウェイを設定する

メッセージングゲートウェイは、エージェントの実行環境をメッセージングプラットフォームに接続します。Telegramの場合、通常はボットトークンと許可するユーザーIDが必要です。

適切なゲートウェイ設定では、エージェントにメッセージを送信できるユーザー、使用するボットトークン、ボットをプライベートチャット、グループチャット、またはその両方で使うかを定義します。

メッセージングボットを、初期設定のまま公開インターフェースとして扱わないでください。セルフホスト型エージェントは、ボットにアクセスできるすべてのユーザーに公開すべきでないツール、ローカルデータ、操作へのアクセス権を持つ場合があります。

ステップ7: ゲートウェイを再起動して新しい設定を適用する

モデルまたはメッセージングゲートウェイを変更した後は、新しい設定を反映するためにゲートウェイの再起動が必要になる場合があります。セットアップが完了したように見えても古い設定のまま動作していることがあるため、再起動の挙動は重要です。

再起動後、ユーザー側とサーバー側の両方から動作を確認します。テストメッセージを送り、ダッシュボードのステータスを確認し、ログに権限、トークン、ネットワークのエラーがないか調べてください。

再起動後に再設定が保持されない場合は、データパスと権限の境界を確認してください。

メッセージングゲートウェイの動作確認に使うHermes AgentのTelegramボット操作画面

権限、トークン、アクセス制御

セルフホスト型エージェントは、ローカルの実行権限と外部の認証情報を組み合わせます。そのため、トークン、許可リスト、ユーザー境界の設定が正しくないと、技術的には動作していても安全とは限りません。

コンテナユーザーが重要な理由

コンテナユーザーによって、コンテナ内でアプリが読み書きできるファイルが決まります。セットアップコマンドをrootとして実行し、その後アプリをroot以外のユーザーとして実行すると、アプリのデータにアクセスできなくなることがあります。

これは多くの場合、アプリのデータパス内で権限エラーとして表示されます。解決策は、常にrootを使い続けることとは限りません。多くの場合、適切な所有権に戻し、想定されたユーザーとしてアプリを実行するのがより良い方法です。

特定の復旧作業で必要な場合に限り root を使用し、通常のアプリファイルを root で作成するのは避けてください。

API キーとボットトークンを保護する必要がある理由

API キーとボットトークンは認証情報です。モデル API キーを使うと、モデルプロバイダーにアクセスできます。ボットトークンを使うと、ボットとしてリクエストを認証できます。

これらの値を公開リポジトリ、スクリーンショット、共有ログ、サポートメッセージに含めないでください。トラブルシューティング時に設定やログを共有する場合は、トークンを伏せてください。

トークンが漏えいした場合は、悪用されないことを期待するのではなく、トークンをローテーションしてください。

ユーザー許可リストでプライベートアクセスを制御する方法

許可リストを使うと、メッセージングゲートウェイ経由でエージェントを操作できるユーザーを制限できます。メッセージングボットには、想定以上に多くの人がアクセスできる可能性があるため、重要です。

プライベートな AI チャットには、合理的な範囲で最小限の許可リストを使用してください。許可するユーザー ID が正しいことと、テストメッセージがそのアカウントから送信されていることを確認します。

複数の人がアクセスする必要がある場合は、ボットを誰でも使える状態にせず、必要な人を個別に追加してください。

メッセージングボットを公開インターフェースとして扱うべきでない理由

メッセージングボットは通常のチャットインターフェースのように感じられるかもしれませんが、その背後には、モデルへのアクセス、ツール、セッション、ローカルランタイムの権限を持つセルフホスト型エージェントが動いていることがあります。

そのため、単純な通知ボットとは異なります。明確なアクセスルール、保護されたトークン、制御されたネットワーク経路が必要です。

グループチャットでは慎重に設定してください。グループ権限、プライバシーモード、ボットの管理者権限によって、ボットが表示または応答できるメッセージが変わることがあります。

よくあるセットアップの問題と解決方法

セットアップの問題の多くは、ランタイム、データパス、権限、ゲートウェイ、シークレット、検証の6つの層のいずれかに原因があります。

アプリのデータパス内の権限エラー

権限エラーは通常、現在のアプリユーザーが必要なファイルやフォルダーを読み取れない、または書き込めないことを意味します。以前のセットアップコマンドで root がファイルを作成した場合や、マウントされたフォルダーの所有者が正しくない場合に発生することがあります。

まず、次の点を確認します。

  • コンテナ内とホストのどちらにいますか?
  • アプリはどのユーザーで実行されていますか?
  • アプリのデータフォルダーの所有者は誰ですか?
  • アプリのデータパスはホストからマウントされていますか?
  • 以前、セットアップコマンドを root で実行しましたか?

対象を理解しないまま、広範囲のフォルダーに対して再帰的に権限を変更しないでください。必要な最小限のパスだけを修正してください。

セットアップ後にボットが応答しない

Hermes Agent 自体が実行中でも、ボットが応答しないことがあります。原因として、トークン、ユーザー許可リスト、メッセージングゲートウェイ、ネットワークアクセス、グループ権限が考えられます。

次の順に確認します。

  1. ボットのトークンが正しいことを確認します。
  2. ユーザー ID が許可されていることを確認します。
  3. 設定後にゲートウェイを再起動したことを確認します。
  4. コンテナからメッセージング API に接続できることを確認します。
  5. トークン、ネットワーク、権限のエラーがないか、アプリのログを確認します。
  6. グループチャットの動作を調べる前に、プライベートチャットをテストしてください。

プライベートチャットではグループの権限という要因が加わらないため、通常、グループチャットよりも簡単にテストできます。

モデルプロバイダーの設定が正しくない

メッセージングボットは応答するのにモデルの応答が失敗する場合、問題はモデルプロバイダーにある可能性があります。ベースURL、APIキー、モデル名、エンドポイントとの互換性を確認してください。

ローカルモデルのエンドポイントを使用している場合は、モデルサービスが稼働していて、コンテナから接続可能かどうかも確認してください。ネットワーク構成が異なると、ホストから接続できるサービスでもコンテナ内からは接続できない場合があります。

プロバイダーのトラブルシューティングは、メッセージングのトラブルシューティングとは分けて行ってください。これにより、本当の問題がモデル接続にあるときにボットの設定を変更せずに済みます。

コンテナからメッセージングAPIに接続できない

コンテナからメッセージングAPIに接続できない場合、ゲートウェイはメッセージを正しく受信または送信できません。DNSの問題、ファイアウォールのルール、プロキシの設定、または外部へのインターネット接続がないことが原因の可能性があります。

ホストとコンテナの両方でインターネットに接続できるか確認してください。両者の接続状況は必ずしも同じではありません。

ホームサーバーでVPN、プロキシ、または制限付きネットワークを使用している場合、コンテナからHTTPSで外部に接続できることを確認してください。

グループチャットの権限またはプライバシーモードが応答を妨げている

グループチャットの動作は、プライベートチャットよりも複雑です。ボットがプライベートチャットでは応答しても、メッセージを閲覧できない、適切な権限がない、またはプライバシー設定の影響を受けているために、グループでは応答しないことがあります。

まずプライベートチャットで動作を確認し、その後グループチャットを別途テストしてください。

グループで使用する場合は、ボットに直接メンションする必要があるか、管理者権限が必要か、必要なメッセージを受信できるプライバシー設定になっているかを確認してください。

Hermes Agentが動作しているか確認する方法

インストールが終わっただけでは、セットアップは完了していません。モデル、ゲートウェイ、権限、ダッシュボード、ログ、再設定の動作がすべて基本的なチェックに合格した時点で完了です。

セットアップウィザードがエラーなく完了する

セットアップウィザードは、コマンドの不足、プロバイダーのエラー、権限エラーが発生することなく完了するはずです。失敗した場合は、再試行する前に、どの層で失敗したのかを記録してください。

セットアップウィザードのエラーは、通常次のいずれかに該当します。

  • モデルプロバイダーの認証情報。
  • 実行環境。
  • コンテナの権限。
  • アプリコマンドの不足。
  • ネットワークアクセス。
  • ゲートウェイの設定。

その分類を参考にして、次に確認する項目を決めてください。

ボットがプライベートチャットのテストメッセージに応答する

メッセージ機能を確認する最も簡単な方法は、プライベートチャットでテストすることです。簡単なメッセージを送信し、ボットが応答することを確認してください。

プライベートチャットで動作するなら、トークン、許可リスト、ゲートウェイ、モデル接続はおおむね正しく設定できている可能性が高いです。グループチャットでまだ動作しない場合は、アプリを再インストールするのではなく、グループの権限とプライバシー設定に注目してください。

最初のメッセージ送信テストには、プライベートチャットを使ってください。

ダッシュボードでエージェントの実行を確認

システムに応じて、ダッシュボードにはエージェントまたはゲートウェイが実行中であることが表示されます。メッセージングアプリだけに頼らずサーバー側の状態を確認できるため、ダッシュボードの状態は役立ちます。

ダッシュボードに停止中または異常の状態が表示されている場合は、トークンやモデルの設定を変更する前にログを確認してください。

ダッシュボードの状態とボットの応答が一致している必要があります。片方が動作してもう片方が失敗する場合、その差から問題のあるレイヤーを特定できます。

ログに権限またはネットワークのエラーがない

ログに「permission denied」「token invalid」「provider unreachable」「gateway failed」「network timeout」などのエラーが繰り返し記録されないことを確認してください。

ログを参考に、次の対応を判断してください。権限エラーは、ファイルの所有者またはコンテナのユーザーに問題があることを示します。ネットワークエラーは、APIに到達できないことを示します。トークンエラーは、認証情報の設定に問題があることを示します。

すべてのレイヤーを一度に修正しようとしないでください。変数を1つ変更し、必要に応じて再起動してから、もう一度テストしてください。

再起動後も再設定が有効

安定したセットアップは、再起動や再設定の後も維持される必要があります。モデルやゲートウェイの設定を変更したら、必要なサービスまたはゲートウェイを再起動し、新しい設定が引き続き適用されていることを確認してください。

再起動後に設定が消える場合は、設定の保存場所とアプリのデータパスが永続化されているかを確認してください。

ここで、ホストパス、コンテナパス、マウントされたボリュームに関する知識が実用的になります。

実際のホームサーバー環境での仕組み

実際のホームサーバー環境でも、基本的なセットアップモデルは変わりません。実行レイヤーを確認し、データパスを調べ、認証情報を保護し、ゲートウェイへのアクセスを設定して、ログとダッシュボードの状態で動作を確認します。

デバイスごとのセットアップガイドでは、具体的なコマンド手順を確認できます。たとえば、ZimaOSでのHermes Agent設定ワークフローでは、モデルプロバイダーの設定、Telegramボットとの連携、アプリユーザーとしてのHermesコンテナへのアクセス、アプリ環境の有効化、セットアップコマンドの実行、ダッシュボードの状態確認、権限やボットの応答エラーのトラブルシューティングを含む、Hermes Agentのセットアップ手順を説明しています。

セルフホストアプリ、メッセージングゲートウェイ、軽量なエージェントのワークフローを、小型の常時稼働サーバーで運用するユーザーにとって、ZimaBoard 2 ホームAIサーバーは、Dockerアプリ、ターミナルアクセス、ローカルサービス、アプリ固有のデータパスをまとめて把握する必要がある環境に適しています。エージェントをホストする方法はほかにもありますが、この記事で説明するホームサーバーのワークフローの一例として参考になります。

重要なのは、特定のセットアップコマンドだけを暗記しないことです。どのレイヤーで操作しているのか、結果をどう検証するのかを理解してください。

よくある質問

Hermes AgentはWebダッシュボードだけで設定できますか?

多くの場合、基本的な設定にはWebダッシュボードで十分です。特に、モデルやゲートウェイの設定ができる場合はそうです。ダッシュボードに必要なオプションがない場合や、トラブルシューティングにアプリレベルのコマンドが必要な場合は、コンテナのターミナルでの設定が必要になります。可能であればまずWebUIを使い、設定手順で必要な場合に限りコンテナのターミナルを使用してください。

ホストのシェルではなく、コンテナに入る必要があるのはなぜですか?

アプリの実行環境や依存関係はコンテナ内にあるため、一部のアプリコマンドはコンテナ内でしか使えません。同じコマンドをホストで実行すると、失敗したり、誤った環境に影響したりすることがあります。適切なユーザーでコンテナに入ることで、設定変更がアプリ自体に反映されるようにできます。

ホストのデータとコンテナのアプリデータは何が違いますか?

ホストのデータはホームサーバーのファイルシステムに保存されます。コンテナのアプリデータは、コンテナ内、Docker管理のボリューム内、またはコンテナにマウントされたホストのフォルダー内に保存される場合があります。画面上で同じフォルダーパスに見えても、ホストとコンテナのレイヤー間で同じ場所を指すとは限りません。そのため、ファイルを編集する前に、マウント設定とアプリのデータ保存場所を確認してください。

Hermes Agentで権限エラーが表示されるのはなぜですか?

権限エラーは、多くの場合、アプリのユーザーに必要なファイルやフォルダーの読み取りまたは書き込み権限がないことを意味します。ファイルがrootユーザーによって作成された場合、マウントされたフォルダーの所有者が正しくない場合、またはコンテナが想定と異なるユーザーで実行されている場合に発生することがあります。権限を広範囲に変更する前に、実行環境のレイヤー、コンテナのユーザー、アプリのデータパス、ファイルの所有権を確認してください。

Telegramボットが応答しないのはなぜですか?

Telegramボットが応答しない場合、トークンが間違っている、ユーザーIDが許可されていない、ゲートウェイを再起動していない、コンテナからTelegram APIに接続できない、またはグループチャットの権限によってメッセージがブロックされている可能性があります。まずプライベートチャットでテストすると、グループ関連の要因を多く取り除けます。その後、ログでトークン、ネットワーク、権限に関するエラーを確認してください。

Hermes Agentをインターネットに直接公開してもよいですか?

セルフホスト型エージェントをインターネットに直接公開するのは、通常、最初に選ぶべき方法ではありません。メッセージングボットやゲートウェイは、ツールやモデルへのアクセス、場合によってはローカル環境での操作にも接続できるため、アクセスを制限する必要があります。インターネットに公開する構成を検討する前に、プライベートなアクセス方法、強力な認証情報、許可リスト、制限的な権限を設定してください。

サポートとヒント

続きを読む

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.