Hermes AgentとCodexサブスクリプション：OAuth設定、利用枠、独立API
OAuth Device Codeフローを介してHermes AgentをChatGPTおよびCodexサブスクリプションと連携させる詳細な技術ガイド。auth.jsonにおけるローカル認証情報の保存形式、無効化されたトークンの自動隔離機能、公式ドキュメントで未公開となっている利用枠の消費ルール、プロバイダー管理画面での課金検証プロトコル、さらに独立した専用APIを用いた代替構成までを網羅的に解説します。
目次
Hermes Agent の統合機能を利用すると、OAuth Device Code フローを介して一般ユーザー向けの ChatGPT や Codex サブスクリプションを用い、OpenAI のモデルへリクエストをルーティングできるようになります。この手法により静的な API キーを入力する手間は省けますが、技術面およびコスト面における不透明性が生じます。認証ハンドシェイクが成功したとしても、それはアカウントの技術的な有効性が確認されたに過ぎず、その後のリクエストに対する課金ルールや消費の仕組みが保証されるわけではありません。
適用範囲と境界：確認済み事項・仕様の未公開点・検証の必要性
Hermes Agent で Codex アカウントを扱う場合、システム間の連携や挙動は以下の3つの明確なカテゴリに分類されます。
| カテゴリ | ドキュメント上の位置づけ | 技術的実装および管理責任範囲 |
|---|---|---|
| 確認済み（Confirmed） | 公式に明記 | Device Code flow による認可。トークンを ~/.hermes/auth.json にローカル保存。~/.codex/auth.json からの認証情報インポート（Codex CLI の単体インストールは不要）。失効したトークンの自動隔離。 |
| 未公開（Undocumented） | 公式には非開示 | サポート対象となるサブスクリプションプランおよび利用枠の消費ルール。公式ドキュメントには対応プランや利用制限の差し引き方法は記載されていない。 |
| 要検証（Requires Verification） | ユーザーの責任範囲 | エージェント実行前後におけるプロバイダー管理ダッシュボードの数値照合、テレメトリ反映遅延の考慮、サブスクリプション課金と独立したAPIキー運用の切り分け。 |
Nous Research の公式ドキュメントに記載されているのは、ネットワーク上のキー交換プロトコルとセッション再開の仕組みのみです。どのサブスクリプションプランが適合するのか、あるいは利用枠がどのように差し引かれるのかといった詳細は公開されていません。そのため、本番タスクを実行する前に、開発者自身がプロバイダーの管理コンソールでアカウント状態を確認する必要があります。エージェントを介して Codex モデルを利用することが「無料」である、あるいは「無制限」である、一般向けプランに制限なしで含まれているといった主張は、技術的な根拠がありません。
設定手順とセッション管理
Hermes のアーキテクチャでは、環境の永続設定を行うコマンドと、対話中の実行時モデル切り替えコマンドが明確に分離されています。
hermes model— アクティブなエージェントセッション外のターミナルから直接実行します。新規プロバイダーの登録、ブラウザを介した OAuth 認可の起動、基本設定パラメータの保存を行う初期設定ウィザードです。/model— セッション対話内で使用する内部コマンドです。すでに設定済みのプロバイダーやモデル間を切り替えるためだけに使用されます。対話チャット内から新しいプロバイダーを追加したり、OAuth 認可フローを実行したりすることはできません。
プロバイダーの初期設定はターミナルで実行し、設定メニューから ChatGPT or Codex Subscription を選択します。
hermes modelこの項目を選択すると、コンソール上に1回限りの検証用 URL と固有の英数字デバイスコードが出力されます。指定された URL をブラウザで開き、OpenAI アカウントにログインして連携を承認します。承認が完了すると、Hermes は取得したアクセストークンおよびリフレッシュトークンをローカルの ~/.hermes/auth.json に保存します。同一マシン上で以前に Codex CLI を使用したことがある場合、エージェントは ~/.codex/auth.json から既存の認証情報を自動的に読み取れるため、Codex CLI パッケージを個別にインストールする必要はありません。
認証エラー処理とトークンの隔離
認可サーバーが致命的な認証エラー（HTTP 4xx レスポンス、invalid_grant ステータス、またはユーザーによるアクセス権限の取り消しなど）を返した場合、Hermes はターミナルログが際限なく更新・出力されるのを防ぐためにリトライ処理を停止します。無効となったリフレッシュトークンは即座にローカルで隔離（クランティン）状態に置かれます。次回エージェントを起動しようとした際には、再ログインを促す所定のシステムメッセージが表示されます。
隔離状態をリセットして再度認証を通すには、以下のコマンドを実行します。
hermes auth add openai-codex別の方法として、hermes model セットアップウィザードを再実行し、サブスクリプションプロバイダーを選択し直すことも可能です。認証情報の更新に成功すると、トークンの隔離ステータスは自動的に解除されます。
独立した専用 API とサブスクリプション運用の比較
一般向けサブスクリプションを利用した OAuth 接続と、静的キーを用いたダイレクトな API 接続は、完全に分離された独立の財務・インフラ環境で動作します。
- サブスクリプション: 一般ユーザー向けの ChatGPT アカウントに直接紐づきます。公式ドキュメントにはサポート対象の契約プラン一覧や、OAuth 経由のリクエストがどのようにクォータ残高を消費するかは明記されていません。エージェントでタスクを開始する前に、アカウントの状態と課金メーターを自身で確認しておく必要があります。
- API キー:
openai-apiプロバイダー（~/.hermes/.env内のOPENAI_API_KEY）またはサードパーティのゲートウェイを選択する際に使用します。運用コストは選択した各プロバイダーの料金体系に従って発生し、単純なトークン量以外の課金要素が含まれる場合もあります。
エージェント運用においてリクエストごとの詳細な利用状況の把握や、代替となるオープンモデルへのアクセスが必要な場合は、サブスクリプション連携を補完または代替する手段として独立したゲートウェイの導入を検討できます。独立したルーティングの具体例としては、BetterToken ドキュメント を参照できます。標準的な OpenAI 互換エンドポイント、個別のアクセスキー、ダッシュボードでの利用量追跡が提供されています。サードパーティの専用 API アクセスは完全に独立した経路として機能するため、既存の ChatGPT/Codex サブスクリプションが変換されることはなく、サブスクリプションの利用枠を引き継ぐことも、同一モデルの提供を保証するものでもありません。
検証チェックリストとトラブルシューティング
一般向けサブスクリプションにおけるクォータ消費の正確な仕組みは公開されていないため、本格的な運用の前に以下の手順に沿って実測ベースラインを測定することを強く推奨します。
- アカウントパラメータの確認: プロバイダーのウェブコンソールで、現在のサブスクリプション種別と利用可能な残枠を記録します（公式に対応しているプランの詳細は公開されていません）。
- タイムスタンプと初期値の記録: テスト開始時のメッセージカウンター初期値と、正確な開始タイムスタンプを記録します。
- 最小限のリクエスト送信: エージェントセッションを開始し、外部ツール呼び出しを伴わない短いテストリクエスト（例:
Calculate 256 * 4）を送信します。 - 残高の照合: テレメトリの反映には遅延が生じる可能性があるため、一定時間待機した後にプロバイダーの課金管理画面を再確認します。カウンターが即座に変動しなかったとしても、その呼び出しが無料であることを意味するわけではありません。
- セキュリティ管理:
~/.hermes/auth.jsonの内容を第三者に共有したり、トークン断片を含むターミナルログを公開したりしないでください。
ログインに成功したにもかかわらず Hermes が HTTP 403 エラーを返したり権限不足を通知したりする場合、Codex 特有の根本原因はドキュメントに記載されていません。エラーメッセージの文面を確認し、契約プランやアカウントの権限要件、選択しているルートおよびモデル ID を再確認したうえで、公式ドキュメントやプロバイダーのサポートに問い合わせてください。必要に応じて、専用アクセスキーを持つ独立した API プロバイダーへ切り替えることも代替手段となります。
