# Hermes Agent 接続

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

## 概要

| 項目 | 内容 |
|---|---|
| 利用できるモデル | Claude ✅（Anthropic プロトコル）· GPT ✅ · 中国系モデル ✅ · Gemini ❌（公式の transport 列挙に Gemini アダプターなし） |
| プロトコルと Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 設定場所 | `~/.hermes/config.yaml`（鍵は `~/.hermes/.env`）。Windows ネイティブ版は `%LOCALAPPDATA%\hermes` |
| 公式ドキュメント | [Providers](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/integrations/providers.md) |

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

## 前提条件

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

## 設定手順

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

`~/.hermes/config.yaml` に：

```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` に鍵を置きます：

```text
# ~/.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 互換エンドポイント」）：

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

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

```text
/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 レッグ）：

```bash
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（リクエストボディ欠如は想定内）
```

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

## 既知の制限

- **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 形式](/docs/getting-started/endpoints-and-api-paths)）。
- Gemini 非対応：公式 transport 列挙に Gemini アダプターが無く、`gemini-*` は使えません。
- `OPENAI_BASE_URL` で QCode を指せません：公式ドキュメント上、この変数は `openai-api` プロバイダーにのみ有効。`config.yaml` を使ってください。
- 出力トークン上限は設定不可：公式が `model.max_tokens` 等の旧キーを読むのをやめており、古いチュートリアルはもう陳腐化しています。

## 関連ドキュメント

- [エンドポイントと API 形式](/docs/getting-started/endpoints-and-api-paths)
- [ツール互換性一覧](/docs/ide/tool-compatibility)
- [ACP 概要](/docs/ide/acp)
- [中国系モデル](/docs/usage/cn-models)
- [トラブルシューティング](/docs/reference/troubleshooting)