トラブルシューティング

これは詳細なランブックです。まず迅速なトリアージ手順として、/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 が新しい非互換プロトコルを受け入れるようにはしないでください。プロトコルのバージョン更新は通信規約を保護するものです。ロールバックからの復旧は、プロセスとバージョンのクリーンアップで対処する問題です。

パスエスケープとしてスキップされるスキルのシンボリックリンク

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

設定されたルートの外部にエスケープしたスキルパスをスキップしています：... reason=symlink-escape

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

リンクを調べます。

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

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

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

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

~、/、または同期対象のプロジェクトフォルダー全体のような広範な参照先は使用しないでください。allowSymlinkTargets は、信頼済みの SKILL.md ディレクトリを含む実際のスキルルートに限定してください。

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

関連項目：

• 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 または一般的なセキュリティメッセージが返される。
• 同じリクエスト時刻に対応するプロバイダー側のセキュリティイベント。
• 通常の SDK 形式のリクエストが失敗する一方で、ごく小さな直接 curl プローブは成功する。

証拠が 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 など）が数分から数時間にわたって応答しなくなり、Control 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/ 内に 1 つ以上の *-uncaught_exception.json バンドルがあり、error.code が ENETDOWN、ENETUNREACH、EHOSTUNREACH、ECONNREFUSED などの一時的なネットワークコードに設定されている。
• クラッシュのタイムスタンプと一致する、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 接続した瞬間に終了する長時間の無応答期間：再作動させているのはユーザーに見えるアクティビティであり、ダッシュボードが 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 に戻そうとすることで、安定した単一の 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 秒間のサンプルで、安定した単一のプロセスではなく、複数の 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 ではなく、安定した単一のプロセスが表示され、受信チャンネルのディスパッチが再開する必要があります。

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。
• critical/rss_threshold、critical/heap_threshold、または critical/rss_growth を伴う Memory pressure:。
• ヒープ上限に近い V8 heap: の値。
• agents/<agent>/sessions/<session>.jsonl や sessions/<session>.jsonl などの Largest session files: エントリ。
• Gateway がコンテナまたはメモリ制限付きサービス内で実行されている場合の Linux cgroup メモリカウンター。

一般的な兆候：

• 再起動の直前に critical memory pressure bundle written が表示される → OpenClaw が OOM 発生前の安定性バンドルを取得しています。openclaw gateway stability --bundle latest で調査してください。
• Gateway のログに memory pressure: level=critical が表示される → OpenClaw が重大なメモリプレッシャーを検出し、利用可能なプロセス内メモリ情報を記録しています。
• Largest session files: が非常に大きな墨消し済みトランスクリプトパスを指している → 保持するセッション履歴を減らし、セッションの増加を調査するか、再起動前に古いトランスクリプトをアクティブストアの外へ移動してください。
• V8 heap: の使用バイト数がヒープ上限に近い → まずプロンプト/セッションの負荷を下げるか、同時実行作業を減らしてください。管理対象サービスでは、openclaw gateway status 内の Gateway heap: を確認してください。not set と表示される場合は、openclaw gateway install --force で古いサービスメタデータを再生成してください。周囲のシェルにある NODE_OPTIONS は意図的に無視されます。明示的なスーパーバイザーレベルのヒープ上書きは、継続的なワークロードを確認し、ネイティブメモリに十分な余裕を確保した後にのみ使用してください。
• Memory pressure: critical/rss_growth → 1 回のサンプリング期間内にメモリが急増しています。最新のログで、大規模なインポート、暴走したツール出力、繰り返される再試行、またはキューに入ったエージェント作業の一群を確認してください。
• 重大なメモリプレッシャーがログに表示されるが、バンドルが存在しない → イベント発生後に openclaw gateway diagnostics export を取得し、利用可能な運用上の証拠を収集してください。

安定性バンドルにはペイロードが含まれません。メッセージ本文、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 のセットアップに失敗しましたが、コマンドは設定済みの直接接続先／ループバック接続先への試行を続けました。
• multiple reachable gateway identities detected → 異なる Gateway が応答したか、OpenClaw が到達可能な接続先を同一の Gateway であると確認できませんでした。同じ 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）。

関連項目：

• Heartbeat
• スケジュール済みタスク
• スケジュール済みタスク：トラブルシューティング

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

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

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

確認事項：

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

一般的な兆候：

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

関連項目：

• 実行承認
• 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

関連項目:

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

関連項目

• Doctor
• FAQ
• Gateway 運用手順書