Gateway トラブルシューティング

このページは詳細な手順書です。 まず高速トリアージフローが必要な場合は /help/troubleshooting から始めてください。

コマンドラダー

まず以下を順番に実行してください：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

正常時のシグナル：

• openclaw gateway status が Runtime: running と RPC probe: ok を表示。
• openclaw doctor がブロッキングな設定/サービス問題を報告しない。
• openclaw channels status --probe が接続済み/準備完了のチャネルを表示。

Anthropic 429：ロングコンテキストに追加使用量が必要

ログ/エラーに以下が含まれる場合に使用： HTTP 429: rate_limit_error: Extra usage is required for long context requests。

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

確認すべき点：

• 選択された Anthropic Opus/Sonnet モデルで params.context1m: true が設定されている。
• 現在の Anthropic クレデンシャルがロングコンテキスト使用の対象外。
• 1M ベータパスが必要な長いセッション/モデル実行でのみリクエストが失敗。

修正オプション：

1. そのモデルの context1m を無効にして通常のコンテキストウィンドウにフォールバック。
2. 請求対応の Anthropic API キーを使用するか、サブスクリプションアカウントで Anthropic Extra Usage を有効化。
3. Anthropic ロングコンテキストリクエストが拒否された場合に実行を継続するためのフォールバックモデルを設定。

関連：

• /providers/anthropic
• /reference/token-use
• /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic

応答がない

チャネルは稼働しているが何も応答しない場合、再接続の前にルーティングとポリシーを確認してください。

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

確認すべき点：

• DM 送信者のペアリングが保留中。
• グループメンション制御（requireMention、mentionPatterns）。
• チャネル/グループ許可リストの不一致。

一般的なシグネチャ：

• drop guild message (mention required → メンションされるまでグループメッセージは無視。
• pairing request → 送信者の承認が必要。
• blocked / allowlist → 送信者/チャネルがポリシーでフィルタリングされた。

関連：

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

ダッシュボード・コントロール UI の接続問題

ダッシュボード/コントロール UI が接続できない場合、URL、認証モード、セキュアコンテキストの前提条件を検証してください。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

確認すべき点：

• 正しいプローブ URL とダッシュボード URL。
• クライアントと Gateway 間の認証モード/トークンの不一致。
• デバイスアイデンティティが必要な場所での HTTP 使用。

一般的なシグネチャ：

• device identity required → 非セキュアコンテキストまたはデバイス認証なし。
• device nonce required / device nonce mismatch → クライアントがチャレンジベースのデバイス認証フロー（connect.challenge + device.nonce）を完了していない。
• device signature invalid / device signature expired → クライアントが現在のハンドシェイクに対して誤ったペイロード（または古いタイムスタンプ）で署名。
• AUTH_TOKEN_MISMATCH で canRetryWithDeviceToken=true → クライアントはキャッシュされたデバイストークンで1回の信頼済みリトライが可能。
• そのリトライ後も unauthorized が繰り返される → 共有トークン/デバイストークンのドリフト。トークン設定を更新し、必要に応じてデバイストークンを再承認/ローテーション。
• gateway connect failed: → ホスト/ポート/URL ターゲットの誤り。

認証詳細コードのクイックマップ

失敗した connect レスポンスの error.details.code を使って次のアクションを判断してください：

デバイス認証 v2 の移行チェック：

openclaw --version
openclaw doctor
openclaw gateway status

ログに nonce/署名エラーが表示される場合、接続クライアントを更新して以下を確認してください：

1. connect.challenge を待機
2. チャレンジバウンドペイロードに署名
3. connect.params.device.nonce に同じチャレンジ nonce を送信

関連：

• /web/control-ui
• /gateway/authentication
• /gateway/remote
• /cli/devices

Gateway サービスが起動しない

サービスはインストール済みだがプロセスが起動しない場合に使用。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

確認すべき点：

• 終了ヒント付きの Runtime: stopped。
• サービス設定の不一致（Config (cli) vs Config (service)）。
• ポート/リスナーの競合。

一般的なシグネチャ：

• Gateway start blocked: set gateway.mode=local → ローカル Gateway モードが有効になっていない。修正：設定で gateway.mode="local" を設定（または openclaw configure を実行）。Podman で専用 openclaw ユーザーを使って OpenClaw を実行している場合、設定は ~openclaw/.openclaw/openclaw.json にあります。
• refusing to bind gateway ... without auth → 認証なしの非ループバックバインド。
• another gateway instance is already listening / EADDRINUSE → ポート競合。

関連：

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

チャネル接続済みだがメッセージが流れない

チャネルの状態は接続済みだがメッセージフローが停止している場合、ポリシー、権限、チャネル固有の配信ルールに注目してください。

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

確認すべき点：

• DM ポリシー（pairing、allowlist、open、disabled）。
• グループ許可リストとメンション要件。
• チャネル API の権限/スコープ不足。

一般的なシグネチャ：

• mention required → グループメンションポリシーでメッセージが無視された。
• pairing / 保留承認トレース → 送信者が未承認。
• missing_scope、not_in_channel、Forbidden、401/403 → チャネル認証/権限の問題。

関連：

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

Cron およびハートビート配信

Cron やハートビートが実行されない、または配信されない場合、まずスケジューラの状態を確認し、次に配信先を確認してください。

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

確認すべき点：

• Cron が有効で次回のウェイクが設定されている。
• ジョブ実行履歴のステータス（ok、skipped、error）。
• ハートビートのスキップ理由（quiet-hours、requests-in-flight、alerts-disabled）。

一般的なシグネチャ：

• cron: scheduler disabled; jobs will not run automatically → Cron が無効。
• cron: timer tick failed → スケジューラーのティックが失敗。ファイル/ログ/ランタイムエラーを確認。
• heartbeat skipped で reason=quiet-hours → アクティブ時間ウィンドウ外。
• heartbeat: unknown accountId → ハートビート配信先の無効なアカウント ID。
• heartbeat skipped で reason=dm-blocked → ハートビートターゲットが DM スタイルの配信先に解決されたが、agents.defaults.heartbeat.directPolicy（またはエージェントごとのオーバーライド）が block に設定されている。

関連：

• /automation/troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

ペアリング済みノードのツールが失敗する

ノードはペアリング済みだがツールが失敗する場合、フォアグラウンド状態、権限、承認状態を分離してください。

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

確認すべき点：

• ノードが期待されるケイパビリティでオンライン。
• カメラ/マイク/位置情報/画面の OS 権限付与。
• exec 承認と許可リストの状態。

一般的なシグネチャ：

• NODE_BACKGROUND_UNAVAILABLE → ノードアプリがフォアグラウンドである必要がある。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → OS 権限なし。
• SYSTEM_RUN_DENIED: approval required → exec 承認が保留中。
• SYSTEM_RUN_DENIED: allowlist miss → コマンドが許可リストでブロックされた。

関連：

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

ブラウザツールが失敗する

Gateway 自体は正常だがブラウザツールのアクションが失敗する場合に使用。

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

確認すべき点：

• 有効なブラウザ実行可能ファイルのパス。
• CDP プロファイルの到達性。
• profile="chrome" の場合の拡張機能リレータブのアタッチメント。

一般的なシグネチャ：

• Failed to start Chrome CDP on port → ブラウザプロセスの起動失敗。
• browser.executablePath not found → 設定されたパスが無効。
• Chrome extension relay is running, but no tab is connected → 拡張機能リレーが未アタッチ。
• Browser attachOnly is enabled ... not reachable → attach-only プロファイルに到達可能なターゲットがない。

関連：

• /tools/browser-linux-troubleshooting
• /tools/chrome-extension
• /tools/browser

アップグレード後に突然壊れた場合

アップグレード後の問題のほとんどは、設定のドリフトまたは以前は許容されていたが現在は厳密化されたデフォルト値が原因です。

1) 認証と URL オーバーライドの動作変更

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

確認すべき点：

• gateway.mode=remote の場合、CLI コールがリモートをターゲットしている可能性がある一方、ローカルサービスは正常。
• --url 付きの明示的コールは保存された認証情報にフォールバックしない。

一般的なシグネチャ：

• gateway connect failed: → URL ターゲットの誤り。
• unauthorized → エンドポイントには到達するが認証が不正。

2) バインドと認証のガードレールが厳密化

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

確認すべき点：

• 非ループバックバインド（lan、tailnet、custom）では認証設定が必要。
• 古いキー gateway.token は gateway.auth.token を置き換えない。

一般的なシグネチャ：

• refusing to bind gateway ... without auth → バインドと認証の不一致。
• RPC probe: failed でランタイムは実行中 → Gateway は稼働しているが現在の認証/URL でアクセスできない。

3) ペアリングとデバイスアイデンティティの状態変更

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

確認すべき点：

• ダッシュボード/ノードの保留中のデバイス承認。
• ポリシーまたはアイデンティティ変更後の保留中の DM ペアリング承認。

一般的なシグネチャ：

• device identity required → デバイス認証が満たされていない。
• pairing required → 送信者/デバイスの承認が必要。

チェック後もサービス設定とランタイムが一致しない場合は、同じプロファイル/ステートディレクトリからサービスメタデータを再インストールしてください：

openclaw gateway install --force
openclaw gateway restart

関連：

• /gateway/pairing
• /gateway/authentication
• /gateway/background-process