インストールと初期設定 — 1 コマンドで始める

これは何か

Hermes Agent の導入では、大きく分けて 3 つの入り口から触ることになる。

• ワンライナーのインストールスクリプト — Linux・macOS・WSL2・Termux（Android）向けの install.sh、Windows ネイティブ向けの install.ps1。実行するとリポジトリの取得から実行環境の構築、初期設定ウィザードの起動までを一括で行う。
• CLI サブコマンド — hermes setup（全体または model・tools・terminal・gateway・telemetry・agent・tts のセクション単位）、hermes config（設定の読み書き）、hermes doctor（診断）、hermes update（更新）。
• 設定ファイル — ~/.hermes/config.yaml（モデル・実行環境・圧縮設定など非秘匿情報）、~/.hermes/.env（API キー等の秘匿情報）、~/.hermes/auth.json（OAuth 認証情報）。

対応 OS は次の表のとおりで、Windows だけはワンライナーの中身（PowerShell 版）が別物になる。~/.hermes/ 配下のファイル配置全体については 第 2 章 で地図として扱うので、この章ではインストールと設定に絞る。

いつ使うのか

この章の操作が必要になる場面は主に 4 つある。

• とにかく最初に動かしてみたい — API キーを持っていなくても、Nous Portal への無料 OAuth ログインだけで一式が揃う Quick Setup が最短ルート。
• 自分の API キーや社内プロキシを使いたい — Anthropic・OpenAI 等の自前キー、または OpenRouter・カスタムエンドポイントを個別に選びたいときは Full Setup。
• サーバーや CI で非対話インストールしたい — --skip-setup・--non-interactive・--ensure 等のフラグで、対話ウィザードを飛ばして最小限だけ入れられる。
• プライバシー重視で最小構成にしたい、または設定を作り直したい — Web・ブラウザ・memory・delegation・cron・skills 等をすべて無効にした Blank Slate、または hermes setup --reconfigure で既存設定をやり直す。

最初にどのモードを選ぶべきかは、次の表で判断できる。3 モードの中身は 仕組みの解説の該当節 で詳しく扱う。

install.sh は実際に何をしているか

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash のようなワンライナーは、パイプの先でどんなコードが走るのか実行前には見えない。これが初心者にとって一番の不安要素のはずなので、ここでは scripts/install.sh（全 3,847 行）の関数を順番に追って、何が起きるかを先に種明かししておく。

# Linux / macOS / WSL2 / Termux（Android）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

内部では次の関数がこの順で呼ばれる: detect_os → install_uv → check_python → check_git・check_cxx_compiler・check_node → install_system_packages → clone_repo → setup_venv → install_deps → setup_path → run_setup_wizard。図 3-1 は、これを「検出」「導入」「配置」の 3 段階に整理した流れだ。

各段階の実際の中身は次のとおり。

• 1. 環境を検出 — OS（Linux/macOS/WSL2/Termux/root かどうか）を判定し、クローン先レイアウトを決める。非 root のデフォルトは $HERMES_HOME/hermes-agent（既定で $HERMES_HOME=~/.hermes）にコードを置き、コマンドは ~/.local/bin にリンクする。root で新規インストールする Linux だけは /usr/local/lib/hermes-agent（Claude Code や Codex CLI と同じ FHS 配置）になる。
• 2. 依存を導入 — Hermes 専用の uv を $HERMES_HOME/bin/uv に導入し、それを使って Python 3.11 を確保する（uv python install なので sudo 不要）。ほかに git・C++ コンパイラ・Node.js・ripgrep・ffmpeg も自動で入れる。Node.js はバージョン 22.22 以降、24.11 以降、または 26 以降のみ対応で、それ以外（23 系・25 系や条件未満のビルド）は Hermes 管理下の Node（バージョン 26）に自動的に置き換わる — つまりシステムに新しめの Node が入っていても、条件を満たさなければ気づかないうちに二重管理になる、という意味だ。理由は依存パッケージ側の制約（nanoid の対応範囲や @babel/* の要求バージョン）による。
• 3. リポジトリ clone — まず SSH（git@github.com:NousResearch/hermes-agent.git）を試し、失敗したら HTTPS にフォールバックする。--depth 1 --branch main の浅いクローンで、GitHub 側のレート制限に対してはリトライと部分クローンへの自動デグレードがある。
• 4. venv 構築 — クローン先ディレクトリへ cd した直後、Python 3.11 の仮想環境をクローン先の内側（$INSTALL_DIR/venv）に作る。なお README には「venv をチェックアウトの外に置く」という注意書きもあるが、それは手動クローンして開発するコントリビュータ向けの別手順の話（理由は「チェックアウトの内側に venv があると、エージェント自身が実行した相対パスのコマンドで venv ごと壊されるおそれがある」ため）。install.sh の自動フロー自体はクローン先の内側に venv を作る。
• 5. PATH 追加 — 使っているシェル（bash/zsh/fish 等）の rc ファイルに ~/.local/bin を追記する。この段階で追記されるのは設定ファイルへの書き込みだけで、今開いているシェルにはまだ反映されない点は後述のつまずきポイントで扱う。
• 6. setup ウィザード起動 — --skip-setup を付けていなければ、ここで対話式の hermes setup が始まり、3 モードのどれかを選ぶ画面になる。

このほか、ブラウザ自動化用の Playwright/Chromium や Computer Use 用ドライバも既定でここに含めてインストールされる（--skip-browser・--skip-computer-use で個別に省略可能）。実際に使うのは 第 11 章 になる。インストール完了後にゲートウェイを起動するかを聞かれることもあるが、詳細は 第 7 章 に譲る。

Windows ネイティブ版の install.ps1 は同じ役割を PowerShell で担うが、bash.exe を実行するために PortableGit（約 45MB）を %LOCALAPPDATA%\hermes\git に展開する点が異なる。README には簡略化された「MinGit」という表記があるが、スクリプト自体のコメントには「MinGit には bash.exe が入っていないため使えない」と明記されており、32bit Windows など最終手段の場合を除けば実際に使われるのは PortableGit の方だ。

クローンやウィザードを伴わず特定の依存だけを入れ直したいときは --ensure node,browser,ripgrep,ffmpeg のように対象を指定できる。主なオプションは --no-venv・--skip-setup・--skip-browser・--no-skills（バンドル済みスキルを一切入れず、以後の hermes update でも注入しないよう記録する）・--branch・--commit・--dir・--hermes-home がある。導入を丸ごとやり直したいときは hermes uninstall（--dry-run で削除対象だけ確認、--full で設定・データごと削除）が使える。hermes update・hermes doctor・アンインストールの詳細な運用は 第 13 章 にまとめる。

setup ウィザードの3モード

新規インストール時、または hermes setup を素で実行したときに提示される 3 モードは、単なる「簡単/詳しい」の違いではなく、あとから何が有効になるかという設定の中身そのものが変わる。図 3-2 はどのユーザーがどれを選ぶべきかを示す。

とくに Blank Slate は「あとから機能を絞る」のではなく「最初から機能を読み込ませない」設定であることに注意したい。選ばなかったツールセットは agent.disabled_toolsets に、有効な CLI ツールセットは platform_toolsets.cli に明示リストとして書き込まれるため、hermes update でバージョンを上げても、選んでいない機能（Web・ブラウザ・コード実行・vision・memory・delegation・cron・skills・plugins・MCP サーバ）は勝手に有効化されない。圧縮（compression）・チェックポイント・スマートルーティング・メモリ取得（memory capture）も無効になる、文字どおりの最小構成だ。

全体ウィザードのほかに、セクション単位でやり直すこともできる。

hermes setup model|tts|terminal|gateway|tools|telemetry|agent
# フラグ: --non-interactive / --reset / --reconfigure / --quick / --portal

たとえば「モデルだけ変えたい」なら hermes setup model、「ゲートウェイだけ設定し直したい」なら hermes setup gateway（詳細は 第 7 章）というように、丸ごとやり直さずに部分的に直せる。

モデルプロバイダ4系統

Hermes が対応するモデルプロバイダのプラグインは plugins/model-providers/ 配下に 30 種類以上あるが、初心者がまず押さえるべき系統は次の 4 つに整理できる。

図 3-3 は「リクエストがどこへ出ていくか」を示したものだ。ローカル vLLM だけが破線の境界を越えず、自分のマシンの中で完結する。

Nous Portal は hermes setup --portal の一発で、ブラウザでの OAuth ログイン → トークンを auth.json に保存 → モデル選択 → config.yaml への反映 → Tool Gateway（Web 検索・画像生成・TTS・ブラウザ自動化のルーティング）有効化までを済ませる。Portal 経由で使えるモデルは Anthropic・OpenAI・Google Gemini・DeepSeek・Qwen など 280 以上あるが、公式ドキュメントは「Hermes 4 系モデル自体はチャット・推論向けのチューニングであり、高速なツールコールを繰り返すエージェント用途には非推奨」と明記している。

OpenRouter は OPENROUTER_API_KEY という環境変数 1 本で 200 以上のモデルにアクセスできるプロバイダで、hermes model から選ぶか、キー自体は次のように設定する。

hermes config set OPENROUTER_API_KEY sk-or-xxxxxxxxxxxxxxxx
# キーの種類を自動判別し、秘匿情報として .env 側に保存される

カスタム OpenAI 互換エンドポイントとローカル vLLM は、内部的には同じ custom プロバイダの別名にすぎない。専用の「vllm プロバイダ」は存在せず、Ollama・llama.cpp・vLLM・GLM 系エンドポイントなどはすべて custom（エイリアス: ollama / local / vllm / llamacpp）としてまとめて設定する。

hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000   ← これが Hermes の最小値

# 対応する config.yaml:
# model:
#   default: qwen3.5:27b
#   provider: custom
#   base_url: http://localhost:11434/v1

設定ファイルの場所と優先順位

~/.hermes/ の中で、この章に直接関わるのは次の 3 ファイルだ（memories/・skills/・cron/・sessions/ 等は 第 5 章 以降で扱う）。

• config.yaml — モデル・実行環境（terminal backend）・圧縮設定・ツールセットなど、秘匿情報でない全設定
• .env — API キー・トークンなどの秘匿情報
• auth.json — Nous Portal 等、OAuth 方式のプロバイダの認証情報

設定値がどこから読まれるかには優先順位があり、図 3-4 のように「上の層に値が無ければ下の層を見る」というカスケードになっている。

この優先順位を踏まえると、「秘匿情報は .env、それ以外は config.yaml」という役割分担がなぜ成立するかも見えてくる。.env はいちばん下に近い層なので、config.yaml や CLI 引数で明示的に上書きしない限り安定してそこから読まれる、という設計だ。値の出し入れは hermes config サブコマンドで行い、キーの種類ごとに保存先が自動で振り分けられる。

hermes config              # 現在の設定を表示
hermes config edit         # config.yaml をエディタで開く
hermes config get KEY      # 値を取得
hermes config set KEY VAL  # 値を設定（.env / config.yaml に自動振り分け）
hermes config unset KEY
hermes config check        # アップデート後の欠落オプションをチェック
hermes config migrate      # 欠落オプションを対話的に追加

config.yaml の中では ${VAR_NAME} という記法で環境変数を展開できる（未定義の場合はプレースホルダのまま警告が出る）。設定や依存関係が正しく揃っているかをまとめて確認したいときは hermes doctor、導入方式（git installer / Docker / NixOS のどれで入れたか）を自動判定した上でバージョンを上げたいときは hermes update を使う。どちらも普段の運用で繰り返し使うコマンドなので、詳しい読み方は 第 13 章 でまとめて扱う。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

hermes doctor

hermes setup --portal

hermes portal info

hermes config set OPENROUTER_API_KEY sk-or-xxxxxxxxxxxxxxxx

hermes doctor

hermes config unset OPENROUTER_API_KEY

つまずきポイント

理解度チェック

まとめ

• ワンライナーは「検出→依存導入→clone→venv構築→PATH追加→setupウィザード」の6段階を順に実行するだけで、中身が見えないブラックボックスではない
• hermes setup の3モードは難易度の違いではなく、あとから何が有効になるかという設定の中身そのものが変わる。迷ったら Quick Setup
• モデルプロバイダは Nous Portal・OpenRouter・カスタムOpenAI互換・ローカルvLLM（=customの別名）の4系統。無料/課金/データの行き先/オフライン可否で選ぶ
• config.yaml・.env・auth.jsonの役割分担と、CLI引数→config.yaml→.env→既定値という優先順位を覚えておくと設定トラブルの切り分けが早い

導入が済んだら、次は実際にエージェントと対話する番だ。対話モードの画面の読み方やセッション管理は 第 4 章 で扱う。

参考リンク

• Hermes Agent 公式リポジトリ（GitHub）
• 公式ドキュメント: Installation
• 公式ドキュメント: Quickstart
• 公式ドキュメント: Nous Portal
• 公式ドキュメント: Configuration
• OpenRouter