認証

OpenClaw は、モデルプロバイダー向けに OAuth と API キーをサポートしています。常時稼働する Gateway ホストでは、API キーが最も予測可能な選択肢です。サブスクリプション/OAuth フローも、プロバイダーアカウントのモデルと一致する場合は使用できます。

• OAuth フロー全体とストレージ構成：/concepts/oauth
• SecretRef ベースの認証（env/file/execプロバイダー）：シークレット管理
• models status --probeで使用される認証情報の適格性/理由コード：認証情報のセマンティクス

推奨設定：API キー（任意のプロバイダー）

1. プロバイダーのコンソールで API キーを作成します。
2. そのキーをGateway ホスト（openclaw gatewayを実行しているマシン）に設定します。

export <PROVIDER>_API_KEY="..."openclaw models status

3. Gateway が systemd/launchd で動作している場合は、デーモンが読み取れるようにキーを~/.openclaw/.envに設定します。

cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF

4. Gateway プロセス（またはデーモン）を再起動し、再確認します。

openclaw models statusopenclaw doctor

環境変数を自分で管理したくない場合は、openclaw onboardでデーモン用の API キーを保存することもできます。環境変数の読み込み優先順位（env.shellEnv、~/.openclaw/.env、systemd/launchd）の全容については、環境変数を参照してください。

Anthropic：Claude CLI の再利用

Anthropic setup-token 認証は、引き続きサポートされる方法です。この連携では Claude CLI の再利用（claude -p形式の使用）も正式に認められており、ホスト上で Claude CLI のログインが利用できる場合、ローカル/デスクトップでの使用にはこれが推奨されます。長期間稼働する Gateway ホストでは、サーバー側の課金を明示的に制御できる Anthropic API キーが、引き続き最も予測可能な選択肢です。

Claude CLI を再利用するためのホスト設定：

# Gateway ホストで実行claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

これは 2 段階の手順です。まずホスト上の Claude Code を Anthropic にログインさせ、次に Anthropic モデルの選択をローカルのclaude-cliバックエンド経由にするよう OpenClaw に指示し、対応する OpenClaw 認証プロファイルを保存します。

claudeがPATHにない場合は、Claude Code をインストールするか、agents.defaults.cliBackends.claude-cli.commandをバイナリのパスに設定します。

トークンの手動入力

すべてのプロバイダーで使用でき、エージェント単位の SQLite 認証ストアへの書き込みと設定の更新を行います。

openclaw models auth paste-token --provider openrouter

OpenClaw は、各エージェントのopenclaw-agent.sqliteから認証プロファイルを読み取ります。エンドポイントの詳細（baseUrl、api、モデル ID、ヘッダー、タイムアウト）は、認証プロファイルではなく、openclaw.jsonまたはmodels.jsonのmodels.providers.<id>に設定します。

古いインストールにauth-profiles.json、auth-state.json、または{ "openrouter": { "apiKey": "..." } }のようなフラットな形式が残っている場合は、openclaw doctor --fixを実行して SQLite にインポートします。doctor は元の JSON ファイルと同じ場所に、タイムスタンプ付きのバックアップを保持します。

Bedrock のauth: "aws-sdk"のような外部認証ルートは認証情報ではありません。名前付き Bedrock ルートでは、openclaw.jsonのauth.profiles.<id>.mode: "aws-sdk"を設定してください。認証プロファイルストアにtype: "aws-sdk"を書き込まないでください。openclaw doctor --fixは、従来の AWS SDK マーカーを認証情報ストアから設定メタデータへ移行します。

SecretRef を使用する認証情報

• api_key認証情報では、keyRef: { source, provider, id }を使用できます
• token認証情報では、tokenRef: { source, provider, id }を使用できます
• OAuth モードのプロファイルでは SecretRef 認証情報は拒否されます。auth.profiles.<id>.modeが"oauth"の場合、そのプロファイルに SecretRef を使用したkeyRef/tokenRefを設定すると拒否されます。

モデル認証状態の確認

openclaw models statusopenclaw doctor

自動化に適した確認方法です。期限切れ/欠落時は終了コード1、期限切れ間近の場合は2になります。

openclaw models status --check

認証のライブプローブ（範囲を絞るには、--probe-provider、--probe-profile、--probe-timeout、--probe-concurrency、または--probe-max-tokensを追加）：

openclaw models status --probe

注意事項：

• プローブ行の情報源には、認証プロファイル、環境変数の認証情報、またはmodels.jsonがあります。
• auth.order.<provider>に保存済みプロファイルが含まれていない場合、プローブはそのプロファイルを試行せず、excluded_by_auth_orderを報告します。
• 認証情報が存在していても、OpenClaw がそのプロバイダーでプローブ可能なモデルを解決できない場合、プローブはstatus: no_modelを報告します。
• レート制限のクールダウンはモデル単位で適用される場合があります。あるモデルでクールダウン中のプロファイルでも、同じプロバイダー上の別のモデルには引き続き使用できます。

任意の運用スクリプト（systemd/Termux）：認証監視スクリプト。

API キーのローテーション（Gateway）

一部のプロバイダーでは、呼び出しがプロバイダーのレート制限に達すると、設定済みの別のキーを使用してリクエストを再試行します。

プロバイダーごとのキーの優先順位：

1. OPENCLAW_LIVE_<PROVIDER>_KEY（単一の上書き。1 つのキーに固定）
2. <PROVIDER>_API_KEYS（カンマ/空白/セミコロン区切りのリスト）
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_*（この接頭辞を持つ任意の環境変数）

Google プロバイダー（google、google-vertex）では、さらにGOOGLE_API_KEYへフォールバックします。結合されたリストは、使用前に重複が除去されます。

OpenClaw が次のキーへローテーションするのは、エラーメッセージがrate_limit、rate limit、429、quota exceeded/quota_exceeded、resource exhausted/resource_exhausted、またはtoo many requestsに一致する場合のみです。それ以外のエラーでは、別のキーを使用した再試行は行われません。すべてのキーで失敗した場合は、最後の試行で発生した最終エラーが返されます。

保存済みの認証情報を削除しても、プロバイダー側のキーは失効しません。プロバイダー側で無効化する必要がある場合は、プロバイダーのダッシュボードでキーをローテーションまたは失効させてください。

Gateway の実行中にプロバイダー認証を削除する

Gateway のコントロールプレーンを介してプロバイダー認証を削除すると、OpenClaw はそのプロバイダーの保存済み認証プロファイルを削除し、選択されているモデルプロバイダーが削除対象と一致する、実行中のチャット/エージェント処理を中断します。中断された処理は、stopReason: "auth-revoked"を含む通常のキャンセル/ライフサイクルイベントを送出するため、接続中のクライアントは認証情報が削除されたため処理が停止したことを表示できます。

使用する認証情報の制御

OpenAI と従来のopenai-codex ID

OpenAI API キープロファイルと ChatGPT/Codex OAuth プロファイルは、どちらも正規のプロバイダー IDopenaiを使用します。新しい設定では、openai:*プロファイル ID とauth.order.openaiを使用してください。

古い設定、認証プロファイル ID、またはauth.order.openai-codexにopenai-codexがある場合は、従来形式の移行入力として扱い、新しいopenai-codexプロファイルを作成しないでください。次を実行します。

openclaw doctor --fixopenclaw models auth list --provider openai

doctor は、従来のopenai-codex:*プロファイル ID とauth.order.openai-codexエントリを、正規のopenaiルートへ書き換えます。OpenAI 固有のモデル/ランタイムルーティングについては、OpenAIを参照してください。

ログイン時（CLI）

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-idを使用すると、同じプロバイダーに対する複数の OAuth ログインを、1 つのエージェント内で個別に保持できます。

--forceは、選択したエージェントディレクトリ内に保存されている、そのプロバイダーの認証プロファイルを削除してから、同じ認証フローを再実行します。保存済みプロファイルが処理不能、期限切れ、または誤ったアカウントに関連付けられている場合に使用します。プロバイダー側の認証情報は失効しません。

openclaw models auth login --provider anthropic --force

セッション単位（チャットコマンド）

• /model <alias-or-id>@<profileId>は、現在のセッションで特定のプロバイダー認証情報を固定します（プロファイル ID の例：anthropic:default、anthropic:work）。
• /model（または/model list）はコンパクトな選択画面を表示し、/model statusは完全なビュー（候補と次の認証プロファイル、および設定されている場合はプロバイダーのエンドポイント詳細）を表示します。

すでに実行中のチャットに対して認証順序またはプロファイルの固定を変更した場合は、/newまたは/resetを送信して新しいセッションを開始してください。既存のセッションでは、リセットされるまで現在のモデル/プロファイルの選択が維持されます。

エージェント単位（CLI による上書き）

認証順序の上書きは、そのエージェントの SQLite 認証状態に保存されます。

openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

特定のエージェントを対象にするには--agent <id>を使用します。省略すると、設定済みのデフォルトエージェントが使用されます。openclaw models status --probeは、除外された保存済みプロファイルを暗黙にスキップするのではなく、excluded_by_auth_orderとして表示します。

トラブルシューティング

「認証情報が見つかりません」

Gateway ホストに Anthropic API キーを設定するか、Anthropic setup-token の経路を設定してから、再確認します。

openclaw models status

トークンが期限切れ間近/期限切れ

openclaw models statusを実行して、どのプロファイルが期限切れ間近かを確認します。Anthropic トークンプロファイルが欠落しているか期限切れの場合は、setup-token を使用して更新するか、Anthropic API キーへ移行してください。

関連項目

• シークレット管理
• リモートアクセス
• 認証ストレージ