2026年 Hermes Agent 完全インストール＆設定ガイド：チェックリスト式完全チュートリアル＋実践ケース
Hermes Agent のチュートリアルは「見た目は完璧なのに、終わっても動いているか分からない」ことがよくあります。本記事ではインストール・設定・初回起動・実践ケースを 6 段階のチェックリストに整理し、各項目に「何を確認するか」「合格基準」「失敗時に最初に見る場所」を明示します。
インストールコマンドは実行したのに API キーが未設定、CLI は起動するのに権限が広すぎてログの場所も不明——そんな状態は珍しくありません。完全なインストール＆設定は段階ごとに受け入れテストすべきです。環境・インストール・モデル・権限・ログ・実践ケースのすべてが合格して初めて、Hermes Agent は「本当に使える」状態になります。
先に押さえる要点： macOS では公式ワンライナーインストーラーのハード前提は Git のみ。設定は ~/.hermes/ に集約。健全性確認は hermes doctor。実践ケースは専用テストディレクトリで実行し、初日からフルディスクアクセスは付与しない。
総チェックリスト：ゼロからケース合格まで
6 段階を順番に進め、すべてにチェックが付いてから Gateway・Cron・本番リポジトリへ拡張してください。
| 段階 | コア合格基準 | 主要コマンド / パス |
|---|---|---|
| ① インストール前 | Git・ネットワーク・テスト用ディレクトリ・API キーアカウント準備完了 | git --version、~/hermes-workspace |
| ② インストール | hermes --version 動作、ディレクトリ構成正常 |
公式 install.sh、~/.local/bin/hermes |
| ③ 設定 | プロバイダ・モデル・.env・ワークスペース・ログパス確認済み | hermes setup、~/.hermes/.env |
| ④ 初回起動 | モデル ping・ファイル R/W・ログ・再起動復帰 | hermes、hermes doctor |
| ⑤ 実践ケース | 要約＋TODO 出力、ログ追跡可能、ロールバック OK | テストディレクトリ内 sample.txt |
| ⑥ トラブルシュート / 仕上げ | 層別逆引き；拡張前に権限を絞る | ~/.hermes/logs/ |
1. インストール前チェックリスト
curl コマンドをコピーする前に、すべての行を確認してください。公式 Git インストーラーの唯一のハード前提は Git です。Python 3.11、Node.js v22、uv、ripgrep、ffmpeg はインストールスクリプトが処理します。
| ☐ | 確認項目 | 合格基準 | 失敗時、最初に確認 |
|---|---|---|---|
| ☐ | macOS とチップを確認 | Apple Silicon または Intel Mac；OS バージョンが現行 公式インストールドキュメント を満たす | macOS アップグレード、または pip / Nix 経路 |
| ☐ | git --version |
バージョン表示；未インストールなら xcode-select --install または Homebrew で git 導入 |
Xcode CLT / Homebrew |
| ☐ | ネットワークテスト | curl -I https://raw.githubusercontent.com と利用予定 LLM プロバイダドメインの両方に到達 |
プロキシ、DNS、社内ファイアウォール |
| ☐ | ディスク空き容量 | 5〜10 GB 以上（Python venv、Node、ブラウザ自動化依存関係） | ~/Library/Caches の整理 |
| ☐ | LLM アカウントと API キー作成 | OpenRouter（柔軟）または Anthropic / OpenAI 等；キーはパスワードマネージャーに保存、チャットやスクショには貼らない | プロバイダ課金コンソール、地域制限 |
| ☐ | テスト用ワークスペース作成 | mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} と chmod 700 ~/hermes-workspace |
パス typo、ディスク権限 |
| ☐ | 既存設定のバックアップ（再インストール時） | 旧 ~/.hermes/ を backups/ に tar 保存 |
バックアップなしで rm -rf ~/.hermes しない |
| ☐ | サンプルテキスト準備（実践ケース用） | ~/hermes-workspace/inbox/sample.txt が存在、200〜500 語程度で十分 |
UTF-8 エンコーディング |
2. インストールチェックリスト
公式 macOS コマンド（2026 年 5 月時点ドキュメント）：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash代替：pip install hermes-agent（PyPI、v0.14+）；Nix ユーザーは公式 Nix ガイド参照。カスタムパスは HERMES_INSTALL_DIR — 公式ドキュメントを確認。
| ☐ | 確認項目 | 合格基準 | 失敗時、最初に確認 |
|---|---|---|---|
| ☐ | コマンドソースを検証 | URL が NousResearch/hermes-agent リポジトリ main/scripts/install.sh を指す |
不明なワンクリックスクリプトは使わない |
| ☐ | インストール出力を監視 | 致命的エラーなし；clone、venv、uv、Node ステップが中断なく完了 | ネットタイムアウト → 再試行；権限 → 意図的でなければ sudo 回避 |
| ☐ | source ~/.zshrc 後 which hermes |
パスが ~/.local/bin/hermes（ユーザー単位インストール） |
PATH 未反映 → 新ターミナル；~/.local/bin が PATH にあるか確認 |
| ☐ | hermes --version または hermes doctor |
CLI がバージョン/診断を表示；command not found なし |
venv ランチャーではなくシステム Python を誤呼び出し |
| ☐ | インストール構成を確認 | コード ~/.hermes/hermes-agent/；データ ~/.hermes/ 作成済み |
HERMES_HOME が意図せず上書き |
| ☐ | ランタイム依存関係 | hermes doctor が Python、Node、ripgrep 等を緑/修正ヒント表示 |
doctor 出力の不足項目；hermes update を試す |
3. 設定チェックリスト
主要ファイル：~/.hermes/config.yaml（設定）と ~/.hermes/.env（API キー・環境変数）。初回はフルウィザードを実行：
hermes setup # フルウィザード
# または段階的に：
hermes model # プロバイダとモデルを選択
hermes tools # ツールの有効/無効
hermes config set KEY value| ☐ | 確認項目 | 合格基準 | 失敗時、最初に確認 |
|---|---|---|---|
| ☐ | LLM プロバイダ設定 | hermes model 後 config.yaml に model.default；OpenRouter 例：OPENROUTER_API_KEY を .env に |
キー typo、地域制限、アカウント残高 |
| ☐ | 秘密ファイルの権限 | chmod 600 ~/.hermes/.env；config.yaml に平文キーを書かない |
yaml や git への誤コミット |
| ☐ | 作業ディレクトリ | MESSAGING_CWD=~/hermes-workspace（または絶対パス）を .env に |
パス不存在、iCloud 同期ディレクトリの誤用 |
| ☐ | ターミナルバックエンドと権限 | 試用期：terminal.backend: local + approvals.mode: manual；本番は docker/ssh を検討 |
YOLO モードや GATEWAY_ALLOW_ALL_USERS の誤有効化 |
| ☐ | ログの場所 | ~/.hermes/logs/ が存在し書き込み可能；Dropbox/iCloud 同期パス上に置かない |
ディスク満杯、ディレクトリ権限 |
| ☐ | ツールセット | hermes tools でケースに必要なもののみ（ファイル R/W、ターミナル）；ブラウザ/gateway は後から |
余分なツールが権限面を拡大 |
| ☐ | 設定整合性 | hermes config check 合格；アップグレード後は必要なら hermes config migrate |
migrate なしのバージョンジャンプ |
4. 初回起動チェックリスト
cd ~/hermes-workspace
hermes # 対話型 CLI| ☐ | 確認項目 | 合格基準 | 失敗時、最初に確認 |
|---|---|---|---|
| ☐ | モデル ping | 「OK と言って」等の短いプロンプトに数秒で妥当な応答；API key not set なし |
hermes model、.env 変数名、プロバイダステータス |
| ☐ | ファイル読み書き | エージェントが scratch/ に ping.txt を作成し読み返せる；ファイルはワークスペース内のみ |
cwd、macOS プライバシー許可、承認の誤拒否 |
| ☐ | ログ書き込み | 会話後 ~/.hermes/logs/ に新エントリまたは更新タイムスタンプ |
ログレベル、ディレクトリ権限 |
| ☐ | ターミナル終了・再起動 | 新ターミナルで hermes 起動；設定保持 |
シェルプロファイルに PATH 未永続化 |
| ☐ | 再起動復帰（任意） | 再起動後も CLI 動作；hermes gateway install 済みなら launchd 自動起動（公式ドキュメント通り） |
launchctl list | grep hermes、gateway ログ |
| ☐ | hermes doctor 最終確認 |
ブロッキング項目なし；インストール方式（git / pip / nix）正しく検出 | doctor 項目を一つずつ修正——盲目的な再インストールは避ける |
5. 実践ケースチェックリスト：テキスト要約＋TODO 抽出
テストディレクトリで最初の検証可能タスクを完了してください。本番リポジトリ、クラウドコンソール、~/Documents は指定しない。
5.1 入力の準備
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
週次スタンドアップメモ（テスト用）
- Alex: 来週 API ドキュメント v2 を完成
- Jordan: 水曜までに login 403 を修正
- Sam: Hermes Agent と OpenClaw を比較し金曜に報告
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak5.2 タスクプロンプト（hermes CLI に貼り付け）
inbox/sample.txt を読み、outbox/ に 2 ファイルを作成：
1) summary.md — 200 語以内の要約
2) todos.md — 担当者と期限付き Markdown TODO リスト
inbox 原本は変更しない。ワークスペース外のパスにはアクセスしない。| ☐ | 確認項目 | 合格基準 | 失敗時、最初に確認 |
|---|---|---|---|
| ☐ | 出力ファイル存在 | outbox/summary.md と outbox/todos.md 作成；名前・日付が入力と一致 |
承認待ち、モデル幻覚 |
| ☐ | 原本未変更 | diff inbox/sample.txt backups/sample.txt.bak で差分なし |
プロンプト制約、ツール権限 |
| ☐ | ログ追跡可能 | ログに本セッションのツール呼び出し記録 | ログパス、ログレベル |
| ☐ | ロールバック検証 | rm outbox/*.md 後タスク再実行成功；バックアップで復元可能 |
セッションキャッシュ、ファイルロック |
| ☐ | コスト観察 | プロバイダコンソールで想定トークン使用量；上限設定可能なら設定済み | 過大モデル、ツールループ |
| ☐ | 権限境界 | ~/.hermes/.env や ~/.ssh を読まない；危険コマンドは手動承認 |
ツール設定、承認モード |
6. トラブルシュートチェックリスト：層別逆引き——再インストールは最後
問題発生時は層を下から順に確認。「インストール済みだが動かない」の多くは PATH・キー・cwd の問題で、Hermes 本体の破損ではありません。
| 層 | 症状 | 最初に確認 | よくある修正 |
|---|---|---|---|
| 依存関係 | hermes: command not found |
PATH、~/.local/bin |
source ~/.zshrc |
| ネットワーク | インストール/モデルタイムアウト | curl GitHub、プロバイダ API | プロキシ、DNS、別ネットワーク |
| キー | API key not set |
~/.hermes/.env 変数名 |
hermes model または hermes config set |
| プロバイダ | 401/429/5xx | プロバイダステータス、残高、モデル ID | モデル切替、上限設定、後で再試行 |
| 権限 | ファイル書込不可 / コマンド拒否 | cwd、承認キュー、macOS TCC | コマンド承認、ワークスペースパス修正 |
| パス | 設定が見つからない | HERMES_HOME、マルチユーザー競合 |
HERMES_HOME 統一または専用アカウント |
| ログ | 無言の失敗 | ~/.hermes/logs/、errors.log |
ログキーワードから設定修正 |
| バックグラウンド | Gateway 無応答 | launchd 状態、トークン、許可リスト | hermes gateway サブコマンド、公式 gateway ドキュメント |
7. 完了後チェックリスト：本番ワークフロー接続前
- ☐
~/.hermes/を再バックアップ（設定、skills；必要なら sessions） - ☐
approvals.modeが manual のまま、またはチーム方針と一致 - ☐ Gateway 有効時：許可リスト / DM ペアリング設定済み；
GATEWAY_ALLOW_ALL_USERSなし - ☐ プロバイダコンソールで支出上限とアラート設定
- ☐ 本番リポジトリを紐付ける前に outbox 品質を手動レビュー
- ☐ ツールやターミナルバックエンド拡張前に公式 Security ドキュメントを読む
すべての段階が合格したら、Telegram Gateway、Cron、CI 連携へ拡張してください。Mac の権限とキー境界をさらに絞るには、関連記事 Hermes Agent Mac 完全セキュリティ設定ガイド も参照してください。
Mac mini で Hermes を動かすと、受け入れテストがより明確に
Hermes Agent は Git、Python、Node、Unix ターミナルツールに依存します——macOS では WSL やドライバ調整なしにネイティブ動作。専用 Mac mini でエージェントを動かすと、CLI 試行、Gateway、ログを日常使い MacBook から分離できます。Apple Silicon のユニファイドメモリはローカル Ollama ルーティングに有利で、Gatekeeper・SIP・FileVault がシステムレベルの整合性を補強します。
Mac mini M4 はアイドル時約 4W、ファンレスで静音、24/7 エージェントノードに適しています。hermes gateway install の launchd と組み合わせれば再起動後もサービス復帰。本チェックリストを進めるなら、Mac mini M4 はコスパの高い専用ホストの一つです——今すぐ手に入れ、安定したハードウェアですべてのゲートを通過しましょう。