OpenRouter 認証とモデル管理の設計

このドキュメントでは、OpenRouter 認証フローとそれに伴うモデル管理の変更の背後にある設計意図を説明します。実装の経緯ではなく、製品とアーキテクチャ上の選択に焦点を当てます。

目標

ユーザーが CLI と /auth の両方から OpenRouter で認証できるようにする。
新しい認証タイプを追加する代わりに、既存の OpenAI 互換プロバイダパスを再利用する。
初回実行時に、ユーザーに数百のモデルをすぐに管理させることなく、使いやすい状態にする。
/manage-models によるより豊かなモデル管理への明確なパスを維持する。

OpenRouter 認証

OpenRouter は OpenAI 互換プロバイダとして統合されています。

認証タイプ: AuthType.USE_OPENAI
プロバイダ設定: modelProviders.openai
API キー環境変数: OPENROUTER_API_KEY
ベース URL: https://openrouter.ai/api/v1

これにより、ランタイムのモデルプロバイダパスがすでに OpenAI 互換である場合に、OpenRouter 固有の AuthType を導入することを回避しています。認証状態、モデル解決、プロバイダ選択、設定スキーマを既存のプロバイダ抽象化と整合させたままにできます。

ユーザー向けのフローは次のとおりです。

/auth → 対話的な TUI フロー用の OpenRouter。
自動化や直接の API キー設定用の環境変数: OPENROUTER_API_KEY と OPENAI_BASE_URL=https://openrouter.ai/api/v1。
明示的なモデルプロバイダエントリが必要なスクリプト設定用の ~/.qwen/settings.json。

ブラウザ OAuth では OpenRouter の PKCE フローを使用し、交換された API キーを設定に書き込んだ後、AuthType.USE_OPENAI として認証を更新します。

モデル管理

OpenRouter は大規模で動的なモデルカタログを公開しています。発見されたすべてのモデルを modelProviders.openai に書き込むと、/model が煩雑になり、長期的な設定フィールドがリモートカタログのキャッシュになってしまいます。

主要な設計上の分割は次のとおりです。

カタログ: OpenRouter などのソースから発見されたモデルの完全なセット。
有効セット: /model に表示され、ユーザー設定に永続化されるべき、より小さいモデルのセット。

初期の OpenRouter フローでは、認証が大きな選択画面でユーザーを中断させるのではなく、有用なデフォルトの有効セットで完了するようにする必要があります。推奨セットは小さく、安定しており、無料モデルが利用可能な場合はそれを含め、ユーザーが製品を問題なく試せるようなモデルに偏っている必要があります。

/model は高速なモデル切り替えのままです。ユーザーがプロバイダの全カタログを閲覧・キュレーションする場所になるべきではありません。

`/manage-models`

より豊かなモデル管理は、別のエントリポイント /manage-models に属します。そのフローでは、ユーザーが次の操作を行えるようにする必要があります。

発見されたモデルを閲覧する。
ID、表示名、プロバイダプレフィックス、free や vision などの派生タグで検索する。
現在有効になっているモデルを確認する。
モデルを一括で有効または無効にする。

ソースの次元は、この設計の一部として残す必要があります。OpenRouter は最初の動的カタログソースにすぎません。将来のソース (ModelScope や ModelStudio など) も同じ形状に適合する必要があります。UI の複雑さは軽減できますが、基盤となるソースの抽象化は拡張ポイントとして利用可能な状態を維持する必要があります。

現在の境界

この変更は、OpenRouter の認証とモデル設定を快適にするために必要な最小限のものにすべきです。

OAuth またはキーベースの認証により、既存の OpenAI 互換プロバイダパスを通じて OpenRouter を構成します。
初期の有効モデルセットは、全カタログを設定にダンプするのではなく、キュレーションされます。
カタログ全体の保存、閲覧、フィルタリング、一括管理は /manage-models に延期されます。

設計原則はシンプルです。認証はユーザーを迅速に動作可能な状態に導き、モデルキュレーションは専用の管理フローに配置するということです。