2026年 Hermes Agent 完全インストール＆設定ガイド：ゼロから実戦まで手厚いチュートリアル

2. よくあるつまずき

1. 制限：「起動できた」で終わる。ウェルカム表示はモデル接続・ファイルツール・ゲートウェイ到達を保証しません。本当に使える状態は、環境確認・モデル接続・権限境界・ログ追跡・低リスク実践検収のセットです。
2. 隠れコスト：キーとパスの散在。API Key がメモだけ、config.yaml と .env が不一致、作業区がホーム全体——一度の誤操作で SSH 鍵や本番リポジトリに触れるリスクがあります。
3. 安定性と監査：ログの場所を忘れる。問題時にいきなり再インストールすると ~/.hermes/logs/errors.log の手がかりを消し、バックアップなしの更新では設定を戻せません。

3. インストール前の準備：Mac と環境チェックリスト

目的：途中でネットワーク・Git・ディスク不足で止まらないようにする。合格基準：下の項目をすべて満たしてから install を実行。

• システム：macOS 12+（Intel / Apple Silicon いずれも可。ローカル推論は Apple Silicon が有利な場合がありますが、クラウドモデルは provider ドキュメント準拠）。
• Git：公式 git インストーラの唯一の必須前提は Git（git --version、2.30+ 推奨）。未導入なら Xcode Command Line Tools または brew install git。
• ネットワーク：GitHub raw（インストールスクリプト）と選んだ LLM provider API に到達できること。社内プロキシは HTTPS_PROXY を事前設定。
• ディスク：Python 3.11、Node.js v22、ripgrep、ffmpeg、リポジトリ取得で空き ≥ 2GB 推奨（Skills 込みで 1.5–3GB 程度のことも——公開時点の公式記載で再確認）。
• 権限：ユーザーインストールに sudo は不要。root で入れた履歴があるとデータが /root/.hermes 側にある場合あり。
• バックアップ：既存 ~/.hermes があるなら cp -a ~/.hermes ~/.hermes.bak-$(date +%F)。
• テストディレクトリ：隔離作業区 ~/hermes-lab を作成。初回実践を ~/Documents、本番 git、秘密情報ディレクトリに向けない。

# インストール前クイックチェック
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes lab sample: Q2 planning notes." > ~/hermes-lab/inbox/sample.txt

失敗時はまず：Git エラー → CLT/Homebrew；ディスク不足 → 空き確保；タイムアウト → ネット変更。原因未特定のまま三連続再インストールは避ける。

4. 公式手順で Hermes Agent をインストール

目的：Nous Research 公式エントリで Python・Node・CLI をまとめて揃える。出典：公式 Installation（公開前にバージョン・引数を再確認）。

4.1 推奨：Git ワンライナー（main 追従）

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

インストーラが uv、Python 3.11、Node.js v22、ripgrep、ffmpeg、リポジトリ clone、venv、PATH への hermes 登録を行います。典型的な per-user 配置：

• コード：~/.hermes/hermes-agent/
• データ・設定：~/.hermes/（HERMES_HOME で上書き可）
• CLI：~/.local/bin/hermes

4.2 代替：pip（Python 3.11+ 必須）

pip install hermes-agent
hermes postinstall   # 任意：Node・ブラウザ・ripgrep・ffmpeg と setup

PyPI はタグ付きリリース追従。最新 edge が必要なら上記 git スクリプトを推奨。hermes update の挙動は方式により異なる——hermes doctor の表示を信頼してください。

4.3 インストール直後の三ステップ

source ~/.zshrc          # または新しいターミナル
hermes version           # バージョンをメモ（後のトラブルシューティング用）
hermes doctor            # 不足検出；--fix で修復試行

合格基準：which hermes → ~/.local/bin/hermes；hermes doctor にブロッキング FAIL なし。失敗時はまず：スクリプト末尾 20 行 → PATH → システム Python でリポジトリ内ファイルを直接叩いていないか（venv ランチャを使う）。

注意：失敗直後に「~/.hermes を消して再インストール」しない。ターミナル出力と hermes doctor を保存し、ネットか権限かを切り分ける。

5. モデルと API Key の設定

目的：選んだ LLM provider を Hermes から呼べるようにする。合格基準：非対話スモークで妥当な応答；hermes auth list または .env に項目があり、シェル履歴に Key が残り続けない。

5.1 対話式（初回向け）

hermes setup          # モデル・ツール・ゲートウェイ等
# または分割：
hermes model          # provider と既定モデル
hermes tools          # ツールセット

5.2 環境変数と設定ファイル

主設定は多くの場合 ~/.hermes/config.yaml、秘密は ~/.hermes/.env（hermes config path、hermes config env-path で実パス確認）。変数名は provider 公式に合わせ、古い記事の名前をそのままコピーしない：

# 例：OpenRouter（自分の key に置換、git にコミットしない）
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# または .env 直接（chmod 600 ~/.hermes/.env）
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

境界：料金・API 上限・地域・プライバシーは provider 側で変わります。本番前に最新条項を確認し、特定モデル名には本文で固定しません。

6. 作業ディレクトリ・権限・ログ

目的：導入後に「追跡できる・制限できる・戻せる」状態にする。原則：最小権限——まずテストディレクトリのみ、本番は段階的に。

• 作業区：config.yaml またはセッションで ~/hermes-lab。AGENTS.md で許可ツールと境界を書く（公式 Context Files 参照）。
• macOS 権限：ターミナル／ファイル系ツールで「フルディスクアクセス」が出る場合、初回検収ではテスト dir 関連のみに留める。
• ログ：既定 ~/.hermes/logs/（agent.log、errors.log、gateway.log）。hermes logs list、hermes logs errors --since 30m。
• 秘密情報：chmod 600 ~/.hermes/.env；バックアップ zip を同期フォルダに置かない；~/.ssh・決済・本番 kubeconfig は読ませない。
• バックグラウンド（任意）：Telegram/Discord 等は hermes gateway setup / install。常駐運用はHermes 長期メンテナンスガイドを参照。

合格基準：「~/hermes-lab のみ読み書き」と指示後、外側パスは拒否またはログに監査痕跡が残る。

7. 初回実行の検収：七ステップ Runbook

「設定完了」から「実戦可用」への門番です。出力のスクリーンショットかログ抜粋を残すことを推奨します。

1. 診断：hermes doctor --fix → 未処理 FAIL なし。
2. モデル ping：hermes chat -q "Reply with exactly: HERMES_OK" → 応答に HERMES_OK。
3. 読み取り：~/hermes-lab/inbox/sample.txt の先頭文を要約させる。
4. 書き込み：~/hermes-lab/outbox/ping.txt を作成 → cat で確認。
5. ログ：hermes logs errors --since 10m → 新規 ERROR なし（既知の無視可は記録）。
6. ターミナル再起動：ウィンドウを閉じ、新規で手順 2 を再実行（PATH が session 限定でないか）。
7. 任意で Mac 再起動：再起動後も手順 2。gateway 導入済みなら hermes gateway status も。

参考しきい値（個人検収、公式 SLA ではない）：スモーク応答 < 60s；10 分以内の未説明 ERROR 0；ls -la ~/hermes-lab/outbox に新ファイル。

8. 最初の実践ケース：要約 + ToDo + ロールバック可能な出力

シナリオ：テスト dir のサンプルを読み、日本語で 150 字以内の要約と ToDo 3 件を Markdown に書き、バックアップを残す。インストール・設定・実 workflow（読む→推論→書く→ログ）を一度に検証します。

# 1. 入力準備（第 3 節で作成済みならスキップ可）
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
今週完了：Hermes インストール文書の下書き。
フォロー：OpenRouter の予算アラート設定；来週 Telegram gateway を評価。
リスク：API Key を git にコミットしないこと。
EOF

# 2. 対話セッション
hermes
# プロンプト例：
# 「~/hermes-lab のみ使用。inbox/weekly-notes.txt を読み、
#   日本語で 150 字以内の要約と ToDo 3 件を outbox/summary-and-todos.md に保存し、
#   原稿を archive/weekly-notes.bak にコピーして」

# 3. 非対話確認
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

合格基準：

• summary-and-todos.md に要約と ToDo 3 件、原文と整合。
• archive/ にバックアップ、diff 可能。
• ログに tool call；provider ダッシュボードに今回の呼び出し（コスト確認用）。

ロールバック：rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt。失敗時はまず：コンテキスト切れで未読 → outbox 書き込み権限 → errors.log の tool エラー。

9. トラブルシューティング：層別に切り分け、盲目的再インストールを避ける

公開前ファクトチェック（編集者向け）：install.sh URL、最低 macOS、既定ディレクトリ、CLI サブコマンド、provider 環境変数名、ログパス——いずれか変更時は本文を先に更新。読者は hermes doctor → errors.log → 最後に再インストール、の順を覚えれば十分です。

10. 次の拡張：テスト dir から本番 workflow へ

検収後は次のペースで広げ、いきなり本番リポジトリや決済系には接続しない：

1. 実プロジェクトを 1 つだけホワイトリストに追加。依然 ~/.ssh とグローバル * 読み書きは禁止。
2. hermes cron で低リスク日次タスク（例：ダウンロード一覧——対象はテスト dir のみ）。
3. メッセージゲートウェイ 1 つをペアリング制限付きで有効化（公式 Security 参照）。
4. 週次 hermes backup --quick の後、長期メンテ記事でアップグレード／ロールバック演習。