OpenClawのAPIキーエラーを直す：401・429・Gatewayの切り分け

OpenClawで「No API Key」や401が出たら、エラーを返した接続と、そこで実際に使ったプロバイダー・認証元を確認するのが最初の一手です。モデル提供元のAPIキー、Gatewayへ接続するトークン、Discordなどのチャネル認証は別のものです。別の接続のキーを更新しても、元のエラーは直りません。

APIキーが設定済みなのに失敗する場合も、すぐに再発行する必要はありません。別のエージェントを見ていた、Gatewayの実行ユーザーに設定が届いていない、セッションが別のモデルを選んでいる、SecretRefの参照先が使えない、といった条件を先に区別できます。以下は2026年10月7日に確認したOpenClaw公式ドキュメントに基づく手順です。掲載する復旧判断のコードは架空の入力でオフライン確認しており、実機のキー認証や有料モデル呼び出しを実証するものではありません。

エラーを見たら、まずどの接続が失敗したかを確認する

最初の失敗について、時刻、エラー本文、呼び出した機能、実際の接続先を控えます。APIキーの値を記録する必要はありません。リトライ後の最終エラーだけでは、最初の認証失敗と、その後の待機状態が混ざることがあります。

HTTPコード、モデル名のプレフィックス、リクエストIDの形式だけでは、どの接続が失敗したかを確定できません。接続先と本文を合わせます。公式の認証説明でも、モデル提供元への認証とGateway認証は分けて扱われています。

APIキーを設定したのにNo API Keyになる場合

確認する順序は「実際のモデル → 実行環境 → 認証元」です。存在するキーを別の場所へむやみにコピーする前に、次の三点を揃えます。

1. 実際のセッションを確認します。 対象チャットの/model statusと/statusで、選択したモデルと、フォールバック後に動いているモデルを区別します。通常のCLIのモデル状態は既定・フォールバック設定を調べるため、チャットの上書きと一致するとは限りません。
2. 対象のエージェントとホストを揃えます。 端末のシェルで設定したキーが、別ユーザーのGatewayやDocker内のプロセスでも使えるとは限りません。エージェントを明示した状態確認では、たとえばopenclaw models status --agent <agentId> --jsonを使えます。
3. 認証元の種類と状態を確認します。 auth.providersは認証元、auth.oauthは保存済みプロファイルの状態、auth.modelRouteIssuesはモデル経路上の問題、auth.runtimeAuthRoutesは別ランタイムの利用可否を確認する入口です。SecretRefが見つかっても解決できない状態と、提供元にキーを拒否された状態は違います。

これらの状態確認は--probeなしでも対象のシークレット解決や提供元が管理する状態の確認を行う場合があります。完全なオフライン操作とは言えません。また、失敗時には通常の状態オブジェクトではなくエラーオブジェクトが返ることがあるため、終了コードと本文を合わせて読みます。モデルCLIの説明を使用中の版と照合してください。

キーが本当に欠けている場合の修正

対象のGatewayホストで、対象エージェントとプロバイダーを明示して、公式の認証ヘルパーから認証情報を登録します。APIキーならmodels auth paste-api-key、対話型の方式選択ならmodels auth addが入口です。複数エージェント環境では対象を明示し、プロファイルを指定する場合は意図したプロファイルが選ばれるかも確認します。キーをチャットやログへ貼り付ける手順にはしません。

認証方式も一致させます。OpenAIのAPIキーとChatGPT/Codex OAuthは、現在は同じopenaiプロバイダーとして扱われますが、同じログイン方式ではありません。OpenAIのログインはChatGPT/Codexが既定なので、APIキーを使う場合は対応するapi-key方式を選びます。paste-tokenもAPIキー登録とは別です。認証ヘルパーの説明を確認します。

Anthropicでも、APIキー、管理されたsetup-token、ネイティブClaude CLIのログインを区別します。常時稼働のGatewayホストでは、公式資料はAPIキーを運用方針が明確な選択肢として説明しています。一方、ネイティブCLIを使う構成は、同じホスト・ユーザー・PATH・CLAUDE_CONFIG_DIRと、対応するCLIバックエンドの選択が必要です。OpenClawがClaudeのネイティブログイントークンを読み出して保存・更新・転送する構成ではありません。モデル名だけでサブスクリプション扱いや無料枠を判断しないでください。認証方式の条件に沿って、失敗した方式を直します。

保存済みプロファイルがある場合の修正

現在の資格情報は共有の~/.openclaw/state/openclaw.sqliteと、エージェントのローカル状態で管理されます。ローカルに同じIDのプロファイルがあると共有側を上書きし、認証順序から除外されたプロファイルも選ばれません。エージェントごとにすべてのキーをコピーする必要がある、と判断するのは早計です。

古いauth-profiles.jsonなどは現在の実行用資格情報ファイルではありません。移行対象・保存先・優先順位の問題を確認してから、バックアップを取って該当する移行を行います。SQLiteの直接編集や、古い履歴の削除を最初の修正にしないでください。現在の保存先と移行の説明が判断の根拠になります。

また、models.providers.<id>に置く接続先baseUrl、API方式、モデルID、ヘッダー、タイムアウトと、認証プロファイルは役割が異なります。認証行に接続先を足して直そうとせず、失敗した接続の設定をそれぞれ確認します。

401はエラー本文を読んでから修正する

モデル提供元がキー・トークンの失効や不一致を明示したら、その認証方式を対象ホストで更新します。送信時に必要な認証が欠けている場合は、選択されたプロファイルと実際の接続設定を修正します。課金・利用権限を理由にした401・403は、認証情報を更新するだけでは解決しない場合があります。理由を区別し、提供元の該当設定へ進みます。

一方、Gatewayへ送ったリクエストの401では、Gatewayの認証を確認します。たとえば共有トークン・パスワード方式のOpenResponses HTTP APIは、Authorization: Bearer <Gatewayの認証情報>を使います。ここへモデル提供元のAPIキーを入れると、別の認証情報を渡すことになります。trusted-proxy方式では別の本人確認ルールが適用されます。OpenResponses HTTP APIの認証モードを確認してください。

共有トークン・パスワード方式のHTTP接続には広いoperator権限があります。認証情報を読み取り専用のキーとみなして共有しないでください。本人確認を伴う方式では、承認されたスコープも確認します。

HTTPのResponsesエンドポイントは既定では無効です。404は無効な入口やパスの問題かもしれず、上流のAPIキーが無効だとは判断できません。モデル一覧を取得できた場合も、上流のモデルを実行できた証明にはなりません。

Gateway・端末・チャネルのエラーをAPIキーと分ける

接続時の詳細があれば、次のように修正先を選べます。

共有トークンが合っていても、Control UIの端末本人確認を代替できるとは限りません。WSの1008も、ポリシーと詳細によって理由が変わります。認証を無効にする、権限を広げる、待機制限を避けるためにIPやOriginを変える、といった修正を行う必要はありません。Gateway・Control UIの対処に沿って必要な認証・承認を確認します。

gateway statusの接続・認証ハンドシェイク成功は、モデル呼び出しや書き込み権限の成功を意味しません。--require-rpcは読み取りスコープを確認し、--no-probeはサービスのみを確認します。明示した--urlには明示した資格情報が必要で、設定・環境の資格情報へ自動で戻りません。サービスの実行ユーザー、設定パス、CLIが調べたホストが同じかを確認します。Gateway状態確認の意味が役立ちます。

DiscordやTelegramなどで無反応になった場合は、受信したか、チャネルの認証・ポリシーが受け入れたか、エージェント処理が始まったか、モデル処理に進んだかを順に区別します。受信されなかったメッセージや、ポリシーで無視されたメッセージに対してLLMキーを交換しても、対処先が違います。

429とcooldown：待つ場所と止める条件を決める

Gateway入口の429と、モデル提供元の429を区別します。 GatewayのOpenResponses HTTP APIでは、認証失敗の試行制限が429とRetry-Afterを返すことがあります。この場合は誤ったGateway認証を直し、制限時間が過ぎるのを待ちます。上流のモデルキーやモデルを切り替えても、入口の制限は解除されません。HTTP APIのエラー仕様に記載されています。

モデル提供元の429では、その提供元の待機指示と、OpenClawの実行中のリトライを確認します。現在の組み込みモデル実行は429で最大10回の総試行、その他の一時的なエラーで最大8回の再試行と90秒の連続障害時間を扱います。完全なモデル応答で連続障害時間は解消されますが、部分応答やツール動作だけでは解消されません。既に実行中のリトライに、アプリ側で会話全体を繰り返すループを重ねないでください。retry.provider.maxRetriesは組み込みセッション設定であり、openclaw.jsonに追加する汎用設定キーではありません。リトライの仕様を確認します。

通常のバックオフ上限より長い提供元の待機指示がある場合も、その最低待機時間を守ります。Retry-Afterは非負の整数秒またはHTTP-dateで、OpenClawではミリ秒のRetryAfterMsなども扱います。待機時間が対話処理の残り時間を超えるなら、延期・キュー待ちにするか、既に承認されたフォールバックの条件を確認します。短い値へ切り詰めて再送してはいけません。HTTPの定義も根拠になります。

保存済みのcooldownは、提供元の一律のリセット時刻ではありません。モデル単位の制限と、課金・恒久的認証エラーによるプロファイル全体の無効化は扱いが違います。再起動や入金をしても、保存済み状態がすぐ消えるとは限りません。モデルフェイルオーバーで対象の状態を確認します。複数キーの設定も、共有される利用枠を増やす仕組みではありません。

フォールバック先を使う条件は、タスクに必要な機能、データの取り扱い、認証、費用、再実行の安全性が揃っていることです。明示的に選んだセッションのモデルや、フォールバックを持たないエージェントの主モデルは厳格に扱われます。同じプロバイダー内で一時的に別の適格プロファイルが選ばれても、選択したモデルの制約は緩みません。ユーザーが固定した認証プロファイルは、resetやcompactでも保持されます。一時的な同じプロバイダー内の切り替えで、この指定が恒久的に置き換わるわけではありません。フォールバックで応答したモデルはそのターンの実行モデルで、次のターンは選択モデルから再開するため、/statusで選択と実行を区別します。

400・コンテキスト超過・ツールの問題

400はリクエスト本文・モデルのパラメーター・コンテキスト長など、実際の本文の理由から対処します。コンテキスト超過なら、完了済みの結果と未完了の作業を保存して、読み込まれた上限を確認し、会話の圧縮や不要な入力の削減を選びます。キー更新や同じ長い入力の即時再送では改善しません。ローカルの形式・履歴保存エラーを、正常なモデル資格情報のcooldown原因と取り違えないことも大切です。モデルフェイルオーバーの分類を参照します。

GatewayへのSSE接続ができても、その後にresponse.failedが届く場合があります。要求されたクライアントツールの構造化結果が返らず、Gateway側の契約不一致で502となる場合もあります。「接続した」「HTTPヘッダーが返った」だけで処理完了とはせず、最終結果とツールの実行記録を確認します。ストレージ、プラグイン、ランタイム、ツール定義の問題は、それぞれのエラーに沿って修正します。エージェント応答の対処が確認先です。

Docker・SecretRef・TLSで先に見る設定

ホストのシェルで設定できていても、動作中のGatewayがその値を使っているとは限りません。環境変数は既存プロセス値を通常は上書きせず、作業ディレクトリの.envは提供元の資格情報を読み込む汎用入口ではありません。グローバルな状態ディレクトリの.env、設定の環境値、サービスが所有する環境値にもそれぞれ条件があります。キーの有無と参照元を確認し、env全体やキー値をサポート用ログへ出さないでください。環境変数の優先関係に従います。

Docker Composeの環境値を変更した場合は、コンテナの再作成で反映します。restartだけでは新しい環境値を取り込みません。公式手順のup -dを使う場面でも、先に処理中の作業を整理し、永続ボリュームを維持します。ボリューム削除や権限の一括変更は必要な前提ではありません。Dockerの環境変数を確認します。

SecretRefを明示している場合は、その参照が失敗した理由を修正します。対象パスでは有効な参照が平文に優先し、保存済み認証プロファイルが設定側の参照を隠す場合もあります。構成した参照先が利用不能なら、環境キーへ迂回して認証するとは限りません。読み取り専用の状態表示が古い準備済み状態を使えても、実際の送信認証は厳格に扱われます。参照元の復旧後、管理者が承認した再読み込みで反映します。Secrets運用の説明が根拠です。

TLSエラーでは証明書チェーン、信頼されたCA、実際の接続先を調べます。NODE_TLS_REJECT_UNAUTHORIZED=0で証明書検証を止めてAPIキー問題を直す方法は使いません。管理者が正当なCAを追加する場合、NodeのNODE_EXTRA_CA_CERTSはプロセス開始時に読み込まれます。後から環境値を変更しただけでは反映されず、クライアントがcaを明示した構成では既定・追加CAが使われません。NodeのCA設定を使用中の環境と照合します。

設定の構造が疑わしい場合は、openclaw config fileで実際のファイルを確認し、該当するスキーマとopenclaw config validateの結果を見ます。構造検証は提供元の認証受理や全パラメーターの有効性を確認するものではありません。Doctorの修復は具体的な移行・構造上の指摘とバックアップがある場合に選びます。正常な認証を作り出したり、利用枠を増やしたりする機能ではありません。設定CLIを参照してください。

本番の復旧は、完了した作業を残して判断する

タイムアウトしたからといって「処理されていない」「課金されていない」とは判断できません。外部メッセージの送信やファイル更新が完了した後で、最終応答だけが失われた可能性があります。復旧前に処理ID、完了済みの操作、未完了の作業、失敗したモデル呼び出しを分けます。POSTを同じ内容・同じジョブIDで送るだけでは、提供元が重複処理しない保証になりません。HTTPの再実行条件に沿って確認します。

次のPython例は、アプリ側で管理するモデル呼び出しの、失敗後の判断だけを行います。通信・待機・認証変更・フォールバックの実行は行いません。アプリが接続先とエラー本文を確認し、issuerとkindへ分類済みの結果を渡す前提です。HTTPコードだけを自動分類していません。入力のattemptsは既に開始した試行数、nowとdeadlineは秒単位の時刻です。

from datetime import timezone
from email.utils import parsedate_to_datetime
import math


def retry_floor(headers, now):
    # headersは大文字小文字を正規化済みの入力とします。
    floors = []
    value = headers.get("retry-after")
    if value is not None:
        text = str(value).strip()
        if text.isascii() and text.isdigit():
            floors.append(float(text))
        else:
            try:
                stamp = parsedate_to_datetime(text)
                if stamp.tzinfo is None:
                    stamp = stamp.replace(tzinfo=timezone.utc)
                floors.append(max(0.0, stamp.timestamp() - now))
            except (ValueError, TypeError, OverflowError):
                return None  # 不正な待機指示で即時再送しません。
    value_ms = headers.get("retry-after-ms")
    if value_ms is not None:
        try:
            milliseconds = float(value_ms)
            if not math.isfinite(milliseconds) or milliseconds < 0:
                return None
            floors.append(milliseconds / 1000)
        except (ValueError, TypeError):
            return None
    return max(floors, default=0.0)


def next_step(error, state):
    if state["cancelled"] or state["now"] >= state["deadline"]:
        return {"action": "stop", "reason": "cancelled_or_deadline"}
    if state["completed_actions"] or state["outcome_unknown"]:
        return {"action": "reconcile", "reason": "preserve_completed_work"}
    if state["runtime_manages_retry"]:
        return {"action": "observe", "reason": "do_not_stack_retry_loops"}
    if error["issuer"] != "provider":
        return {"action": "repair_origin", "reason": error["issuer"]}
    if error["kind"] in {"auth", "billing", "context", "format", "refusal"}:
        return {"action": "stop_and_fix", "reason": error["kind"]}
    if error["kind"] not in {"rate", "transient"}:
        return {"action": "inspect", "reason": "unclassified_error"}
    if not state["replay_safe"]:
        return {"action": "reconcile", "reason": "replay_not_confirmed"}
    if state["attempts"] >= state["max_attempts"]:
        return {"action": "stop", "reason": "attempt_budget"}
    floor = retry_floor(error["headers"], state["now"])
    if floor is None:
        return {"action": "inspect", "reason": "invalid_retry_header"}
    # この例独自の待機方針。OpenClawの内蔵設定ではありません。
    delay = max(floor, min(8.0, 2.0 ** (state["attempts"] - 1)))
    if state["now"] + delay >= state["deadline"]:
        return {"action": "defer", "reason": "wait_exceeds_budget",
                "minimum_wait_seconds": delay}
    return {"action": "retry_failed_call", "wait_seconds": delay,
            "remaining_starts": state["max_attempts"] - state["attempts"]}


if __name__ == "__main__":
    error = {"issuer": "provider", "kind": "rate", "status": 429,
             "headers": {"retry-after": "45"}}
    state = {"now": 1000.0, "deadline": 1020.0,
             "attempts": 1, "max_attempts": 3, "cancelled": False,
             "completed_actions": [], "outcome_unknown": False,
             "runtime_manages_retry": False, "replay_safe": True}
    print(next_step(error, state))

この入力ではdeferと最低45秒の待機が返ります。20秒の残り時間に合わせて45秒を短縮して再送することはありません。completed_actionsに完了した送信などがあればreconcileとなり、会話全体の再実行より先に既存結果を照合します。分類済みの認証エラーはstop_and_fix、Gatewayの429はrepair_originです。上限に達した最後の試行では、待機指示を作りません。

実際のアプリでは、判断後の待機・キャンセル・送信開始を同じ管理単位で扱い、待機終了時にも期限を再確認します。ここで返すremaining_startsはアプリ側の上限であり、SDKやOpenClaw内部の試行数・料金上限を保証しません。フォールバックを使う場合も、承認済みの接続と再実行可能な未完了処理だけを対象にします。

修正できたかは、同じ接続の最終結果で確認する

修正後は、元のエージェント・セッション・選択モデル・実行ホスト・認証方式を揃え、未完了の処理だけを小さく再確認します。外部操作を伴わない短いモデル処理で最終応答が完了したことと、選択モデルから別モデルへ切り替わったかを記録します。別の接続先でモデル一覧が取れた、Gatewayの/healthzが成功した、設定が検証を通った、という結果だけでは元のモデル呼び出しを検証できません。

models status --checkの終了コード0も、認識済みの認証・経路・ランタイム・期限の問題が検出されなかったという意味です。1は欠落・期限切れ・非互換・利用不能・不確定などを含み、2は他の問題なしで期限が近い場合です。モデルの実行成功とは分けてください。状態確認の仕様に従います。

実呼び出しの--probeはトークン消費や制限を発生させる可能性があります。公式資料では、稼働中のGatewayと同じ状態ディレクトリを同時に扱わず、保守時間に実行中の処理と終了処理が落ち着いてから実施するよう求めています。実施権限を確認し、対象のプロバイダー・プロファイル・時間・並列数・トークンを絞ります。既定値を費用上限の保証にせず、タイムアウト後も残った処理を確認してからGatewayを復帰させます。このページのオフライン例は、この実呼び出しを実施した結果ではありません。

よくある疑問

キーの先頭がsk-なら有効ですか？

先頭の形式だけでは有効性を確認できません。実際の提供元、認証方式、接続先、失効状態を確認します。Gatewayトークンや別の提供元のキーを、同じ形式の文字列として扱わないでください。

再起動するとcooldownは消えますか？

保存済み状態は再起動で必ず消えるものではありません。提供元が指定した最低待機時間と、OpenClawが保存したモデル・プロファイルの状態を分けて確認します。入金やプラン変更だけで即時復旧する保証もありません。フェイルオーバーの説明が確認先です。

設定を削除して最初からやり直すべきですか？

最初の対処にはしません。対象ホスト、エージェント、認証順序、参照元を特定し、問題のある箇所を修正します。資格情報のローカル削除は提供元での失効処理とは別で、稼働中のGatewayから認証を削除すると該当処理が中断される場合もあります。認証運用の条件を確認します。

モデルを変えれば認証エラーを避けられますか？

Gateway入口の認証や端末権限の問題には効きません。モデル提供元の問題でも、承認済みの利用可能な認証と、必要な機能・データ・費用条件を満たす代替先が必要です。まず失敗した接続を特定し、明示的に選んだモデルの制約と処理の再実行可否を確認します。