プロバイダーの選択

対応プロバイダー

q の管理対象 Gateway は次をサポートします。

• ローカルサーバーを含む OpenAI 互換 HTTP API
• OpenRouter
• xAI と Grok
• Anthropic ネイティブ Messages API
• 現在の Codex ログインを使うローカル Codex App Server

Gatewayを設定

Studio の Settings → Providers でプロバイダーを追加し、Settings → Services でリスナーを設定します。Studio ホストは非公開ループバックポート上の管理対象 Gateway 子プロセスを監督します。

プロバイダー変更は、置き換え用プロセスの起動に成功してから有効化されます。起動できない場合は、動作中の設定を維持します。

認証情報には可能な限り環境変数参照を使ってください。グローバルなプロバイダー定義は ~/.q/providers.json に保存されます。

モデルロールを割り当て

Settings → Models でメインチャットと interviewer、manager、research、reviewer、coder、commit、thinker、librarian などの専門ロールにモデルを割り当てます。senior developer は reviewer、junior developer は coder のモデルロールを使います。

ロール割り当て一覧から再利用可能なカスタムロールを作成できます。カスタムサブエージェントは自身のツールと委任許可を保ったまま、そのロールを選択できます。

ワークスペース上書きは .q/model.json、グローバル割り当ては ~/.q/config.yaml に保存されます。

モデル API を選ぶ

q は具体的なモデルごとに Chat Completions または Responses を選びます。ネイティブ Responses が確認された OpenAI、xAI、OpenRouter の Gateway 経路は Responses を優先します。Codex App Server、Anthropic ネイティブ、未知の互換エンドポイントは既存の API を使います。Gateway は両方の入力経路を引き続き受け付けます。

Codex App Server では q の minimal agent が node_repl など継承された非公開 MCP ツールを無効にします。Q 自身のツールは引き続き使え、セッショントレースに表示されます。

Studio のモデル API 設定を使うか、~/.q/config.yaml の model_api_modes に完全なモデル ID と chat_completions または responses を指定できます。既定モデルのグループに候補が複数ある場合、Responses は使えません。ロール別グループは各候補モデルの API を選びます。保存済みセッションは両 API で共通のメッセージ形式を使います。

埋め込みを設定

モデル割り当て画面にはグローバルな embedding ターゲットもあります。埋め込み対応モデルを選び、そのモデルが要求するベクトル次元を入力します。q は 1 から 4096 の次元を受け付けます。

Workspace Memory と Library が共有の派生インデックスを維持するため、埋め込み設定はグローバルで、ワークスペースごとの上書きはできません。モデルの割り当てや変更により、再構築可能な HNSW プロジェクションを再設定し、アクティブな Agent Skills を新しいモデルでバックフィルします。ターゲットをクリアするとスキルと履歴の検索は BM25 のみになります。

設定したプロバイダーは埋め込みリクエストに対応し、次元数は選択モデルと一致する必要があります。設定エラーが起きても元の JSON レコードは利用できます。

フォールバックグループ

ロールは順序付きモデルグループを参照できます。候補がタイムアウトするか一時的な HTTP 5xx を返すと、q は次の候補を試します。

ユーザーキャンセル、ツール失敗、検証エラーではフォールバックしません。その場合は別モデルではなく依頼、ツール状態、設定を変更する必要があります。