Gatewayのトラブルシューティング
このページは詳細ランブックです。 まず素早いトリアージフローを確認したい場合は、/help/troubleshootingから始めてください。コマンドの段階的確認
まず次をこの順序で実行してください:openclaw gateway statusにRuntime: runningとRPC probe: okが表示される。openclaw doctorが、設定/サービスに関するブロッキングな問題なしと報告する。openclaw channels status --probeに、アカウントごとのライブ転送状態と、サポートされる場合はworksやaudit okなどのprobe/audit結果が表示される。
長いコンテキストでAnthropic 429のextra usageが必要
ログ/エラーに次が含まれる場合はこれを使用します:HTTP 429: rate_limit_error: Extra usage is required for long context requests.
- 選択されたAnthropic Opus/Sonnetモデルに
params.context1m: trueがある。 - 現在のAnthropic認証情報が長いコンテキスト利用の対象になっていない。
- リクエストが失敗するのは、1Mベータパスが必要な長いセッション/モデル実行時のみ。
- そのモデルの
context1mを無効にして、通常のコンテキストウィンドウにフォールバックする。 - 課金付きのAnthropic APIキーを使うか、Anthropic OAuth/subscriptionアカウントでAnthropic Extra Usageを有効にする。
- Anthropicの長いコンテキストリクエストが拒否されたときに実行が継続するよう、フォールバックモデルを設定する。
- /providers/anthropic
- /reference/token-use
- /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic
応答がない
channelsは稼働しているのに何も応答しない場合、何かを再接続する前にルーティングとポリシーを確認してください。- DM送信者のペアリングが保留中。
- グループでのメンション制御（
requireMention、mentionPatterns）。 - channel/group allowlistの不一致。
drop guild message (mention required→ メンションがあるまでグループメッセージは無視される。pairing request→ 送信者には承認が必要。blocked/allowlist→ 送信者/channelがポリシーでフィルタリングされた。
Dashboard control ui接続
dashboard/control UIが接続しない場合、URL、認証モード、およびセキュアコンテキスト前提を検証してください。- 正しいprobe URLとdashboard URL。
- クライアントとgatewayの間で認証モード/トークンが一致している。
- デバイスIDが必要な場面でHTTPを使っている。
device identity required→ 非セキュアコンテキスト、またはデバイス認証不足。origin not allowed→ ブラウザーのOriginがgateway.controlUi.allowedOriginsに入っていない （または、明示的なallowlistなしで非loopbackのブラウザーoriginから接続している）。device nonce required/device nonce mismatch→ クライアントがチャレンジベースのデバイス認証フロー（connect.challenge+device.nonce）を完了していない。device signature invalid/device signature expired→ クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）に署名した。AUTH_TOKEN_MISMATCHとcanRetryWithDeviceToken=true→ クライアントはキャッシュ済みデバイストークンで信頼済みの1回の再試行が可能。- そのキャッシュトークン再試行では、ペアリング済みデバイストークンとともに保存されたキャッシュ済みスコープ集合を再利用する。明示的な
deviceToken/ 明示的なscopes呼び出し元は、要求したスコープ集合を保持する。 - その再試行パス以外では、接続認証の優先順位は、明示的な共有
token/passwordが先、次に明示的な
deviceToken、次に保存済みデバイストークン、次にbootstrap token。 - 非同期のTailscale Serve Control UIパスでは、同じ
{scope, ip}に対する失敗した試行は、limiterが失敗を記録する前に直列化される。そのため、同じクライアントからの2つの不正な同時再試行では、2回とも単純な不一致ではなく、2回目でretry laterが出ることがある。 - ブラウザーoriginのloopbackクライアントからの
too many failed authentication attempts (retry later)→ その同じ正規化されたOriginからの繰り返し失敗は一時的にロックアウトされる。別のlocalhost originは別バケットを使う。 - その再試行後も繰り返し
unauthorized→ 共有トークン/デバイストークンのドリフト。トークン設定を更新し、必要ならデバイストークンを再承認/ローテーションする。 gateway connect failed:→ ホスト/ポート/urlターゲットが誤っている。
認証詳細コードのクイックマップ
失敗したconnectレスポンスのerror.details.codeを使って次の対応を選んでください:
| Detail code | 意味 | 推奨対応 |
|---|---|---|
AUTH_TOKEN_MISSING | クライアントが必要な共有トークンを送信しなかった。 | クライアントにトークンを貼り付け/設定して再試行してください。dashboardパスでは: openclaw config get gateway.auth.tokenを実行して、Control UI設定に貼り付けます。 |
AUTH_TOKEN_MISMATCH | 共有トークンがgateway認証トークンと一致しなかった。 | canRetryWithDeviceToken=trueなら、信頼済みの1回の再試行を許可してください。キャッシュトークン再試行は保存済みの承認済みスコープを再利用します。明示的なdeviceToken / scopes呼び出し元は要求したスコープを保持します。まだ失敗する場合は、token drift recovery checklistを実行してください。 |
AUTH_DEVICE_TOKEN_MISMATCH | キャッシュ済みのデバイスごとのトークンが古いか失効している。 | devices CLIを使ってデバイストークンをローテーション/再承認し、その後再接続してください。 |
PAIRING_REQUIRED | デバイスIDは認識されているが、このロールでは承認されていない。 | 保留中の要求を承認します: openclaw devices listの後にopenclaw devices approve <requestId>。 |
connect.challengeを待つ- チャレンジに束縛されたペイロードに署名する
- 同じチャレンジnonceとともに
connect.params.device.nonceを送る
openclaw devices rotate / revoke / removeが予期せず拒否される場合:
- ペアリング済みデバイストークンのセッションは、呼び出し元が
operator.adminも持っていない限り、自分自身のデバイスしか管理できない openclaw devices rotate --scope ...は、呼び出し元セッションがすでに保持しているoperatorスコープしか要求できない
- /web/control-ui
- /gateway/configuration（gateway認証モード）
- /gateway/trusted-proxy-auth
- /gateway/remote
- /cli/devices
Gatewayサービスが動作していない
サービスはインストールされているが、プロセスが起動したままにならない場合に使用します。- 終了ヒント付きの
Runtime: stopped。 - サービス設定の不一致（
Config (cli)対Config (service)）。 - ポート/listener競合。
--deep使用時の追加のlaunchd/systemd/schtasksインストール。Other gateway-like services detected (best effort)のクリーンアップヒント。
Gateway start blocked: set gateway.mode=localまたはexisting config is missing gateway.mode→ local gateway modeが有効でないか、設定ファイルが壊れてgateway.modeが失われた。修正: 設定でgateway.mode="local"を設定するか、openclaw onboard --mode local/openclaw setupを再実行して期待されるlocal-mode設定を書き戻す。OpenClawをPodman経由で実行している場合、デフォルトの設定パスは~/.openclaw/openclaw.json。refusing to bind gateway ... without auth→ 有効なgateway認証パス（token/password、または設定済みのtrusted-proxy）がない非loopback bind。another gateway instance is already listening/EADDRINUSE→ ポート競合。Other gateway-like services detected (best effort)→ 古い、または並行するlaunchd/systemd/schtasksユニットが存在する。ほとんどの構成では、1台のマシンにつき1つのgatewayにするべきです。複数必要な場合は、ポート + config/state/workspaceを分離してください。/gateway#multiple-gateways-same-hostを参照してください。
Gateway probe警告
openclaw gateway probeが何かに到達しているのに、警告ブロックも表示される場合に使用します。
- JSON出力の
warnings[].codeとprimaryTargetId。 - 警告がSSHフォールバック、複数gateway、スコープ不足、または未解決認証refに関するものか。
SSH tunnel failed to start; falling back to direct probes.→ SSHセットアップが失敗したが、コマンドは引き続き構成済み/loopbackターゲットへの直接probeを試した。multiple reachable gateways detected→ 複数のターゲットが応答した。通常、これは意図的なマルチgateway構成か、古い/重複listenerを意味する。Probe diagnostics are limited by gateway scopes (missing operator.read)→ 接続は成功したが、詳細RPCはスコープ制限されている。デバイスIDをペアリングするか、operator.read付き認証情報を使用する。- 未解決の
gateway.auth.*/gateway.remote.*SecretRef警告テキスト → 失敗したターゲットに対して、このコマンドパスでは認証情報が利用できなかった。
Channelは接続済みだがメッセージが流れない
channel状態は接続済みなのにメッセージフローが止まっている場合、ポリシー、権限、channel固有の配信ルールに集中してください。- DMポリシー（
pairing、allowlist、open、disabled）。 - グループallowlistとメンション要件。
- channel APIの権限/スコープ不足。
mention required→ グループメンションポリシーによりメッセージが無視される。pairing/ 保留中の承認トレース → 送信者が承認されていない。missing_scope,not_in_channel,Forbidden,401/403→ channel認証/権限の問題。
Cronとheartbeatの配信
cronやheartbeatが実行されなかった、または配信されなかった場合、まずスケジューラー状態を確認し、その後配信先を確認してください。- cronが有効で、次回wakeが存在する。
- ジョブ実行履歴ステータス（
ok、skipped、error）。 - heartbeatスキップ理由（
quiet-hours、requests-in-flight、alerts-disabled、empty-heartbeat-file、no-tasks-due）。
cron: scheduler disabled; jobs will not run automatically→ cronが無効。cron: timer tick failed→ スケジューラーのtick失敗。ファイル/ログ/ランタイムエラーを確認してください。heartbeat skippedでreason=quiet-hours→ アクティブ時間帯の外。heartbeat skippedでreason=empty-heartbeat-file→HEARTBEAT.mdは存在するが、空行 / markdownヘッダーしか含まれていないため、OpenClawはモデル呼び出しをスキップする。heartbeat skippedでreason=no-tasks-due→HEARTBEAT.mdにtasks:ブロックはあるが、このtick時点ではどのタスクも期限になっていない。heartbeat: unknown accountId→ heartbeat配信先のaccount idが無効。heartbeat skippedでreason=dm-blocked→ heartbeatターゲットがDM形式の宛先に解決されたが、agents.defaults.heartbeat.directPolicy（またはagentごとの上書き）がblockに設定されている。
Nodeはペアリング済みだがtoolが失敗する
nodeがペアリング済みなのにtoolが失敗する場合、フォアグラウンド、権限、承認状態を切り分けてください。- nodeがオンラインで、期待される機能を持っている。
- カメラ/マイク/位置情報/画面に対するOS権限が付与されている。
- exec承認とallowlist状態。
NODE_BACKGROUND_UNAVAILABLE→ node appはフォアグラウンドにある必要がある。*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ OS権限不足。SYSTEM_RUN_DENIED: approval required→ exec承認が保留中。SYSTEM_RUN_DENIED: allowlist miss→ コマンドがallowlistでブロックされた。
Browser toolが失敗する
gateway自体は正常なのにbrowser toolの操作が失敗する場合に使用します。plugins.allowが設定されており、browserを含んでいるか。- 有効なブラウザー実行ファイルパス。
- CDPプロファイルへの到達可能性。
existing-session/userプロファイル向けのローカルChromeの可用性。
unknown command "browser"またはunknown command 'browser'→ バンドル済みbrowser pluginがplugins.allowにより除外されている。browser.enabled=trueなのにbrowser toolがない / 利用不可 →plugins.allowがbrowserを除外しているため、pluginが読み込まれていない。Failed to start Chrome CDP on port→ ブラウザープロセスの起動に失敗した。browser.executablePath not found→ 設定されたパスが無効。browser.cdpUrl must be http(s) or ws(s)→ 設定されたCDP URLがfile:やftp:のような未対応スキームを使っている。browser.cdpUrl has invalid port→ 設定されたCDP URLのポートが不正または範囲外。No Chrome tabs found for profile="user"→ Chrome MCPアタッチプロファイルにローカルのChromeタブが開かれていない。Remote CDP for profile "<name>" is not reachable→ 設定されたリモートCDPエンドポイントにgateway hostから到達できない。Browser attachOnly is enabled ... not reachableまたはBrowser attachOnly is enabled and CDP websocket ... is not reachable→ attach-onlyプロファイルに到達可能なターゲットがない、またはHTTPエンドポイントは応答したがCDP WebSocketを開けなかった。Playwright is not available in this gateway build; '<feature>' is unsupported.→ 現在のgatewayインストールに完全なPlaywrightパッケージがない。ARIAスナップショットと基本的なページスクリーンショットは引き続き動作するが、ナビゲーション、AIスナップショット、CSSセレクターによる要素スクリーンショット、PDFエクスポートは引き続き利用不可。fullPage is not supported for element screenshots→ スクリーンショット要求で--full-pageと--refまたは--elementを混在させている。element screenshots are not supported for existing-session profiles; use ref from snapshot.→ Chrome MCP /existing-sessionのスクリーンショット呼び出しでは、CSSの--elementではなく、ページキャプチャまたはスナップショットの--refを使う必要がある。existing-session file uploads do not support element selectors; use ref/inputRef.→ Chrome MCPのアップロードフックにはCSSセレクターではなくスナップショットrefが必要。existing-session file uploads currently support one file at a time.→ Chrome MCPプロファイルでは1回の呼び出しにつき1ファイルずつアップロードする。existing-session dialog handling does not support timeoutMs.→ Chrome MCPプロファイル上のダイアログフックではtimeoutの上書きはサポートされない。response body is not supported for existing-session profiles yet.→responsebodyには引き続き管理対象ブラウザーまたは生のCDPプロファイルが必要。- attach-onlyまたはremote CDPプロファイルで古いviewport / dark-mode / locale / offline上書きが残っている →
openclaw browser stop --browser-profile <name>を実行し、ゲートウェイ全体を再起動せずにアクティブな制御セッションを閉じてPlaywright/CDPエミュレーション状態を解放する。
アップグレード後に突然何かが壊れた場合
アップグレード後の障害の多くは、設定ドリフトか、より厳格なデフォルトの適用です。1) 認証とURL上書き動作が変わった
gateway.mode=remoteなら、ローカルサービスが正常でもCLI呼び出しはremoteを対象にしている可能性がある。- 明示的な
--url呼び出しは保存済み認証情報にフォールバックしない。
gateway connect failed:→ URLターゲットが誤っている。unauthorized→ エンドポイントには到達できているが認証が誤っている。
2) Bindと認証のガードレールがより厳格になった
- 非loopback bind（
lan、tailnet、custom）には、有効なgateway認証パスが必要: 共有token/password認証、または正しく設定された非loopbacktrusted-proxyデプロイ。 gateway.tokenのような古いキーはgateway.auth.tokenの代わりにはならない。
refusing to bind gateway ... without auth→ 有効なgateway認証パスがない非loopback bind。RPC probe: failedなのにruntimeはrunning → gatewayは生きているが現在の認証/urlでは到達できない。
3) PairingとデバイスID状態が変わった
- dashboard/nodes向けの保留中デバイス承認。
- ポリシーまたはID変更後の保留中DMペアリング承認。
device identity required→ デバイス認証が満たされていない。pairing required→ 送信者/デバイスには承認が必要。