OpenRouter 認証およびモデル管理の設計

本ドキュメントでは、OpenRouter 認証フローとそれに伴うモデル管理変更の設計意図をまとめている。実装の経緯ではなく、プロダクトおよびアーキテクチャの選択に焦点を当てている。

目標

CLI と /auth の両方から OpenRouter への認証を可能にする。
OpenRouter 専用の新しい認証タイプを追加するのではなく、既存の OpenAI 互換プロバイダーパスを再利用する。
初回起動時にユーザーがすぐに数百のモデルを管理する必要なく、すぐに使える体験を提供する。
/manage-models を通じた高度なモデル管理への明確な道筋を維持する。

OpenRouter 認証

OpenRouter は OpenAI 互換プロバイダーとして統合される：

auth type: AuthType.USE_OPENAI
provider settings: modelProviders.openai
API key env var: OPENROUTER_API_KEY
base URL: https://openrouter.ai/api/v1

ランタイムのモデルプロバイダーパスがすでに OpenAI 互換であるため、OpenRouter 固有の AuthType を導入する必要がなくなる。これにより、認証ステータス、モデル解決、プロバイダー選択、設定スキーマが既存のプロバイダー抽象化と整合した状態を保つ。

ユーザー向けのフローは以下の通り：

自動化または直接 API キーを設定する場合：qwen auth openrouter --key <key>
ブラウザベースの OAuth の場合：qwen auth openrouter
TUI フローの場合：/auth → API Key → OpenRouter

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

モデル管理

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

設計上の重要な分離点は以下の通り：

Catalog：OpenRouter などのソースから発見されたモデルの完全なセット。
Enabled set：/model に表示され、ユーザー設定に永続化されるべき、より小さなモデルのセット。

初回の OpenRouter フローでは、大規模なピッカーでユーザーの作業を中断するのではなく、有用なデフォルトの enabled set で認証を完了させるべきである。推奨セットは小規模で安定しており、無料モデルを含む、ユーザーがプロダクトを正常に試せるモデルを優先して選択する必要がある。

/model は引き続き高速なモデル切り替えツールとして機能する。ユーザーがプロバイダーカタログ全体を閲覧・キュレーションする場所にはならないようにする。

`/manage-models`

高度なモデル管理は、専用の /manage-models エントリーポイントに委ねる。このフローではユーザーが以下の操作を行えるようにする：

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

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

現在の範囲

この変更では、OpenRouter 認証とモデルセットアップを快適にするために必要な最小限の実装に留める：

OAuth またはキーベースの認証は、既存の OpenAI 互換プロバイダーパスを通じて OpenRouter を設定する。
初期の enabled model set はキュレーションされ、カタログ全体を設定にダンプしない。
カタログ全体の保存、閲覧、フィルタリング、一括管理は /manage-models に委ねる。

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