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

このドキュメントは、次にまたがって使用される標準の認証情報適格性と解決セマンティクスを定義します。

• 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 の一方または両方をサポートします。

# 適格性ルール

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

# 解決ルール

1. リゾルバーのセマンティクスは、expires の適格性セマンティクスと一致します。
2. 適格なプロファイルでは、トークン素材をインライン値または tokenRef から解決できます。
3. 解決できない参照は、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" または組み込みの Amazon Bedrock デフォルト AWS SDK ルートを使用する場合に有効です。これらのプロファイル ID は、一致するエントリが auth-profiles.json に存在しない場合でも、auth.order とセッション オーバーライドに現れることがあります。

type: "aws-sdk" を auth-profiles.json に書き込まないでください。レガシーインストールに そのようなマーカーがある場合、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.

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

# 関連

• シークレット管理
• 認証ストレージ