ACP ホスト連携

Hermes Agent は ACP サーバーとして動かせます。ACP に対応したホストは、標準入出力を通して Hermes とやり取りできます。エディタ側では次のものを表示できます。

チャットのメッセージ
ツールの動き
ファイルの差分
端末で実行したコマンド
承認を求める画面
少しずつ流れてくる思考や返答

エディタ以外のホストも、同じ手順で共同作業のイベントを Hermes へ流し込めます。会話のやり取り自体は別のアプリに任せつつ、Hermes 側の名義・プロバイダ設定・記憶・スキル・ツールをそのまま保ちたいときに ACP が向いています。

ACP モードで使えるもの

ACP モードの Hermes は、エディタ作業向けに選び抜いた hermes-acp ツールセットで動きます。中身は次のとおりです。

ファイル系: read_file、write_file、patch、search_files
端末系: terminal、process
Web / ブラウザ系
記憶、やることリスト、セッション検索
スキル
execute_code と delegate_task
画像認識

一方で、メッセージの配信や定期実行の管理など、エディタでの使い勝手に合わないものは意図的に外してあります。

インストール

Hermes を普通にインストールしたあと、インストール先のディレクトリで ACP 用の追加パッケージを入れます。

cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'

これで agent-client-protocol が入り、次のものが使えるようになります。

hermes acp
hermes-acp
python -m acp_adapter

ACP サーバーを起動する

次のどれを実行しても、Hermes が ACP モードで立ち上がります。

hermes acp

hermes-acp

python -m acp_adapter

Hermes はログを標準エラー出力へ書きます。標準出力は ACP の JSON-RPC 通信専用に空けてあるためです。

対話せずに状態だけ確かめたいときは次を使います。

hermes acp --version
hermes acp --check

ブラウザ系ツール（任意）

ブラウザ系のツール（browser_navigate、browser_click など）は npm パッケージの agent-browser と Chromium に依存していて、Python のパッケージには含まれていません。次のコマンドで入れてください。

hermes acp --setup-browser           # interactive (prompts before ~400 MB download)
hermes acp --setup-browser --yes     # accept the download non-interactively

これは単体で実行するコマンドです。端末での認証の流れ（hermes acp --setup）でも、モデルを選んだあとに続けてブラウザの導入を尋ねられるので、多くの場合は --setup-browser を直接実行する必要はありません。

このコマンドが行うことは次のとおりです。

Node.js 26 が無ければ ~/.hermes/node/ に入れる
そのディレクトリを指定して npm install -g agent-browser @askjo/camofox-browser を実行する（npm の --prefix が Hermes 管理下の書き込み可能な Node を指すため、管理者権限は要りません）
Playwright の Chromium を入れる。システムに Chrome や Chromium が見つかればそれを使う

この処理は何度実行しても安全です。2 回目以降は済んでいる部分を飛ばすので短時間で終わります。

ホスト側の設定

Buzz のチャンネル（リレーによる橋渡し）

Buzz は Nostr を土台にした、人とエージェントのための共同作業ツールです。付属の buzz-acp というハーネスが、Buzz のチャンネルと任意の ACP エージェントを標準入出力でつなぎます。

Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent

これは通信経路をつなぐ仕組みであって、Hermes をもう 1 つ入れるわけではありません。 buzz-acp が起動する子プロセスは、そのホスト上の hermes と同じ設定・認証情報・記憶・スキル・状態を使います。

（Buzz Desktop の管理下で動かす方法とは別物です。あちらは手元の Hermes をあらかじめ用意されたハーネスとして起動します。こちらのリレー橋渡しは、主にサーバー上でエージェント名義として Buzz の*チャンネル*に参加するためのものです。）

事前に必要なもの:

上の ACP のインストールと hermes acp --check を済ませておく。
Buzz のリポジトリから buzz-acp と buzz コマンドを

ビルドしておく（cargo build --release -p buzz-acp）。

Hermes 専用の Nostr 鍵ペアを発行し（buzz-admin generate-key）、リレーのメンバーとして

登録する（buzz-admin add-member）。エージェントにはそれぞれ固有の名義が必要です。人が使っている鍵ペアを使い回さないでください。

参加させたい Buzz のチャンネルに、その名義を追加する。

橋渡しは次のように起動します。

export BUZZ_RELAY_URL="wss://community.example.com"
export BUZZ_PRIVATE_KEY="..."
export BUZZ_API_TOKEN="..."
export BUZZ_ACP_AGENT_COMMAND="hermes"
export BUZZ_ACP_AGENT_ARGS="acp"

buzz-acp

BUZZ_API_TOKEN が要るのは、リレー側がトークン認証を必須にしている場合だけです。秘密鍵や API トークンをコミットしたり、どこかに貼り付けたりしないでください。

サーバーに常駐させるなら、buzz-acp はサービス管理の仕組みで動かし、実行ユーザーは対象の Hermes ホームを所有している OS ユーザーと同じにしてください。設定、鍵の生成、チャンネルの検出、エージェントごとの選択肢については buzz-acp の README に説明があります。

橋渡しは Hermes の名義がメンバーになっている Buzz のチャンネルをすべて見つけ、新しいチャンネルに追加されたときも自動で参加します。つまり、どこまで見えるかを決めるのは Buzz のチャンネル参加状況であり、Hermes 側の設定にチャンネル一覧を別途書く必要はありません。

Hermes の ACP としての動きを所有者の Buzz Desktop に映したいときは、次を追加します。

export BUZZ_ACP_RELAY_OBSERVER="true"

これで、エージェントの所有者宛てに暗号化された種別 24200 の観測フレームが送られます（Buzz の NIP-AO）。Desktop 側では、起動から終了までの流れ、ツールの実行、返答、使用量がエージェントの Activity log にそのまま流れます。リレーはこのフレームを一時的なものとして扱うため、やり取りが始まる前に Desktop を起動しておく必要があります。所有者の手元に残る記録は Desktop のローカル保存分です。

画面のない橋渡しでは、承認画面を出すエディタが存在しないため、ACP の権限要求には橋渡し自身が答えます。詳しくは Buzz のエージェントは所有者だけが使える状態にするを参照してください。この橋渡しは強い権限を持つ自動処理だと考えてください。専用の OS アカウントを用意し、エージェントに話しかけられる Buzz 利用者を制限し（buzz-acp には BUZZ_ACP_AGENT_OWNER による所有者だけに応答する仕組みがあります）、Hermes に働いてほしいチャンネルにだけ参加させてください。

VS Code

ACP Client 拡張機能をインストールします。

つなぎ方は次のとおりです。

アクティビティバーから ACP Client のパネルを開きます。
組み込みのエージェント一覧から Hermes Agent を選びます。
接続してチャットを始めます。

自分で Hermes を定義したい場合は、VS Code の設定の acp.agents に次を追加します。

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Zed の設定で、Hermes を独自のエージェントサーバーとして登録します。

Agent Panel を開きます。
次の内容で独自のエージェントサーバーを追加します。

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Hermes の外部エージェントスレッドを新しく開きます。

事前に必要なもの:

先に hermes model でプロバイダの認証情報を設定するか、~/.hermes/.env や ~/.hermes/config.yaml に書いておいてください。

JetBrains

ACP に対応したプラグインを使い、hermes acp または hermes-acp を指すように設定します。

Buzz Desktop

Buzz には Hermes Agent があらかじめ実行環境として組み込まれています。 Hermes を通常どおりインストールしてあれば Buzz が自動で見つけるので、 Settings → Runtimes を開けば実行環境の一覧に Hermes が現れます。

古いインストールなどで見つからない場合は、ログインシェルの PATH 上に ACP の起動用ファイルがあるかどうかを確かめてください。

command -v hermes-acp || command -v hermes

最近のインストールでは hermes と hermes-acp の両方の起動用ファイルが ~/.local/bin に書き込まれます。古いインストールでも hermes update を実行すれば hermes-acp が追加されます。手動で対処するなら、Buzz 側のエージェント起動コマンドを hermes、引数を ["acp"] に設定してください。

モデルの選択

Buzz Desktop（v0.5.1 以降）では、エージェントの実行環境の設定画面に Hermes のモデル一覧がそのまま表示されます。この一覧は ACP を通して Hermes 自身が渡すもので、Hermes 側で認証済みのプロバイダのモデルがすべて並びます（hermes model や /model コマンドで見えるものと同じです）。つまり、一覧に無いモデルは、そのプロバイダの認証情報が Hermes 側に設定されていないということです。

一覧の項目は provider:model の形（例: openrouter:z-ai/glm-5.1）か、config.yaml に定義した OpenAI 互換の独自エンドポイントであれば custom:<name>:<model> の形になります。ここでモデルを選ぶと、そのエージェントのセッションにだけ適用されます。Hermes 全体の既定は変わりません。既定を変えるには hermes model を使ってください。

Buzz のエージェントは所有者だけが使える状態にする

Buzz は新しいエージェントを作るとき、Who can talk to this agent を必ず Owner only にします。実行環境が Hermes のときは、この設定のままにしてください。

この経路では 2 つの挙動が重なります。まず hermes-acp のツールセットには terminal と execute_code が含まれます。そして Buzz の ACP 橋渡しは、Hermes からの権限要求を画面に出さず自分で allow_once と答えます。つまり Buzz 上の Hermes エージェントは、確認なしでホスト上のシェルコマンドを実行します。実際に、使い捨てのディレクトリに対して rm -rf を実行するよう頼んでみたところ、そのまま削除されました。確認は一度も出ませんでした。

ここで Anyone を選ぶと、そのチャンネルに手が届く投稿者すべてに同じシェル権限を渡すことになります。Buzz は選んでも警告を出しません。

すぐ思いつく対策は、どちらも今のところ効きません。

approvals.mode: manual にすると Hermes は確かに権限要求を出しますが、

Buzz がそれを自動承認するのでコマンドは実行されます。

platform_toolsets.acp では ACP のツールセットを絞り込めないため、

terminal を外す用途には使えません。

所有者が !shutdown と送ればどのモードでもエージェントは停止します。Buzz は他の人からのこのコマンドを無視します。

設定と認証情報

ACP モードは CLI と同じ Hermes の設定を使います。

~/.hermes/.env
~/.hermes/config.yaml
~/.hermes/skills/
~/.hermes/state.db

プロバイダの決定も Hermes の通常の仕組みどおりなので、ACP でも現在設定されているプロバイダと認証情報がそのまま引き継がれます。また Hermes は、初めて接続する ACP クライアント向けに端末での認証方法（--setup）を提示します。これを選ぶと Hermes の対話式のモデル・プロバイダ設定が開きます。

ホスト側から渡される設定

ここで挙げる変数は、ACP ホスト側のプロセス（エディタや別のエージェントのハーネス）が、起動した Hermes の子プロセスに対して設定するものです。利用者が設定するものではないので、 .env や config.yaml に自分で書かないでください。

変数	値	効果
`HERMES_ACP_SKIP_CONFIGURED_MCP`	`1`	ACP の JSON-RPC 通信を始める前に、`config.yaml` に書かれた全体設定の MCP サーバーを起動する処理を飛ばします。

Hermes は通常、ACP の JSON-RPC 通信に入る前に config.yaml の MCP サーバーをすべて起動します。 MCP を自分で管理するホスト（セッションで使うサーバーを session/new で明示的に渡すホスト）にはこの全体起動が要らず、無関係で遅い、あるいは入力を求めてくる MCP サーバーがあると initialize が待たされてしまいます。この目印をちょうど 1 にすると、そうしたホストは起動処理を飛ばせます。

飛ばされるのは全体設定の config.yaml の検出だけです。ACP セッションが session/new で渡した MCP サーバーはこれまでどおり登録されるので、ホストが求めた機能が失われることはありません。それ以外の値（未設定、空、0、false）では従来どおりの動きになります。真っぽく見える無関係な文字列で MCP が黙って無効になることはありません。

セッションの扱い

ACP のセッションは、サーバーが動いている間、ACP アダプタがメモリ上で管理します。

セッションごとに保持されるのは次のものです。

セッション ID
作業ディレクトリ
選んだモデル
現在の会話履歴
中断用のイベント

内部の AIAgent は Hermes の通常の保存やログの仕組みをそのまま使いますが、ACP の list/load/resume/fork が対象にするのは、いま動いている ACP サーバープロセスの分だけです。

作業ディレクトリの扱い

ACP のセッションは、エディタの作業ディレクトリを Hermes のタスク ID に結びつけます。そのため、ファイル系や端末系のツールはサーバープロセスの場所ではなく、エディタで開いている作業場所を基準に動きます。

承認

危険な端末コマンドは、承認を求める形でエディタ側に返せます。ACP の承認の選択肢は CLI より単純です。

今回だけ許可
常に許可
拒否

実際に確認画面が出るかどうかはホスト次第です。ホストは要求をプログラムで自動的に答えてもかまわず、その場合これらの選択肢は通信上は存在しても人の目には届きません。Buzz Desktop がまさにこの動きをするので、approvals の設定にかかわらず、この経路は無人での実行だと考えてください。

制限時間を過ぎたときやエラーが起きたときは、承認の橋渡し部分が要求を拒否します。

セッションの間だけ編集を自動承認する

ACP には、*今回だけ許可*と*常に許可*の中間にもう一段あります。このセッションの間は許可です。エディタの確認画面でこれを選ぶと、承認は今の ACP セッションの中にだけ記録されます。以降そのセッションで同じ内容のコマンドが来ても確認なしで通りますが、ACP セッションを新しく始めたりエディタを再起動したりすると記録は消え、最初の 1 回はまた確認されます。

選択肢	エディタでの表示	適用範囲	再起動後も残るか
`allow_once`	Allow once	このツール呼び出し 1 回だけ	残りません
`allow_session`	Allow for session	この ACP セッション内で条件の合う呼び出しすべて	残りません。セッションが終わると消えます
`allow_always`	Allow always	今後のすべてのセッション	残ります（Hermes の恒久的な許可リストに書かれます）
`deny`	Deny	このツール呼び出し 1 回だけ	残りません

作業のあいだだけエージェントを信用したいけれど、長く残る許可は与えたくない。エディタでの作業はたいていそういう形なので、既定としては allow_session が向いています。安全面の兼ね合いは分かりやすくて、範囲を広げるほどエディタに邪魔されなくなる一方、エージェントが誤動作したりプロンプトを乗っ取られたりしたときに、気づくまでに受ける被害も大きくなります。見慣れないコマンドはまず allow_once で始め、同じ動きを何度か問題なく確認できたら allow_session に上げ、allow_always は何度実行しても影響のない、ずっと信用できるコマンド（git status など）に絞ってください。

ACP の橋渡し部分は、これらの選択肢を Hermes 内部の承認の考え方に対応づけます。allow_always は CLI と同じように恒久的な許可リストへ書き込み、allow_session は今の ACP セッションのプロセス内にある承認の記録だけに影響します。

うまくいかないとき

エディタにエージェントが出てこない

次を確認してください。

手動設定や開発中の環境なら、ホスト側の起動コマンドが hermes acp を指しているか。
Hermes がインストールされていて、PATH 上にあるか。
ACP 用の追加パッケージが入っているか（cd ~/.hermes/hermes-agent && uv pip install -e '.[acp]'）。

起動した直後にエラーで落ちる

次のコマンドで状態を確かめてください。

hermes acp --version
hermes acp --check
hermes doctor
hermes status

認証情報が足りない

ACP モードは Hermes に設定済みのプロバイダをそのまま使います。認証情報は次のコマンドで設定してください。

hermes model

~/.hermes/.env を直接編集してもかまいません。端末での認証の流れ（hermes acp --setup）から、対話式のプロバイダ・モデル設定を呼び出すこともできます。