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

これらのセマンティクスにより、選択時と実行時の認証動作の整合性が保たれます。これらは以下で共有されます。

• resolveAuthProfileOrder（プロファイルの順序付け）
• resolveApiKeyForProfile（実行時の認証情報解決）
• openclaw models status --probe
• openclaw doctor の認証チェック（doctor-auth）

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

プローブ結果には、status 区分（ok、auth、rate_limit、billing、timeout、format、unknown、no_model）に加え、プローブがモデル呼び出しに到達しなかった場合は安定した reasonCode が含まれます。

適格性チェックでは、使用可能な認証情報の理由コードとして ok が報告されます。

トークン認証情報

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

適格性ルール

1. token と tokenRef の両方が存在しない場合、トークンプロファイルは不適格です（missing_credential）。
2. expires は省略可能です。指定する場合は、0 より大きく、JavaScript の Date タイムスタンプの最大値（8640000000000000）以下である有限数の Unix エポックミリ秒でなければなりません。
3. expires が無効な場合（型が不正、NaN、0、負数、非有限値、またはその最大値を超える値）、プロファイルは invalid_expires として不適格になります。
4. expires が過去の日時である場合、プロファイルは expired として不適格になります。
5. tokenRef を使用しても expires の検証は回避されません。

解決ルール

1. リゾルバーの expires に関するセマンティクスは、適格性のセマンティクスと一致します。
2. 適格なプロファイルでは、トークン情報をインライン値または tokenRef から解決できます。
3. 解決できない参照は、models status --probe の出力で unresolved_ref になります。

エージェントコピーの可搬性

エージェントの認証継承は読み取り透過方式です。エージェントにローカルプロファイルがない場合、シークレット情報を自身の認証情報ストア（agents/<agentId>/agent/openclaw-agent.sqlite）へコピーせず、実行時にデフォルト／メインエージェントのストアからプロファイルを解決します。

openclaw agents add などの明示的なコピー処理では、次の可搬性ポリシーが使用されます。

• api_key および token プロファイルは、copyToAgents: false でない限り可搬です。
• oauth プロファイルは、リフレッシュトークンが一度しか使用できない場合やローテーションの影響を受ける場合があるため、デフォルトでは可搬ではありません。
• プロバイダーが所有する OAuth フローは、エージェント間でリフレッシュ情報をコピーしても安全であることが判明している場合に限り、copyToAgents: true でオプトインできます。このオプトインは、プロファイルにインラインのアクセストークン／リフレッシュトークン情報が含まれている場合にのみ適用されます。

可搬でないプロファイルも、対象エージェントが個別にサインインして独自のローカルプロファイルを作成しない限り、読み取り透過継承を通じて引き続き使用できます。

設定専用の認証ルート

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

認証情報ストアに type: "aws-sdk" を書き込まないでください。保存できる認証情報は api_key、token、oauth のみです。従来の auth-profiles.json にこのようなマーカーがある場合、openclaw doctor --fix はそれを auth.profiles に移動し、ストアからマーカーを削除します。

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

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

プローブ対象の解決

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

外部 CLI 認証情報の検出

• 外部 CLI が所有する実行時専用の認証情報（claude-cli 用の Claude CLI、openai 用の Codex CLI、minimax-portal 用の MiniMax CLI）は、プロバイダー、ランタイム、または認証プロファイルが現在の操作の対象範囲に含まれる場合、あるいはその外部ソース用の保存済みローカルプロファイルがすでに存在する場合にのみ検出されます。
• 認証ストアの呼び出し元は、外部 CLI の明示的な検出モードを選択します。永続化済み／Plugin 認証のみを対象とする none、保存済みの外部 CLI プロファイルを更新する existing、具体的なプロバイダー／プロファイルセットを対象とする scoped のいずれかです。
• 読み取り専用／ステータス確認の処理では allowKeychainPrompt: false が渡されます。ファイルに保存された外部 CLI 認証情報のみを使用し、macOS Keychain の結果を読み取ったり再利用したりしません。

OAuth SecretRef ポリシーガード

SecretRef 入力は静的な認証情報専用です。OAuth 認証情報は実行時に変更されるため（更新フローによってローテーションされたトークンが永続化されます）、SecretRef による OAuth 情報の参照を許可すると、変更可能な状態が複数のストアに分散します。

• プロファイルの認証情報が type: "oauth" の場合、そのプロファイルのすべての認証情報フィールドで SecretRef オブジェクトが拒否されます。
• auth.profiles.<id>.mode が "oauth" の場合、そのプロファイルに対する SecretRef ベースの keyRef／tokenRef 入力が拒否されます。
• 違反があると、起動時／再読み込み時のシークレット準備およびプロファイル解決処理でハードエラー（例外の送出）になります。

従来互換のメッセージ

スクリプトとの互換性のため、プローブエラーでは次の先頭行が変更されずに維持されます。

Auth profile credentials are missing or expired.

人間が理解しやすい詳細と安定した理由コードは、後続の行に ↳ Auth reason [code]: ... の形式で続きます。

関連項目

• シークレット管理
• 認証情報の保存