トラブルシューティング

これは詳細なランブックです。まず /help/troubleshooting の迅速なトリアージフローから開始してください。

コマンドの実行順序

次の順序で実行します。

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

正常性を示すシグナル：

• openclaw gateway status に Runtime: running、Connectivity probe: ok、および Capability: ... 行が表示される。
• openclaw doctor で、処理を妨げる設定やサービスの問題が報告されない。
• openclaw channels status --probe にアカウントごとの現在のトランスポート状態が表示され、対応している場合は works または audit ok が表示される。

更新後

更新が完了したものの、Gateway が停止している、チャネルが空である、またはモデル呼び出しが 401 で失敗する場合に使用します。

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

確認項目：

• openclaw status / openclaw status --all の Update restart。保留中または失敗した引き継ぎには、次に実行するコマンドが含まれます。
• Channels の plugin load failed: dependency tree corrupted; run openclaw doctor --fix：チャネル設定はまだ存在しますが、チャネルを読み込む前に Plugin の登録が失敗しています。
• 再認証後のプロバイダー 401：openclaw doctor --fix は、エージェントごとに残っている古い OAuth 認証のシャドウコピーを確認して削除し、すべてのエージェントが現在の共有プロファイルを解決できるようにします。

分断されたインストールと新しい設定の保護

更新後に Gateway サービスが予期せず停止した場合、またはログで、ある openclaw バイナリが最後に openclaw.json を書き込んだバージョンより古いことが示される場合に使用します。

OpenClaw は設定の書き込み時に meta.lastTouchedVersion を記録します。読み取り専用コマンドは新しい OpenClaw が書き込んだ設定を検査できますが、古いバイナリからのプロセスおよびサービスの変更操作は実行を拒否されます。ブロックされる操作：Gateway サービスの開始、停止、再起動、アンインストール、サービスの強制再インストール、サービスモードでの Gateway 起動、および gateway --force によるポートのクリーンアップ。

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

ロールバック後のプロトコル不一致

ダウングレードまたはロールバック後、ログに protocol mismatch が繰り返し出力される場合に使用します。古い Gateway が動作していますが、新しいローカルクライアントプロセスが、古い Gateway が対応できないプロトコル範囲を使って再接続し続けています。

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

確認項目：

• Gateway ログの protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>。
• openclaw gateway status --deep の Established clients: または openclaw doctor --deep の Gateway clients：Gateway ポートに接続しているアクティブな TCP クライアント。OS が許可する場合は PID とコマンドラインも表示されます。
• コマンドラインが、ロールバック元の新しい OpenClaw インストールまたはラッパーを指しているクライアントプロセス。

修正方法：

1. gateway status --deep に表示された古い OpenClaw クライアントプロセスを停止または再起動します。
2. OpenClaw を組み込んでいるアプリまたはラッパーを再起動します。たとえば、ローカルダッシュボード、エディター、アプリサーバーヘルパー、長時間実行中の openclaw logs --follow シェルなどです。
3. openclaw gateway status --deep または openclaw doctor --deep を再実行し、古いクライアント PID がなくなったことを確認します。

古い Gateway が、互換性のない新しいプロトコルを受け入れるように変更しないでください。プロトコルのバージョン更新は通信規約を保護します。ロールバックからの復旧は、プロセスとバージョンのクリーンアップの問題です。

パス脱出としてスキップされた Skill シンボリックリンク

ログに次の内容が含まれる場合に使用します。

設定されたルート外へ脱出する Skill パスをスキップしています：... reason=symlink-escape

各 Skill ルートは封じ込め境界です。~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills、または ~/.openclaw/skills 配下のシンボリックリンクは、その実際のリンク先がルート外に解決される場合、リンク先が明示的に信頼されていない限りスキップされます。

リンクを調査します。

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

リンク先が意図したものである場合は、直接の Skill ルートと許可するシンボリックリンク先の両方を設定します。

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

その後、新しいセッションを開始するか、Skills ウォッチャーが更新されるまで待ちます。実行中のプロセスが設定変更より前に起動されている場合は、Gateway を再起動します。

~、/、同期対象プロジェクトフォルダー全体など、広範なリンク先を使用しないでください。allowSymlinkTargets の範囲は、信頼された SKILL.md ディレクトリを含む実際の Skill ルートに限定してください。

Skill Workshop の適用時に、信頼されたシンボリックリンク先のワークスペース Skill パスにも書き込む必要がある場合は、skills.workshop.allowSymlinkTargetWrites を有効にします。読み取り専用の共有 Skill ルートでは無効のままにしてください。

関連項目：

• Skills の設定
• 設定例

長いコンテキストに追加利用枠が必要な Anthropic 429

ログまたはエラーに HTTP 429: rate_limit_error: Extra usage is required for long context requests が含まれる場合に使用します。

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

確認項目：

• 選択した Anthropic モデルが一般提供されている 1M 対応の Claude 4.x モデル（Opus 4.6/4.7/4.8、Sonnet 4.6）であるか、モデル設定に従来の params.context1m: true がまだ残っている。
• 現在の Anthropic 認証情報が長いコンテキストの利用対象ではない。
• 1M コンテキスト経路を必要とする長いセッションまたはモデル実行でのみリクエストが失敗する。

修正オプション：

関連項目：

• Anthropic
• トークンの使用量とコスト
• Anthropic から HTTP 429 が返されるのはなぜですか？

アップストリームからの 403 ブロック応答

アップストリームの LLM プロバイダーから Your request was blocked などの一般的な 403 が返される場合に使用します。

これが常に OpenClaw の設定上の問題だと仮定しないでください。この応答は、OpenAI 互換エンドポイントの前段にある CDN、WAF、ボット管理ルール、リバースプロキシなど、アップストリームのセキュリティレイヤーから返される場合があります。

openclaw statusopenclaw gateway statusopenclaw logs --follow

確認項目：

• 同じプロバイダーの複数のモデルが同様に失敗する。
• 通常のプロバイダー API エラーではなく、HTML または一般的なセキュリティメッセージが返される。
• 同じリクエスト時刻に対応するプロバイダー側のセキュリティイベントがある。
• 小さな直接 curl プローブは成功する一方で、通常の SDK 形式のリクエストは失敗する。

WAF/CDN によるブロックを示す証拠がある場合は、まずプロバイダー側のフィルタリングを修正します。OpenClaw が使用する API パスに限定した許可ルールまたはスキップルールを使用し、サイト全体の保護を無効にしないでください。

関連項目：

• OpenAI 互換エンドポイント
• プロバイダー設定
• ログ

ローカルの OpenAI 互換バックエンドへの直接プローブは成功するが、エージェント実行は失敗する

次の場合に使用します。

• curl ... /v1/models が動作する。
• 小さな直接 /v1/chat/completions 呼び出しが動作する。
• OpenClaw のモデル実行が通常のエージェントターンでのみ失敗する。

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

確認項目：

• 小さな直接呼び出しは成功するが、OpenClaw の実行は大きなプロンプトでのみ失敗する。
• 同じプレフィックスなしのモデル ID を使った直接 /v1/chat/completions は動作するにもかかわらず、model_not_found または 404 エラーが発生する。
• messages[].content に文字列を要求するバックエンドエラー。
• OpenAI 互換ローカルバックエンドで断続的に発生する incomplete turn detected ... stopReason=stop payloads=0 警告。
• 大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ発生するバックエンドのクラッシュ。

関連項目：

• 設定
• ローカルモデル
• OpenAI 互換エンドポイント

応答がない

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

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

確認事項:

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

一般的なシグネチャ:

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

関連項目:

• チャンネルのトラブルシューティング
• グループ
• ペアリング

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

ダッシュボード/コントロール UI に接続できない場合は、URL、認証モード、およびセキュアコンテキストに関する前提を検証します。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

確認事項:

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

更新後にローカルブラウザから 127.0.0.1:18789 に接続できない場合は、まずローカルの Gateway サービスを復旧し、ダッシュボードが配信されていることを確認します。

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

curl が OpenClaw の HTML を返す場合、Gateway は動作しており、残っている問題はブラウザキャッシュ、古いディープリンク、または古いタブの状態である可能性があります。http://127.0.0.1:18789 を直接開き、ダッシュボードから移動してください。再起動後もサービスが稼働し続けない場合は、openclaw gateway start を実行し、openclaw gateway status を再確認します。

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

失敗した connect 応答の error.details.code を使用して、次の操作を選択します。

デバイス認証 v2 の移行確認:

openclaw --versionopenclaw doctoropenclaw gateway status

ログに nonce/署名エラーが表示される場合は、接続クライアントを更新し、次のように検証します。

openclaw devices rotate / revoke / remove が予期せず拒否される場合:

• ペアリング済みデバイストークンのセッションは、呼び出し元が operator.admin も持っていない限り、自身のデバイスのみを管理できます。
• openclaw devices rotate --scope ... で要求できるのは、呼び出し元のセッションがすでに保持しているオペレータースコープのみです。

関連項目:

• 設定（Gateway の認証モード）
• コントロール UI
• デバイス
• リモートアクセス
• 信頼済みプロキシ認証

Gateway サービスが実行されていない

サービスはインストールされているものの、プロセスが稼働し続けない場合に使用します。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # システムレベルのサービスもスキャン

確認事項:

• 終了に関するヒントを伴う Runtime: stopped。
• サービス設定の不一致（Config (cli) と Config (service)）。
• ポート/リスナーの競合。
• --deep 使用時に検出される追加の launchd/systemd/schtasks インストール。
• Other gateway-like services detected (best effort) のクリーンアップに関するヒント。

関連項目:

• バックグラウンド実行とプロセスツール
• 設定
• Doctor

macOS の Gateway が応答を停止し、ダッシュボードを操作すると再開する

macOS ホスト上のチャンネル（Telegram、WhatsApp など）が数分から数時間にわたって反応しなくなり、コントロール UI を開く、SSH で接続する、またはその他の方法でホストを操作した瞬間に Gateway が復帰するように見える場合に使用します。確認する頃には Gateway が再び稼働しているため、通常 openclaw status には明らかな症状が表示されません。

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

確認事項:

• ~/.openclaw/logs/stability/ に、error.code が ENETDOWN、ENETUNREACH、EHOSTUNREACH、ECONNREFUSED などの一時的なネットワークコードに設定された *-uncaught_exception.json バンドルが 1 つ以上ある。
• クラッシュのタイムスタンプと一致する、Entering Sleep state due to 'Maintenance Sleep' や en0 driver is slow (msg: WillChangeState to 0) のような pmset -g log の行。Power Nap / Maintenance Sleep は Wi-Fi ドライバーを一時的に状態 0 にします。この時間帯に発生した外向きの connect() は、それ以外では完全なネットワーク接続があるホストでも ENETDOWN で失敗する可能性があります。
• launchctl print の出力に、直近の複数の runs と終了コードとともに state = not running が表示される。特に、クラッシュから次の起動までの間隔が数秒ではなく 1 時間程度の場合。macOS の launchd はクラッシュが短期間に集中した後、文書化されていない再起動保護ゲートを適用します。このゲートにより、対話型ログイン、ダッシュボード接続、launchctl kickstart などの外部トリガーが再有効化するまで、KeepAlive=true が無視されることがあります。

一般的な兆候:

• error.code が ENETDOWN または同種のコードであり、コールスタックが Node の net にある lookupAndConnect / Socket.connect を示す安定性バンドル。OpenClaw 2026.5.26 以降では、これらは無害な一時的ネットワークエラーとして分類されるため、トップレベルの未捕捉ハンドラーまで伝播しなくなりました。古いリリースを使用している場合は、まずアップグレードしてください。
• Control UI に接続するか、ホストへ SSH 接続した瞬間に終了する長い無通信期間。launchd の再起動ゲートを再有効化するのは、ダッシュボードが Gateway に対して行う処理ではなく、ユーザーから見えるアクティビティです。
• ~/Library/Logs/openclaw/gateway.log に対応する received SIG*; shutting down 行がないまま、1 日を通して runs のカウントが増加する。正常なシャットダウンではシグナルがログに記録されますが、一時的なクラッシュでは記録されません。

対処方法:

1. 2026.5.26 より前のリリースを実行している場合は、Gateway をアップグレードします。アップグレード後、以降の ENETDOWN エラーはプロセスを終了させる代わりに警告として記録されます。

2. 常時稼働サーバーとして使用する Mac mini / デスクトップホストでは、メンテナンススリープの動作を減らします:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   これにより、根本にあるドライバーの瞬断は大幅に減少しますが、完全には解消されません。これらのフラグに関係なく、TCP keepalive と mDNS の維持のために、システムが一部のメンテナンススリープを実行する場合があります。

3. launchd によって待機状態にされた将来の連続クラッシュを迅速に検出できるように、稼働監視ウォッチドッグを追加します:

   # 5 分間隔の cron または LaunchAgent に適した、launchd 対応の稼働確認例state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   目的は、再起動ゲートを外部から再有効化することです。macOS では連続クラッシュ後、KeepAlive=true だけでは不十分です。

関連項目:

• macOS プラットフォームの注意事項
• ログ記録
• Doctor

Gateway/node の重複した LaunchAgent による macOS launchd 監視ループ

macOS のインストール環境が数秒ごとに再起動し続け、openclaw のヘルスチェック結果が正常と利用不可の間で変動し、サービスが実行中に 見えるにもかかわらず、チャンネルのディスパッチが停止する場合に使用します。

これは、ai.openclaw.gateway と ai.openclaw.node の両方の LaunchAgent が有効で、それぞれが OPENCLAW_LAUNCHD_LABEL を注入していた 古いインストール環境で確認されています。この状態では、OpenClaw が launchd による監視を検出し、再起動を launchd に戻そうとして、安定した 1 つの Gateway プロセスではなく、高速な EADDRINUSE/再起動ループに陥ることがあります。

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

確認事項:

• 30 秒間のサンプルで、安定した 1 つのプロセスではなく複数の Gateway PID が 表示される。
• gateway.log に EADDRINUSE、another gateway instance is already listening、 または再起動/引き渡しの行が繰り返し表示される。
• 管理対象の Gateway サービスを 1 つだけ実行すべきホストで、 ~/Library/LaunchAgents/ai.openclaw.gateway.plist と ~/Library/LaunchAgents/ai.openclaw.node.plist の両方が同時に読み込まれている。

対処方法:

1. このホストで Gateway サービスだけを実行する場合は、OpenClaw を通じて 管理対象の Node サービスを削除します。リモート Node 機能のために Node サービスを実際に使用している場合は、アンインストールするとこのホスト上の それらの機能が停止するため、この手順をスキップしてください:

   openclaw node uninstall

2. OpenClaw を起動する前に、継承された launchd マーカーを消去する永続的な Gateway ラッパーをインストールします。サポートされている --wrapper オプションを使用してください。サービスの再インストール、更新、Doctor による修復で再生成されるため、~/.openclaw/service-env/ 配下の生成済み ファイルは編集しないでください:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install は、強制再インストール、更新、Doctor による修復を行っても、 ラッパーのパスを保持します。

3. Gateway が単にリッスンしているだけでなく、安定して RPC を提供していることを 確認します:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID サンプルには、入れ替わり続ける複数の PID ではなく、安定した 1 つの プロセスが表示され、受信チャンネルのディスパッチが再開する必要があります。

4. 根本的な LaunchAgent の二重ループが修正されたリリースへアップグレードした後、 回避策を削除し、通常の管理対象サービスを再インストールします:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

関連項目:

• macOS プラットフォームの注意事項
• Doctor
• Gateway CLI

メモリ使用量が多いときに Gateway が終了する

負荷がかかると Gateway が消失する場合、スーパーバイザーが OOM 形式の再起動を報告する場合、またはログに critical memory pressure bundle written と記録されている場合に使用します。

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

確認事項:

• 最新の安定性バンドルに Reason: diagnostic.memory.pressure.critical がある。
• Memory pressure: に critical/rss_threshold、critical/heap_threshold、または critical/rss_growth がある。
• V8 heap: の値がヒープ上限に近い。
• Largest session files: に agents/<agent>/sessions/<session>.jsonl や sessions/<session>.jsonl などのエントリがある。
• Gateway がコンテナまたはメモリ制限付きサービス内で実行されている場合、Linux cgroup のメモリカウンターがある。

一般的な兆候:

• 再起動の直前に critical memory pressure bundle written が表示される → OpenClaw が OOM 前の安定性バンドルを取得しました。openclaw gateway stability --bundle latest で確認してください。
• Gateway ログに memory pressure: level=critical ... memoryPressureSnapshot=disabled が表示される → OpenClaw は重大なメモリ圧迫を検出しましたが、OOM 前の安定性スナップショットは無効です。
• Largest session files: が非常に大きな編集済みトランスクリプトのパスを示す → 保持するセッション履歴を減らすか、セッションの増大を調査するか、再起動前に古いトランスクリプトをアクティブストアの外へ移動してください。
• V8 heap: の使用済みバイト数がヒープ上限に近い → プロンプト/セッションの負荷を下げるか、同時実行作業を減らすか、ワークロードが想定どおりであることを確認した後にのみ Node のヒープ上限を引き上げてください。
• Memory pressure: critical/rss_growth → 1 回のサンプリング期間内にメモリが急増しました。最新ログで、大規模なインポート、制御不能なツール出力、繰り返される再試行、またはキューに入ったエージェント作業の一括処理を確認してください。
• 重大なメモリ圧迫がログに表示されるが、バンドルが存在しない → これがデフォルトです。今後の重大なメモリ圧迫イベントで OOM 前の安定性バンドルを取得するには、diagnostics.memoryPressureSnapshot: true を設定してください。

安定性バンドルにはペイロードが含まれません。メッセージ本文、Webhook 本文、認証情報、トークン、Cookie、生のセッション ID ではなく、運用上のメモリ情報と編集済みの相対ファイルパスが含まれます。生のログをコピーする代わりに、診断エクスポートをバグ報告へ添付してください。

関連項目:

• Gateway のヘルス
• 診断エクスポート
• セッション

Gateway が無効な設定を拒否した

Gateway の起動が Invalid config で失敗する場合、またはホットリロードのログに無効な編集をスキップしたと記録されている場合に使用します。

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

確認事項:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• アクティブな設定ファイルの隣に、タイムスタンプ付きの openclaw.json.rejected.* ファイルがある。
• doctor --fix が壊れた直接編集を修復した場合、タイムスタンプ付きの openclaw.json.clobbered.* ファイルがある。
• OpenClaw は設定パスごとに最新の 32 個の .clobbered.* ファイルを保持し、それより古いものをローテーションします。

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

関連項目:

• 設定
• 設定: ホットリロード
• 設定: 厳格な検証
• Doctor

Gateway プローブの警告

openclaw gateway probe が何らかの対象に到達しているにもかかわらず、警告ブロックが表示される場合に使用します。

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

確認項目:

• JSON 出力の warnings[].code と primaryTargetId。
• 警告が SSH フォールバック、複数の Gateway、スコープ不足、未解決の認証参照のいずれに関するものか。

一般的なシグネチャ:

• SSH tunnel failed to start; falling back to direct probes. → SSH のセットアップに失敗しましたが、コマンドは設定済みの直接ターゲット/local loopback ターゲットへのプローブを引き続き試行しました。
• multiple reachable gateway identities detected → 異なる Gateway が応答したか、到達可能なターゲットが同じ Gateway であることを OpenClaw が証明できませんでした。同じ Gateway への SSH トンネル、プロキシ URL、または設定済みリモート URL は、トランスポートのポートが異なる場合でも、複数のトランスポートを持つ 1 つの Gateway として扱われます。
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 接続には成功しましたが、詳細 RPC はスコープによって制限されています。デバイス ID をペアリングするか、operator.read を持つ認証情報を使用してください。
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 接続には成功しましたが、完全な診断 RPC セットがタイムアウトまたは失敗しました。これは診断機能が低下した到達可能な Gateway として扱い、--json 出力の connect.ok と connect.rpcOk を比較してください。
• Capability: pairing-pending または gateway closed (1008): pairing required → Gateway は応答しましたが、このクライアントが通常のオペレーターアクセスを行うには、引き続きペアリング/承認が必要です。
• 未解決の gateway.auth.* / gateway.remote.* SecretRef 警告テキスト → 失敗したターゲットに対して、このコマンドパスでは認証情報を利用できませんでした。

関連項目:

• Gateway
• 同じホスト上の複数の Gateway
• リモートアクセス

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

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

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

確認項目:

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

一般的なシグネチャ:

• mention required → グループのメンションポリシーによりメッセージが無視されました。
• pairing / 承認待ちのトレース → 送信者が承認されていません。
• missing_scope、not_in_channel、Forbidden、401/403 → チャンネルの認証/権限に問題があります。

関連項目:

• チャンネルのトラブルシューティング
• Discord
• Telegram
• WhatsApp

Cron と Heartbeat の配信

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

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

確認項目:

• Cron が有効で、次回のウェイク時刻が存在すること。
• ジョブ実行履歴のステータス（ok、skipped、error）。
• Heartbeat のスキップ理由（quiet-hours、requests-in-flight、cron-in-progress、lanes-busy、alerts-disabled、empty-heartbeat-file、no-tasks-due）。

関連項目:

• Heartbeat
• スケジュールされたタスク
• スケジュールされたタスク: トラブルシューティング

Node はペアリング済みだが、ツールが失敗する

Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認の状態を切り分けてください。

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

確認項目:

• Node がオンラインで、想定される機能を備えていること。
• カメラ/マイク/位置情報/画面に対する OS 権限の付与。
• Exec の承認と許可リストの状態。

一般的なシグネチャ:

• NODE_BACKGROUND_UNAVAILABLE → Node アプリがフォアグラウンドにある必要があります。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → OS 権限が不足しています。
• SYSTEM_RUN_DENIED: approval required → Exec の承認待ちです。
• SYSTEM_RUN_DENIED: allowlist miss → コマンドが許可リストによってブロックされました。

関連項目:

• Exec の承認
• Node のトラブルシューティング
• Node

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

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

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

確認項目:

• plugins.allow が設定され、browser が含まれているか。
• ブラウザーの実行可能ファイルへのパスが有効か。
• CDP プロファイルに到達可能か。
• existing-session / user プロファイルでローカルの Chrome が利用可能か。

関連項目:

• ブラウザー（OpenClaw 管理）
• ブラウザーのトラブルシューティング

アップグレード後に突然問題が発生した場合

アップグレード後の問題の多くは、設定のずれ、または以前より厳格なデフォルトが適用されるようになったことが原因です。

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

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

openclaw gateway install --forceopenclaw gateway restart

関連項目:

• 認証
• バックグラウンド Exec とプロセスツール
• Node のペアリング

関連項目

• Doctor
• よくある質問
• Gateway ランブック