Gateway
トラブルシューティング
このページは詳細なランブックです。まず高速なトリアージフローを使いたい場合は、/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.lastTouchedVersionFix PATH
PATH を修正して openclaw が新しいインストールを解決するようにし、その後アクションを再実行します。
Reinstall the gateway service
新しいインストールから、意図した gateway サービスを再インストールします。
openclaw gateway install --forceopenclaw gateway restartRemove stale wrappers
まだ古い openclaw バイナリを指している古いシステムパッケージまたは古いラッパーエントリを削除します。
ロールバック後のプロトコル不一致
OpenClaw をダウングレードまたはロールバックした後も、ログに 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 インストールまたはラッパーを指しているクライアントプロセス。
修正:
gateway status --deepに表示される古い OpenClaw クライアントプロセスを停止または再起動します。- ローカルダッシュボード、エディター、アプリサーバーヘルパー、長時間実行中の
openclaw logs --followシェルなど、OpenClaw を組み込んでいるアプリやラッパーを再起動します。 openclaw gateway status --deepまたはopenclaw doctor --deepを再実行し、古いクライアント PID がなくなっていることを確認します。
古い Gateway に、新しい互換性のないプロトコルを受け入れさせないでください。プロトコルの引き上げはワイヤ契約を保護します。ロールバック復旧は、プロセス/バージョンのクリーンアップ問題です。
パスエスケープとしてスキルのシンボリックリンクがスキップされる
ログに次が含まれる場合に使用します。
Skipping escaped skill path outside its configured root: ... reason=symlink-escapeOpenClaw はすべてのスキルルートを封じ込め境界として扱います。
~/.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 watcher が更新されるのを待ちます。実行中のプロセスが設定変更より前のものである場合は、gateway を再起動します。
~、/、または同期済みプロジェクトフォルダー全体のような広いターゲットは使用しないでください。
allowSymlinkTargets は、信頼された SKILL.md ディレクトリを含む実際のスキルルートに限定してください。
Skill Workshop apply でも、これらの信頼されたシンボリックリンク先の
ワークスペーススキルパスに書き込む必要がある場合は、skills.workshop.allowSymlinkTargetWrites を有効にします。
読み取り専用の共有スキルルートでは無効のままにしてください。
関連:
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 モデルが GA 対応の 1M Claude 4.x モデルである、またはモデルにレガシーの
params.context1m: trueがある。 - 現在の Anthropic 認証情報が長いコンテキストの利用対象ではない。
- 1M コンテキストパスを必要とする長いセッション/モデル実行でのみリクエストが失敗する。
修正オプション:
Use a standard context window
標準ウィンドウのモデルに切り替えるか、1M コンテキストに GA 対応していない古い
モデル設定からレガシーの context1m を削除します。
Use an eligible credential
長いコンテキストリクエストの対象となる Anthropic 認証情報を使用するか、Anthropic API キーに切り替えます。
Configure fallback models
Anthropic の長いコンテキストリクエストが拒否された場合でも実行が継続するよう、フォールバックモデルを設定します。
関連:
アップストリームの 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互換バックエンドは直接プローブに通るがエージェント実行が失敗する
次の場合に使用します。
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警告 - より大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ現れるバックエンドクラッシュ
Common signatures
- ローカル MLX/vLLM スタイルのサーバーで
model_not_found→baseUrlに/v1が含まれていること、/v1/chat/completionsバックエンドではapiが"openai-completions"であること、models.providers.<provider>.models[].idが素のプロバイダーローカル id であることを確認します。たとえばmlx/mlx-community/Qwen3-30B-A3B-6bitのように、プロバイダープレフィックス付きで一度選択します。カタログエントリはmlx-community/Qwen3-30B-A3B-6bitのままにします。 messages[...].content: invalid type: sequence, expected a string→ バックエンドが構造化された Chat Completions コンテンツパーツを拒否しています。修正:models.providers.<provider>.models[].compat.requiresStringContent: trueを設定します。validation.keysまたは["role","content"]のような許可メッセージキー → バックエンドが Chat Completions メッセージ上の OpenAI スタイルのリプレイメタデータを拒否しています。修正:models.providers.<provider>.models[].compat.strictMessageKeys: trueを設定します。incomplete turn detected ... stopReason=stop payloads=0→ バックエンドは Chat Completions リクエストを完了しましたが、そのターンでユーザーに表示される assistant テキストを返していません。OpenClaw は、リプレイ安全な空の OpenAI互換ターンを一度再試行します。永続的な失敗は通常、バックエンドが空/非テキストのコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。- 直接の小さなリクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルのクラッシュで失敗する(たとえば一部の
inferrsビルド上の Gemma) → OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドがより大きなエージェントランタイムプロンプト形状で失敗しています。 - ツールを無効化すると失敗が減るが消えない → ツールスキーマは負荷の一部でしたが、残る問題は依然としてアップストリームのモデル/サーバー容量またはバックエンドのバグです。
Fix options
- 文字列のみの Chat Completions バックエンドには
compat.requiresStringContent: trueを設定します。 - 各メッセージで
roleとcontentのみを受け入れる厳格な Chat Completions バックエンドにはcompat.strictMessageKeys: trueを設定します。 - OpenClaw のツールスキーマサーフェスを信頼性高く扱えないモデル/バックエンドには
compat.supportsTools: falseを設定します。 - 可能な範囲でプロンプト負荷を下げます。より小さなワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強力な長いコンテキスト対応を持つバックエンドを使用します。
- 小さな直接リクエストは成功し続ける一方で、OpenClaw エージェントターンがバックエンド内部でクラッシュし続ける場合は、アップストリームサーバー/モデルの制限として扱い、受け入れられたペイロード形状とともに再現を提出します。
関連:
応答がない
チャネルは起動しているのに何も応答しない場合は、何かを再接続する前にルーティングとポリシーを確認します。
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→ 送信者/チャネルがポリシーでフィルタされた。
関連:
ダッシュボード Control UI の接続性
ダッシュボード/Control 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:18789curl が OpenClaw HTML を返す場合、Gateway は動作しており、残りの問題は
ブラウザーキャッシュ、古いディープリンク、または古いタブ状態である可能性が高いです。
http://127.0.0.1:18789 を直接開き、ダッシュボードから移動してください。再起動後も
サービスが稼働しない場合は、openclaw gateway start を実行し、
openclaw gateway status を再確認します。
Connect / auth signatures
device identity required→ 非セキュアコンテキスト、またはデバイス認証の欠落。origin not allowed→ ブラウザーのOriginがgateway.controlUi.allowedOriginsに含まれていない(または明示的な許可リストなしで非ループバックのブラウザーオリジンから接続している)。device nonce required/device nonce mismatch→ クライアントがチャレンジベースのデバイス認証フロー(connect.challenge+device.nonce)を完了していない。device signature invalid/device signature expired→ クライアントが現在のハンドシェイクに対して誤ったペイロード(または古いタイムスタンプ)に署名した。AUTH_TOKEN_MISMATCHかつcanRetryWithDeviceToken=true→ クライアントはキャッシュ済みデバイストークンで 1 回だけ信頼済みリトライを実行できる。- そのキャッシュ済みトークンによるリトライは、ペアリング済みデバイストークンと一緒に保存されたキャッシュ済みスコープセットを再利用する。明示的な
deviceToken/ 明示的なscopes呼び出し元は、代わりに要求したスコープセットを維持する。 AUTH_SCOPE_MISMATCH→ デバイストークンは認識されたが、その承認済みスコープがこの接続リクエストをカバーしていない。共有 Gateway トークンをローテーションするのではなく、再ペアリングするか要求されたスコープ契約を承認する。- そのリトライ経路以外では、接続認証の優先順位は、明示的な共有トークン/パスワード、明示的な
deviceToken、保存済みデバイストークン、ブートストラップトークンの順。 - 非同期 Tailscale Serve Control UI 経路では、同じ
{scope, ip}に対する失敗した試行は、リミッターが失敗を記録する前に直列化される。そのため、同じクライアントから 2 つの不正なリトライが同時に行われると、2 つの通常の不一致ではなく、2 回目の試行でretry laterが表面化することがある。 - ブラウザーオリジンのループバッククライアントからの
too many failed authentication attempts (retry later)→ 同じ正規化済みOriginからの失敗が繰り返されたため、一時的にロックアウトされている。別の localhost オリジンは別のバケットを使用する。 - そのリトライ後も
unauthorizedが繰り返される → 共有トークン/デバイストークンのずれ。必要に応じてトークン設定を更新し、デバイストークンを再承認/ローテーションする。 gateway connect failed:→ ホスト/ポート/URL ターゲットが誤っている。
認証詳細コードのクイックマップ
失敗した connect レスポンスの error.details.code を使って、次の対応を選びます。
| 詳細コード | 意味 | 推奨対応 |
|---|---|---|
AUTH_TOKEN_MISSING |
クライアントが必要な共有トークンを送信しなかった。 | クライアントにトークンを貼り付ける/設定してリトライする。ダッシュボード経路の場合: openclaw config get gateway.auth.token の後、Control UI 設定に貼り付ける。 |
AUTH_TOKEN_MISMATCH |
共有トークンが Gateway 認証トークンと一致しなかった。 | canRetryWithDeviceToken=true の場合は、1 回の信頼済みリトライを許可する。キャッシュ済みトークンのリトライは保存済みの承認済みスコープを再利用する。明示的な deviceToken / scopes 呼び出し元は要求したスコープを維持する。それでも失敗する場合は、トークンずれ復旧チェックリストを実行する。 |
AUTH_DEVICE_TOKEN_MISMATCH |
キャッシュ済みのデバイスごとのトークンが古い、または失効している。 | devices CLI を使ってデバイストークンをローテーション/再承認し、再接続する。 |
AUTH_SCOPE_MISMATCH |
デバイストークンは有効だが、その承認済みロール/スコープがこの接続リクエストをカバーしていない。 | デバイスを再ペアリングするか、要求されたスコープ契約を承認する。これを共有トークンのずれとして扱わない。 |
PAIRING_REQUIRED |
デバイス ID に承認が必要。error.details.reason で not-paired、scope-upgrade、role-upgrade、または metadata-upgrade を確認し、存在する場合は requestId / remediationHint を使用する。 |
保留中のリクエストを承認する: openclaw devices list の後、openclaw devices approve <requestId>。スコープ/ロールのアップグレードも、要求されたアクセスを確認した後に同じフローを使用する。 |
デバイス認証 v2 移行チェック:
openclaw --versionopenclaw doctoropenclaw gateway statusログに nonce/署名エラーが表示される場合は、接続元クライアントを更新して検証します。
Wait for connect.challenge
クライアントは Gateway が発行した connect.challenge を待つ。
Sign the payload
クライアントはチャレンジに紐づいたペイロードに署名する。
Send the device nonce
クライアントは同じチャレンジ nonce とともに connect.params.device.nonce を送信する。
openclaw devices rotate / revoke / remove が予期せず拒否される場合:
- ペアリング済みデバイストークンのセッションは、呼び出し元が
operator.adminも持っていない限り、自分自身の デバイスのみ管理できる openclaw devices rotate --scope ...は、呼び出し元セッションがすでに保持している operator スコープのみ要求できる
関連:
- 設定(Gateway 認証モード)
- Control UI
- デバイス
- リモートアクセス
- 信頼済みプロキシ認証
Gateway サービスが実行されていない
サービスはインストールされているが、プロセスが稼働し続けない場合に使用します。
openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep # also scan system-level services確認すること:
Runtime: stoppedと終了ヒント。- サービス設定の不一致(
Config (cli)とConfig (service))。 - ポート/リスナー競合。
--deep使用時の追加の launchd/systemd/schtasks インストール。Other gateway-like services detected (best effort)のクリーンアップヒント。
Common signatures
Gateway start blocked: set gateway.mode=localまたはexisting config is missing gateway.mode→ ローカル Gateway モードが有効ではない、または設定ファイルが上書きされてgateway.modeが失われている。修正: 設定でgateway.mode="local"を設定するか、openclaw onboard --mode local/openclaw setupを再実行して期待されるローカルモード設定を再スタンプする。Podman 経由で OpenClaw を実行している場合、デフォルト設定パスは~/.openclaw/openclaw.json。refusing to bind gateway ... without auth→ 有効な Gateway 認証経路(トークン/パスワード、または設定済みの場合は信頼済みプロキシ)なしで非ループバックにバインドしている。another gateway instance is already listening/EADDRINUSE→ ポート競合。Other gateway-like services detected (best effort)→ 古い、または並列の launchd/systemd/schtasks ユニットが存在する。ほとんどのセットアップでは、マシンごとに Gateway は 1 つにするべきです。複数必要な場合は、ポート + 設定/状態/ワークスペースを分離してください。/gateway#multiple-gateways-same-host を参照してください。- doctor からの
System-level OpenClaw gateway service detected→ ユーザーレベルサービスがない一方で、systemd システムユニットが存在する。doctor にユーザーサービスをインストールさせる前に重複を削除または無効化するか、そのシステムユニットが意図したスーパーバイザーである場合はOPENCLAW_SERVICE_REPAIR_POLICY=externalを設定する。 Gateway service port does not match current gateway config→ インストール済みスーパーバイザーがまだ古い--portを固定している。openclaw doctor --fixまたはopenclaw gateway install --forceを実行し、その後 Gateway サービスを再起動する。
関連:
macOS Gateway が黙って応答を停止し、ダッシュボードに触れると再開する
macOS ホスト上のチャネル(Telegram、WhatsApp など)が数分から数時間にわたって静かになり、Control UI を開く、SSH で入る、またはその他の方法でホストとやり取りした瞬間に Gateway が戻ってくるように見える場合に使用します。通常、openclaw status には明らかな症状はありません。確認する頃には Gateway が再び稼働しているためです。
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などの一時的なネットワークコードに設定されている。pmset -g logのEntering Sleep state due to 'Maintenance Sleep'やen0 driver is slow (msg: WillChangeState to 0)のような行が、クラッシュ時刻と一致している。Power Nap / Maintenance Sleep は Wi-Fi ドライバーを短時間だけ状態 0 にする。その時間枠に入った送信connect()は、それ以外では完全なネットワーク接続があるホストでもENETDOWNで失敗することがある。launchctl printの出力で、state = not runningと複数の直近runsおよび終了コードが表示されている。特にクラッシュから次の起動までの間隔が数秒ではなく 1 時間程度の場合。macOS launchd はクラッシュの連続後に未文書化の再生成保護ゲートを適用し、対話ログイン、ダッシュボード接続、launchctl kickstartなどの外部トリガーで再武装されるまでKeepAlive=trueを尊重しなくなることがある。
よくあるシグネチャ:
error.codeがENETDOWNまたは関連コードで、コールスタックが NodenetのlookupAndConnect/Socket.connectを指している安定性バンドル。OpenClaw2026.5.26以降はこれらを無害な一時的ネットワークエラーとして分類するため、トップレベルの未捕捉ハンドラーに伝播しなくなる。古いリリースを使っている場合は、まずアップグレードする。- Control UI に接続した瞬間、またはホストに SSH した瞬間に終わる長い無音期間: 再武装されるのは launchd の再生成ゲートであり、ダッシュボードが Gateway に対して何かを行っているわけではない。
- 1 日を通して
runs数が増えているが、~/Library/Logs/openclaw/gateway.logに対応するreceived SIG*; shutting down行がない: クリーンシャットダウンではシグナルがログに出る。一時的なクラッシュでは出ない。
対処方法:
-
2026.5.26より前のリリースを実行している場合は、Gateway をアップグレードする。アップグレード後、今後のENETDOWNエラーはプロセスを終了する代わりに警告としてログに記録される。 -
常時稼働サーバーとして動かす想定の Mac mini / デスクトップホストでは、メンテナンススリープの動作を減らす:
bash sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0これにより、根本にあるドライバーの揺らぎは大幅に減るが、完全にはなくならない。これらのフラグに関係なく、システムは TCP keepalive や mDNS 維持のために一部のメンテナンススリープを引き続き実行できる。
-
launchd によって保留された将来のクラッシュ連続をすばやく検知できるように、ライブネスウォッチドッグを追加する:
bash # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(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だけでは十分ではない。
関連:
高メモリ使用時に 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 ... 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 の起動が 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.*ファイルを保持し、古いものをローテーションする
起きたこと
- 起動中、ホットリロード中、または OpenClaw が所有する書き込み中に設定が検証を通らなかった。
- Gateway の起動は
openclaw.jsonを書き換える代わりにフェイルクローズする。 - ホットリロードは無効な外部編集をスキップし、現在のランタイム設定をアクティブのままにする。
- OpenClaw が所有する書き込みは、コミット前に無効/破壊的なペイロードを拒否し、
.rejected.*を保存する。 - 修復は
openclaw doctor --fixが所有する。拒否されたペイロードを.clobbered.*として保持しながら、JSON ではないプレフィックスを削除したり、最後に正常だったコピーを復元したりできる。 - 1 つの設定パスで多数の修復が発生した場合、OpenClaw は古い
.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よくあるシグネチャ
.clobbered.*が存在する → doctor はアクティブ設定を修復しながら、壊れた外部編集を保持した。.rejected.*が存在する → OpenClaw が所有する設定書き込みが、コミット前にスキーマまたは上書きチェックで失敗した。Config write rejected:→ 書き込みが必須の形を落とす、ファイルを急激に縮小する、または無効な設定を永続化しようとした。config reload skipped (invalid config):→ 直接編集が検証に失敗し、実行中の Gateway に無視された。Invalid config at ...→ Gateway サービスが起動する前に起動が失敗した。missing-meta-vs-last-good、gateway-mode-missing-vs-last-good、またはsize-drop-vs-last-good:*→ OpenClaw が所有する書き込みが、最後に正常だったバックアップと比べてフィールドまたはサイズを失ったため拒否された。Config last-known-good promotion skipped→ 候補に***などの編集済みシークレットプレースホルダーが含まれていた。
修正オプション
openclaw doctor --fixを実行し、doctor にプレフィックス付き/上書きされた設定を修復させるか、最後に正常だった状態を復元させる。.clobbered.*または.rejected.*から意図したキーだけをコピーし、openclaw config setまたはconfig.patchで適用する。- 再起動前に
openclaw config validateを実行する。 - 手作業で編集する場合は、変更したかった部分オブジェクトだけではなく、完全な JSON5 設定を保持する。
関連:
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 警告テキスト → 失敗したターゲットについて、このコマンドパスで認証素材を利用できなかった。
関連:
チャンネルは接続済みだが、メッセージが流れない
チャンネル状態が接続済みなのにメッセージフローが停止している場合は、ポリシー、権限、チャンネル固有の配信ルールに注目する。
openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels確認する内容:
- DM ポリシー (
pairing、allowlist、open、disabled)。 - グループ allowlist とメンション要件。
- 欠落しているチャンネル API 権限/スコープ。
よくあるシグネチャ:
mention required→ グループメンションポリシーによりメッセージが無視された。pairing/ 保留中の承認トレース → 送信者が承認されていない。missing_scope、not_in_channel、Forbidden、401/403→ チャンネル認証/権限の問題。
関連:
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)。
一般的なシグネチャ
cron: scheduler disabled; jobs will not run automatically→ cron が無効。cron: timer tick failed→ スケジューラの tick が失敗した。ファイル、ログ、ランタイムエラーを確認する。heartbeat skippedwithreason=quiet-hours→ アクティブ時間帯の範囲外。heartbeat skippedwithreason=empty-heartbeat-file→HEARTBEAT.mdは存在するが、空白、コメント、ヘッダー、フェンス、または空のチェックリストのひな形だけを含むため、OpenClaw はモデル呼び出しをスキップする。heartbeat skippedwithreason=no-tasks-due→HEARTBEAT.mdにはtasks:ブロックがあるが、この tick で期限を迎えるタスクがない。heartbeat: unknown accountId→ Heartbeat 配信ターゲットのアカウント ID が無効。heartbeat skippedwithreason=dm-blocked→agents.defaults.heartbeat.directPolicy(またはエージェントごとのオーバーライド) がblockに設定されている状態で、Heartbeat ターゲットが DM 形式の宛先に解決された。
関連:
Node はペアリング済みだが、ツールが失敗する
ノードがペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分ける。
openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status確認する項目:
- ノードがオンラインで、期待される機能を持っている。
- カメラ、マイク、位置情報、画面に対する OS 権限付与。
- Exec 承認と許可リストの状態。
一般的なシグネチャ:
NODE_BACKGROUND_UNAVAILABLE→ ノードアプリをフォアグラウンドにする必要がある。*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ OS 権限が不足している。SYSTEM_RUN_DENIED: approval required→ exec 承認が保留中。SYSTEM_RUN_DENIED: allowlist miss→ コマンドが許可リストによってブロックされた。
関連:
ブラウザツールが失敗する
Gateway 自体は正常でもブラウザツールのアクションが失敗する場合に使用する。
openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor確認する項目:
plugins.allowが設定されていて、browserが含まれているか。- 有効なブラウザ実行ファイルパス。
- CDP プロファイルへの到達性。
existing-session/userプロファイル用のローカル Chrome の可用性。
Plugin / 実行ファイルのシグネチャ
unknown command "browser"orunknown command 'browser'→ バンドル済みブラウザ Plugin がplugins.allowによって除外されている。- browser tool missing / unavailable while
browser.enabled=true→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 のポートが不正、または範囲外。Playwright is not available in this gateway build; '<feature>' is unsupported.→ 現在の Gateway インストールにはコアブラウザランタイム依存関係がない。OpenClaw を再インストールまたは更新してから、Gateway を再起動する。ARIA スナップショットと基本的なページスクリーンショットは引き続き動作する場合があるが、ナビゲーション、AI スナップショット、CSS セレクタ要素のスクリーンショット、PDF エクスポートは利用できないままになる。
Chrome MCP / 既存セッションのシグネチャ
Could not find DevToolsActivePort for chrome→ Chrome MCP の既存セッションが、選択されたブラウザデータディレクトリにまだアタッチできなかった。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにして、最初のアタッチプロンプトを承認してから再試行する。サインイン状態が不要な場合は、管理対象のopenclawプロファイルを優先する。No Chrome tabs found for profile="user"→ Chrome MCP アタッチプロファイルに、開いているローカル Chrome タブがない。Remote CDP for profile "<name>" is not reachable→ 設定されたリモート CDP エンドポイントに Gateway ホストから到達できない。Browser attachOnly is enabled ... not reachableorBrowser attachOnly is enabled and CDP websocket ... is not reachable→ アタッチ専用プロファイルに到達可能なターゲットがない、または HTTP エンドポイントは応答したが CDP WebSocket を開けなかった。
要素 / スクリーンショット / アップロードのシグネチャ
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 プロファイルのダイアログフックは、タイムアウトのオーバーライドをサポートしない。existing-session type does not support timeoutMs overrides.→profile="user"/ Chrome MCP 既存セッションプロファイルでact:typeにtimeoutMsを指定しない。カスタムタイムアウトが必要な場合は、管理対象または CDP ブラウザプロファイルを使用する。existing-session evaluate does not support timeoutMs overrides.→profile="user"/ Chrome MCP 既存セッションプロファイルでact:evaluateにtimeoutMsを指定しない。カスタムタイムアウトが必要な場合は、管理対象または CDP ブラウザプロファイルを使用する。response body is not supported for existing-session profiles yet.→responsebodyには引き続き管理対象ブラウザまたは raw CDP プロファイルが必要。- stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → Gateway 全体を再起動せずにアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放するには、
openclaw browser stop --browser-profile <name>を実行する。
関連:
アップグレード後に突然何かが壊れた場合
アップグレード後の破損の多くは、設定のドリフト、またはより厳格なデフォルトが適用されるようになったことが原因。
1. 認証と URL オーバーライドの動作が変更された
openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode確認する内容:
gateway.mode=remoteの場合、ローカルサービスは正常でも CLI 呼び出しがリモートをターゲットにしている可能性がある。- 明示的な
--url呼び出しは、保存済み認証情報へフォールバックしない。
一般的なシグネチャ:
gateway connect failed:→ URL ターゲットが間違っている。unauthorized→ エンドポイントには到達できるが、認証が間違っている。
2. バインドと認証のガードレールがより厳格になった
openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow確認する内容:
- 非ループバックバインド (
lan,tailnet,custom) には、有効な Gateway 認証パスが必要: 共有トークン/パスワード認証、または正しく設定された非ループバックのtrusted-proxyデプロイ。 gateway.tokenのような古いキーはgateway.auth.tokenを置き換えない。
一般的なシグネチャ:
refusing to bind gateway ... without auth→ 有効な Gateway 認証パスなしの非ループバックバインド。Connectivity probe: failedwhile runtime is running → Gateway は稼働しているが、現在の auth/url ではアクセスできない。
3. ペアリングとデバイス ID 状態が変更された
openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor確認する内容:
- ダッシュボード/ノードの保留中デバイス承認。
- ポリシーまたは ID 変更後の保留中 DM ペアリング承認。
一般的なシグネチャ:
device identity required→ デバイス認証が満たされていない。pairing required→ 送信者/デバイスを承認する必要がある。
確認後もサービス設定とランタイムが一致しない場合は、同じプロファイル/状態ディレクトリからサービスメタデータを再インストールする:
openclaw gateway install --forceopenclaw gateway restart関連: