OpenClaw認証情報の管理：資格情報と解決ルールを徹底解説

開発を進めている中で、「なぜか認証が通らない」「どの設定が優先されているのか分からない」といった問題に直面したことはありませんか？認証情報の解決ルールが不明確だと、デバッグに多くの時間を費やしてしまいます。

この記事では、認証情報の適格性と解決に関する標準的なセマンティクスについて解説します。これにより、開発時と実行時の挙動を一致させ、スムーズな認証管理を実現できます。

Auth Credential のセマンティクス

このドキュメントでは、以下のコンポーネント全体で使用される標準的な認証情報の適格性および解決セマンティクスを定義します。

目的は、選択時の挙動と実行時の挙動を一致させることです。

エラーや状態を特定するために、以下の理由コードが使用されます。

Token Credential（type: "token"）は、インラインの token または tokenRef（あるいはその両方）をサポートしています。

token と tokenRef の両方が存在しない場合、そのトークンプロファイルは不適格となります。
expires は任意項目です。
expires を指定する場合、0 より大きい有限の数値である必要があります。
expires が無効な場合（NaN、0、負の数、非有限数、または型が正しくない場合）、そのプロファイルは invalid_expires として不適格になります。
expires が過去の時刻を示している場合、そのプロファイルは expired として不適格になります。
tokenRef を使用している場合でも、expires のバリデーションはスキップされません。

Resolver のセマンティクスは、expires に関する適格性のセマンティクスと一致します。
適格なプロファイルについては、インラインの値または tokenRef からトークン素材が解決されます。また、解決できない参照がある場合は、models status --probe の出力に unresolved_ref が表示されます。

SecretRef の入力は、静的な認証情報のみを対象としています。
プロファイルの認証情報が type: "oauth" の場合、その認証情報素材として SecretRef オブジェクトを使用することはできません。
auth.profiles.<id>.mode が "oauth" に設定されている場合、そのプロファイルに対する SecretRef ベースの keyRef や tokenRef の入力は拒否されます。
これらの違反は、起動時または再読み込み時の認証解決パスにおいて、致命的なエラー（hard failure）として扱われます。

スクリプトの互換性を維持するため、プローブエラーの最初の行は以下のように変更せず保持されます。

Auth profile credentials are missing or expired.

人間が理解しやすい詳細な情報や、安定した理由コードは、2行目以降に追加される場合があります。

OpenClaw Expert

このページで解決しない場合は、OpenClaw Expertに直接質問してください。