Hermes Agent 接続

Hermes Agent（Nous Research）の config.yaml で QCode.cc を custom provider として登録する：transport の3プロトコル、.env による鍵管理、セッション中のモデル切替

最終確認：2026-09-18 · 📄 公式ドキュメント準拠（Hermes Agent v0.21.3 / tag v2026.9.14、2026-09-14 公開）

概要¶

Hermes Agent は Nous Research の汎用 AI エージェント（経験からスキルを学ぶループを内蔵）。端末 TUI とマルチチャネルゲートウェイ（Telegram / Discord / Slack / CLI）の形で動きます。コードエディタではありません——ただし ACP サーバーとしてエディタのバックエンドにもなれます（ACP 概要 参照）。モデルのエンドポイントはすべて本体の config.yaml に書き、ホスト側のエディタ設定には依存しません。

前提条件¶

• Hermes Agent がインストール済み（インストールは公式 README に従ってください。本頁ではコマンドを重複しません）。
• QCode.cc の cr_ キー（コンソールで発行）。Nous Portal やモデルベンダーのアカウントは不要。
• 役割分担：シークレットは ~/.hermes/.env、挙動設定は config.yaml。モデルとエンドポイントの唯一の真実源は config.yaml——旧 LLM_MODEL 環境変数は公式により削除済み。

設定手順¶

ルート A：名前付きプロバイダー（推奨。Claude と GPT / 中国系を併存）¶

~/.hermes/config.yaml に：

# ~/.hermes/config.yaml
model:
  provider: custom:qcode_claude
  default: claude-sonnet-5

providers:
  qcode_claude:
    api: https://api.qcode.cc/api
    key_env: QCODE_API_KEY
    transport: anthropic_messages
    default_model: claude-sonnet-5
    discover_models: false
  qcode_openai:
    api: https://api.qcode.cc/openai/v1
    key_env: QCODE_API_KEY
    transport: chat_completions
    default_model: glm-5.3

続けて ~/.hermes/.env に鍵を置きます：

# ~/.hermes/.env
QCODE_API_KEY=cr_your-QCode-key

ポイント（いずれも公式 providers ドキュメント由来）：

• transport の正規値は 3 つのみ：chat_completions / anthropic_messages / codex_responses（小文字・アンダースコア）。QCode で Claude を使うなら anthropic_messages 必須。
• エンドポイント条部の URL キーは公式教学では api（base_url / url は受理される別名）。プロトコルキーは transport（api_mode は別名）。
• key_env には変数名を書く（$ 無し）。値は .env 側。
• プロバイダー URL が /anthropic 終わりなら transport が自動判定されるが、/api 終わりでは発火しないため transport は明示必須。

ルート B：単一エンドポイント（OpenAI 互換レッグのみ）¶

まずは GPT / 中国系だけ動かすなら、公式のフラットな書き方（provider: custom は「任意の OpenAI 互換エンドポイント」）：

model:
  provider: custom
  base_url: https://api.qcode.cc/openai/v1
  api_key: cr_your-QCode-key
  default: gpt-5.6

セッション中のモデル切替¶

/model custom:qcode_claude:<model-id>
/model custom:qcode_openai:<model-id>

<model-id> には各プロバイダーで宣言済みのモデル ID を入れます（Anthropic 側は claude-sonnet-5、OpenAI 側は glm-5.3 など）。

公式の役割分担に注意：/model は設定済みの provider / モデルの切り替えのみ可。新しい provider の追加はセッションを抜けて hermes model ウィザードを実行してください。

接続の確認¶

hermes を起動して一言投げる。失敗時は順に：

1. パスと鍵の到達確認（OpenAI レッグ）：

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $QCODE_API_KEY"
# → 401 = 鍵が無効；400 = パス OK（リクエストボディ欠如は想定内）

1. providers: 条部の YAML インデント（2 スペース同階層）が崩れていないか。
2. key_env の変数名と .env の記述が完全一致しているか。
3. 全リクエストは probe.qcode.cc に記録されます。それでも駄目なら トラブルシューティング へ。

既知の制限¶

• Anthropic レッグは未実測：公式の anthropic_messages 実例はいずれも「ホスト＋プレフィックス」で /v1 を付けません（例 https://proxy.example.com/anthropic）。本頁も倣って https://api.qcode.cc/api としていますが、Hermes が最終パスをどう組むかは未検証です。404 なら api を完全パス https://api.qcode.cc/api/v1/messages に変更してください。
• discover_models: false：Hermes はカスタムエンドポイントで <base>/models を探索します。QCode の OpenAI レッグには存在しますが、/api/models は存在しません（実測 404）。Claude 条では上記の通り探索を無効化し、default_model / models で明示してください。
• 中国系モデルを codex_responses に回さないこと——QCode の Responses レッグは GPT 系専用（対応表：エンドポイントと API 形式）。
• Gemini 非対応：公式 transport 列挙に Gemini アダプターが無く、gemini-* は使えません。
• OPENAI_BASE_URL で QCode を指せません：公式ドキュメント上、この変数は openai-api プロバイダーにのみ有効。config.yaml を使ってください。
• 出力トークン上限は設定不可：公式が model.max_tokens 等の旧キーを読むのをやめており、古いチュートリアルはもう陳腐化しています。

関連ドキュメント¶

• エンドポイントと API 形式
• ツール互換性一覧
• ACP 概要
• 中国系モデル
• トラブルシューティング