Gateway

認証情報のセマンティクス

このドキュメントは、以下全体で使用される正規の認証情報適格性と解決セマンティクスを定義します。

resolveAuthProfileOrder
resolveApiKeyForProfile
models status --probe
doctor-auth

目的は、選択時とランタイムの動作を一致させることです。

安定したプローブ理由コード

ok
excluded_by_auth_order
missing_credential
invalid_expires
expired
unresolved_ref
no_model

トークン認証情報

トークン認証情報（type: "token"）は、インラインの token および/または tokenRef をサポートします。

適格性ルール

token と tokenRef の両方が存在しない場合、トークンプロファイルは不適格です。
expires は任意です。
expires が存在する場合、0 より大きい有限数でなければなりません。
expires が無効（NaN、0、負数、非有限、または誤った型）の場合、プロファイルは invalid_expires で不適格です。
expires が過去の場合、プロファイルは expired で不適格です。
tokenRef は expires の検証を回避しません。

解決ルール

リゾルバーのセマンティクスは、expires の適格性セマンティクスと一致します。
適格なプロファイルでは、トークン素材をインライン値または tokenRef から解決できます。
解決できない参照は、models status --probe 出力で unresolved_ref を生成します。

エージェントコピーのポータビリティ

エージェント認証の継承は読み通しです。エージェントにローカルプロファイルがない場合、ランタイムでデフォルト/メインエージェントストアからプロファイルを解決でき、シークレット素材を自身の auth-profiles.json にコピーする必要はありません。

openclaw agents add などの明示的なコピーフローでは、このポータビリティポリシーを使用します。

api_key プロファイルは、copyToAgents: false でない限りポータブルです。
token プロファイルは、copyToAgents: false でない限りポータブルです。
oauth プロファイルは、リフレッシュトークンが単回使用またはローテーションに敏感な場合があるため、デフォルトではポータブルではありません。
プロバイダー所有の OAuth フローは、エージェント間でリフレッシュ素材をコピーしても安全であることが分かっている場合にのみ、copyToAgents: true でオプトインできます。

非ポータブルなプロファイルは、対象エージェントが別途サインインして独自のローカルプロファイルを作成しない限り、読み通し継承を通じて引き続き利用できます。

設定専用の認証ルート

mode: "aws-sdk" を持つ auth.profiles エントリは、保存された認証情報ではなくルーティングメタデータです。対象プロバイダーが models.providers.<id>.auth: "aws-sdk"、または Plugin 所有の Amazon Bedrock セットアップ AWS SDK ルートを使用する場合に有効です。これらのプロファイル ID は、auth-profiles.json に一致するエントリが存在しない場合でも、auth.order とセッションオーバーライドに現れることがあります。

auth-profiles.json に type: "aws-sdk" を書き込まないでください。レガシーインストールにそのようなマーカーがある場合、openclaw doctor --fix はそれを auth.profiles に移動し、認証情報ストアからマーカーを削除します。

明示的な認証順序フィルタリング

プロバイダーに対して auth.order.<provider> または認証ストアの順序オーバーライドが設定されている場合、models status --probe は、そのプロバイダーの解決済み認証順序に残っているプロファイル ID のみをプローブします。
そのプロバイダーの保存済みプロファイルが明示的な順序から省略されている場合、後で暗黙的に試行されることはありません。プローブ出力は reasonCode: excluded_by_auth_order と詳細 Excluded by auth.order for this provider. でそれを報告します。

プローブ対象の解決

プローブ対象は、認証プロファイル、環境認証情報、または models.json から取得できます。
プロバイダーに認証情報があるものの、OpenClaw がそのプロバイダーに対してプローブ可能なモデル候補を解決できない場合、models status --probe は reasonCode: no_model とともに status: no_model を報告します。

外部 CLI 認証情報の検出

外部 CLI が所有するランタイム専用の認証情報は、現在の操作のスコープ内にプロバイダー、ランタイム、または認証プロファイルがある場合、またはその外部ソースの保存済みローカルプロファイルがすでに存在する場合にのみ検出されます。
認証ストア呼び出し側は、明示的な外部 CLI 検出モードを選択する必要があります。永続化済み/Plugin 認証のみの場合は none、すでに保存されている外部 CLI プロファイルを更新する場合は existing、具体的なプロバイダー/プロファイルセットの場合は scoped です。
読み取り専用/ステータスパスは allowKeychainPrompt: false を渡します。ファイルベースの外部 CLI 認証情報のみを使用し、macOS Keychain の結果を読み取ったり再利用したりしません。

OAuth SecretRef ポリシーガード

SecretRef 入力は静的認証情報専用です。
プロファイル認証情報が type: "oauth" の場合、そのプロファイル認証情報素材では SecretRef オブジェクトはサポートされません。
auth.profiles.<id>.mode が "oauth" の場合、そのプロファイルに対する SecretRef ベースの keyRef/tokenRef 入力は拒否されます。
違反は、起動/再読み込みの認証解決パスでハードフェイルになります。

レガシー互換メッセージング

スクリプト互換性のため、プローブエラーはこの先頭行を変更せずに保持します。

Auth profile credentials are missing or expired.

人間が読みやすい詳細と安定した理由コードは、後続行に追加される場合があります。