チュートリアル 7: 設定ファイル

おかえりなさい、エージェント使いの皆さん！今回のチュートリアルでは、Hermes の核心部分である設定ファイルに深く潜り込みます。YAML や環境変数の海で迷子になった経験がある方も、ご安心ください。できるだけ苦痛なく進めていきます。

Hermes のホームベース

すべては ~/.hermes/ に格納されています。エージェントの住まいだと思ってください。中身はこんな感じです：

~/.hermes/
├── config.yaml     # 設定（モデル、ターミナル、TTS、圧縮など）
├── .env            # API キーとシークレット
├── auth.json       # OAuth プロバイダーの認証情報（Nous Portal など）
├── SOUL.md         # プライマリエージェントのアイデンティティ（システムプロンプトのスロット #1）
├── memories/       # 永続メモリ（MEMORY.md、USER.md）
├── skills/         # エージェントが作成したスキル（skill_manage ツールで管理）
├── cron/           # スケジュールされたジョブ
├── sessions/       # ゲートウェイセッション
└── logs/           # ログ（errors.log、gateway.log — シークレットは自動的に伏せ字化）

最も簡単な道：ワンコマンドセットアップ

細かい話に入る前に、プロの技をひとつ：hermes setup --portal を実行してください。OAuth を1回行うだけで、モデルプロバイダーと Tool Gateway の4つのツールすべてが手に入ります。YAML ファイルに一切触れる必要はありません。Portal サブスクライバーは、トークン課金のプロバイダーも10%オフになります。手っ取り早く始めたい人にはうってつけで、私たちも大好きです。

設定の管理

Hermes には、設定を管理するための完全なツールキットが用意されています。毎日使うコマンドはこちら：

hermes config              # 現在の設定を表示
hermes config edit         # エディタで config.yaml を開く
hermes config get KEY      # 解決済みの値を表示
hermes config set KEY VAL  # 特定の値を設定
hermes config unset KEY    # ユーザー設定値を削除
hermes config check        # 不足しているオプションを確認（アップデート後）
hermes config migrate      # 不足しているオプションを対話的に追加

実際の使用例をいくつか紹介します：

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # .env に保存されます

ここがミソ： hermes config set は値を自動的に適切なファイルへ振り分けます。API キーは .env へ、それ以外は config.yaml へ。もう迷う必要はありません！

競合したら何が優先される？

Hermes は次の順序で設定を解決します（優先度が高い順）：

CLI 引数 — hermes chat --model anthropic/claude-sonnet-4 など
~/.hermes/config.yaml — プライマリ設定ファイル
~/.hermes/.env — シークレット用（API キー、トークン、パスワード）
組み込みのデフォルト値 — 安全なハードコード値

経験則： シークレットは .env へ。それ以外はすべて config.yaml へ。両方が設定されている場合、非シークレット設定では config.yaml が優先されます。

環境変数の置換

config.yaml 内で ${VAR_NAME} 構文を使って環境変数を参照できます：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

複数の参照も可能です：url: "${HOST}:${PORT}"。変数が設定されていない場合、プレースホルダーはそのまま残り、警告がログに記録されます。Cursor スタイルの ${env:VAR_NAME} 構文も動作するので、Cursor や Claude の設定からスニペットをそのままコピーできます。

プロバイダーのタイムアウト

プロバイダー単位、モデル単位でタイムアウトを設定できます：

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

また、ストリーミングではない呼び出しの失効を検出するための stale_timeout_seconds もあります。これらの設定は、従来の HERMES_API_TIMEOUT および HERMES_API_CALL_STALE_TIMEOUT 環境変数を上書きします。

実行時制限

長時間実行するサーバー面（ゲートウェイ、hermes serve --isolated）では、ファイルディスクリプタの制限を設定できます：

runtime:
  nofile_soft_limit: 4096

デフォルトは 4096 です。0、false、または null に設定すると、調整が無効になります。

アップデート動作

アップデート設定は config.yaml の updates 配下にあります：

updates:
  pre_update_backup: quick

まとめ

設定ツアーは以上です！覚えておいてください：簡単な道は hermes setup --portal、素早い変更は hermes config set、そしてシークレットは .env に。あなたのエージェントが感謝することでしょう。

次回は、AI プロバイダーとお気に入りのモデルを接続する方法を探っていきます。お楽しみに！