コマンドラダー
次の順序で実行します。openclaw gateway statusにRuntime: running、Connectivity probe: ok、およびCapability: ...行が表示される。openclaw doctorがブロック要因となる設定/サービスの問題を報告しない。openclaw channels status --probeにアカウントごとのライブなトランスポート状態が表示され、サポートされる場合はworksまたはaudit okが表示される。
更新後
更新は完了したが Gateway が停止している、チャンネルが空、またはモデル呼び出しが 401 で失敗する場合に使用します。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 サービスの start/stop/restart/uninstall、強制サービス再インストール、サービスモードの Gateway 起動、および gateway --force のポートクリーンアップ。
ロールバック後のプロトコル不一致
ダウングレードまたはロールバック後にログがprotocol mismatch を出し続ける場合に使用します。古い Gateway が動作していますが、新しいローカルクライアントプロセスが、古い Gateway では話せないプロトコル範囲でまだ再接続しています。
- 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 を埋め込むアプリまたはラッパーを再起動します: ローカルダッシュボード、エディター、アプリサーバーヘルパー、または長時間実行中の
openclaw logs --followシェル。 openclaw gateway status --deepまたはopenclaw doctor --deepを再実行し、古いクライアント PID がなくなったことを確認します。
パスエスケープとしてスキップされた Skill シンボリックリンク
ログに次が含まれる場合に使用します。~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills、または ~/.openclaw/skills 配下のシンボリックリンクは、その実体ターゲットがそのルートの外に解決される場合、ターゲットが明示的に信頼されていない限りスキップされます。
リンクを検査します。
~、/、または同期済みプロジェクトフォルダー全体のような広いターゲットは使用しないでください。allowSymlinkTargets は、信頼できる SKILL.md ディレクトリを含む実際の Skill ルートに限定してください。
Skill Workshop の apply でも、信頼されたシンボリックリンクされたワークスペース Skill パスへ書き込む必要がある場合は、skills.workshop.allowSymlinkTargetWrites を有効にします。読み取り専用の共有 Skill ルートでは無効のままにします。
関連:
長いコンテキストに Anthropic 429 の追加使用量が必要
ログ/エラーにHTTP 429: rate_limit_error: Extra usage is required for long context requests が含まれる場合に使用します。
- 選択された Anthropic モデルが GA 対応の 1M Claude 4.x モデル (Opus 4.6/4.7/4.8、Sonnet 4.6) である、またはモデル設定にまだレガシーの
params.context1m: trueが含まれている。 - 現在の Anthropic 認証情報が長いコンテキストの使用対象ではない。
- 1M コンテキストパスを必要とする長いセッション/モデル実行でのみリクエストが失敗する。
Use a standard context window
標準ウィンドウのモデルに切り替えるか、1M コンテキストで GA 対応ではない古い
モデル設定からレガシーの
context1m を削除します。アップストリームの 403 ブロック応答
アップストリームの LLM プロバイダーがYour request was blocked のような汎用 403 を返す場合に使用します。
これが常に OpenClaw の設定問題だと仮定しないでください。応答は、OpenAI 互換エンドポイントの前段にある CDN、WAF、ボット管理ルール、またはリバースプロキシなどのアップストリームのセキュリティ層から返されることがあります。
- 同じプロバイダー配下の複数のモデルが同じ方法で失敗している。
- 通常のプロバイダー API エラーではなく、HTML または汎用セキュリティテキストが返されている。
- 同じリクエスト時刻にプロバイダー側のセキュリティイベントがある。
- 小さな直接
curlプローブは成功するが、通常の SDK 形式のリクエストは失敗する。
ローカルの OpenAI 互換バックエンドは直接プローブに通るが、エージェント実行が失敗する
次の場合に使用します。curl ... /v1/modelsが動作する。- 小さな直接
/v1/chat/completions呼び出しが動作する。 - OpenClaw モデル実行が通常のエージェントターンでのみ失敗する。
- 直接の小さな呼び出しは成功するが、OpenClaw 実行は大きなプロンプトでのみ失敗する。
- 同じ素のモデル ID で直接
/v1/chat/completionsが動作しているにもかかわらず、model_not_foundまたは 404 エラーが発生する。 messages[].contentが文字列を期待しているというバックエンドエラー。- OpenAI 互換ローカルバックエンドで、断続的な
incomplete turn detected ... stopReason=stop payloads=0警告が発生する。 - 大きなプロンプトトークン数または完全なエージェントランタイムプロンプトでのみ発生するバックエンドクラッシュ。
Common signatures
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 リクエストを完了しましたが、そのターンのユーザーに見えるアシスタントテキストを返しませんでした。OpenClaw はリプレイ安全な空の OpenAI 互換ターンを一度だけ再試行します。永続的な失敗は通常、バックエンドが空/非テキストコンテンツを出力しているか、最終回答テキストを抑制していることを意味します。- 直接の小さなリクエストは成功するが、OpenClaw エージェント実行がバックエンド/モデルクラッシュで失敗する (たとえば一部の
inferrsビルド上の Gemma): OpenClaw のトランスポートはすでに正しい可能性が高く、バックエンドがより大きなエージェントランタイムプロンプト形状で失敗しています。 - ツールを無効にすると失敗は減るが、消えない: ツールスキーマは負荷の一部でしたが、残る問題は依然としてアップストリームのモデル/サーバー容量またはバックエンドのバグです。
Fix options
Fix options
- 文字列のみの Chat Completions バックエンドには
compat.requiresStringContent: trueを設定します。 - 各メッセージで
roleとcontentのみを受け入れる厳格な Chat Completions バックエンドにはcompat.strictMessageKeys: trueを設定します。 - OpenClaw のツールスキーマサーフェスを確実に扱えないモデル/バックエンドには
compat.supportsTools: falseを設定します。 - 可能な範囲でプロンプト負荷を下げます: より小さなワークスペースブートストラップ、短いセッション履歴、軽量なローカルモデル、またはより強力な長いコンテキスト対応のバックエンド。
- 小さな直接リクエストは通り続けるのに OpenClaw エージェントターンがバックエンド内部でまだクラッシュする場合は、アップストリームのサーバー/モデル制限として扱い、受け入れられたペイロード形状を添えてそちらに再現報告を提出します。
返信がない
チャンネルは起動しているのに何も応答しない場合は、何かを再接続する前にルーティングとポリシーを確認してください。- DM 送信者のペアリングが保留中になっている。
- グループメンションのゲート制御（
requireMention,mentionPatterns）。 - チャンネル/グループの許可リスト不一致。
drop guild message (mention required→ メンションされるまでグループメッセージは無視される。pairing request→ 送信者に承認が必要。blocked/allowlist→ 送信者/チャンネルがポリシーによってフィルターされた。
ダッシュボード Control UI の接続性
ダッシュボード/Control UI が接続できない場合は、URL、認証モード、セキュアコンテキストの前提を検証します。- 正しいプローブ URL とダッシュボード URL。
- クライアントと Gateway の間の認証モード/トークン不一致。
- デバイス ID が必要な場所で HTTP を使用している。
127.0.0.1:18789 に接続できない場合は、まずローカル Gateway サービスを復旧し、ダッシュボードを提供していることを確認します。
curl が OpenClaw HTML を返す場合、Gateway は動作しており、残る問題はブラウザーキャッシュ、古いディープリンク、または古いタブ状態である可能性があります。http://127.0.0.1:18789 を直接開き、ダッシュボードから移動してください。再起動してもサービスが稼働したままにならない場合は、openclaw gateway start を実行し、openclaw gateway status を再確認します。
認証詳細コードのクイックマップ
失敗した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 に承認が必要。not-paired、scope-upgrade、role-upgrade、または metadata-upgrade については error.details.reason を確認し、存在する場合は requestId / remediationHint を使用する。 | 保留中のリクエストを承認する: openclaw devices list の後に openclaw devices approve <requestId> を実行する。スコープ/ロールのアップグレードも、要求されたアクセスを確認した後、同じフローを使用する。 |
共有 Gateway トークン/パスワードで認証された直接のループバックバックエンド RPC は、CLI のペアリング済みデバイススコープベースラインに依存すべきではありません。サブエージェントやその他の内部呼び出しがまだ
scope-upgrade で失敗する場合は、呼び出し元が client.id: "gateway-client" と client.mode: "backend" を使用しており、明示的な deviceIdentity またはデバイストークンを強制していないことを確認してください。openclaw devices rotate / revoke / remove が予期せず拒否される場合:
- ペアリング済みデバイストークンセッションは、呼び出し元が
operator.adminも持っていない限り、自分自身のデバイスだけを管理できます。 openclaw devices rotate --scope ...は、呼び出し元セッションがすでに保持しているオペレータースコープのみを要求できます。
- 設定（Gateway 認証モード）
- Control UI
- デバイス
- リモートアクセス
- 信頼済みプロキシ認証
Gateway サービスが実行されていない
サービスはインストールされているが、プロセスが起動し続けない場合に使用します。- 終了ヒント付きの
Runtime: stopped。 - サービス設定の不一致（
Config (cli)とConfig (service)）。 - ポート/リスナーの競合。
--deepを使用したときの追加の launchd/systemd/schtasks インストール。Other gateway-like services detected (best effort)のクリーンアップヒント。
よくあるシグネチャ
よくあるシグネチャ
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 が再び稼働しているためです。
~/.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 ドライバーを短時間 state 0 にする。その時間帯に発生した外向きのconnect()は、通常は完全なネットワーク接続があるホストでもENETDOWNで失敗することがある。 launchctl print出力に、複数の最近のrunsと終了コードを伴うstate = not runningが表示される。特に、クラッシュから次の起動までの間隔が数秒ではなく 1 時間程度の場合。macOS launchd はクラッシュの連続後に未文書化の再起動保護ゲートを適用し、対話型ログイン、ダッシュボード接続、launchctl kickstartなどの外部トリガーで再び有効化されるまで、KeepAlive=trueを尊重しなくなることがある。
error.codeがENETDOWNまたは関連コードで、コールスタックが NodenetのlookupAndConnect/Socket.connectを指している安定性バンドル。OpenClaw2026.5.26以降は、これらを無害な一時的ネットワークエラーとして分類するため、トップレベルの uncaught ハンドラーには伝播しなくなった。古いリリースを使用している場合は、まずアップグレードする。- Control UI に接続するかホストへ SSH した瞬間に終わる長い無音期間: launchd の再起動ゲートを再び有効化するのはユーザーに見えるアクティビティであり、ダッシュボードが Gateway に対して行う処理ではない。
- 1 日を通して
runsカウントが増えているのに、~/Library/Logs/openclaw/gateway.logに対応するreceived SIG*; shutting down行がない: クリーンシャットダウンではシグナルが記録されるが、一時的なクラッシュでは記録されない。
-
2026.5.26より前のリリースを実行している場合は、Gateway をアップグレードする。アップグレード後は、今後のENETDOWNエラーはプロセスを終了させる代わりに警告として記録される。 -
常時稼働サーバーとして使う Mac mini / デスクトップホストでは、メンテナンススリープの動作を減らす:
これにより、根本のドライバーフラップは大幅に減るが、完全にはなくならない。これらのフラグにかかわらず、システムは TCP keepalive や mDNS 保守のために一部のメンテナンススリープを実行することがある。
-
launchd によって保留された将来のクラッシュ連続をすばやく検出できるように、liveness watchdog を追加する:
目的は、外部から再起動ゲートを再び有効化すること。macOS ではクラッシュ連続後に
KeepAlive=trueだけでは十分ではない。
メモリ使用量が多いときに Gateway が終了する
負荷中に Gateway が消える、スーパーバイザーが OOM 形式の再起動を報告する、またはログにcritical memory pressure bundle written と表示される場合に使用する。
- 最新の安定性バンドル内の
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を設定する。
Gateway が無効な設定を拒否した
Gateway の起動がInvalid config で失敗する場合、またはホットリロードログに無効な編集をスキップしたと表示される場合に使用する。
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が修復を担当する。JSON ではない接頭辞を削除したり、最後に正常だったコピーを復元したりでき、拒否されたペイロードは.clobbered.*として保持する。- 1 つの設定パスで多数の修復が発生すると、OpenClaw は古い
.clobbered.*ファイルをローテーションし、最新の修復済みペイロードを利用可能な状態に保つ。
調査と修復
調査と修復
よくある兆候
よくある兆候
.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 が何かに到達するが、それでも警告ブロックを表示する場合に使用する。
- JSON 出力内の
warnings[].codeとprimaryTargetId。 - 警告が SSH フォールバック、複数の Gateway、不足しているスコープ、または未解決の認証参照に関するものかどうか。
SSH tunnel failed to start; falling back to direct probes.→ SSH セットアップは失敗したが、コマンドは引き続き設定済み/loopback の直接ターゲットを試した。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 は応答したが、このクライアントは通常の operator アクセスの前にペアリング/承認がまだ必要。- 未解決の
gateway.auth.*/gateway.remote.*SecretRef 警告テキスト → 失敗したターゲットについて、このコマンドパスでは認証素材を利用できなかった。
チャンネルは接続済みだがメッセージが流れない
チャンネル状態が接続済みなのにメッセージフローが止まっている場合は、ポリシー、権限、チャンネル固有の配信ルールに注目する。- DM ポリシー (
pairing、allowlist、open、disabled)。 - グループ allowlist とメンション要件。
- 不足しているチャンネル API 権限/スコープ。
mention required→ グループメンションポリシーによりメッセージが無視された。pairing/ 承認待ちトレース → 送信者が承認されていない。missing_scope、not_in_channel、Forbidden、401/403→ チャンネル認証/権限の問題。
Cron と Heartbeat の配信
Cron または Heartbeat が実行されなかった、または配信されなかった場合は、まずスケジューラー状態を確認し、次に配信ターゲットを確認する。- 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 skippedとreason=quiet-hours→ アクティブ時間帯の範囲外。heartbeat skippedとreason=empty-heartbeat-file→HEARTBEAT.mdは存在するが、空白、コメント、ヘッダー、フェンス、または空のチェックリストの足場だけを含むため、OpenClaw はモデル呼び出しをスキップする。heartbeat skippedとreason=no-tasks-due→HEARTBEAT.mdにtasks:ブロックは含まれるが、この tick で期限のタスクがない。heartbeat: unknown accountId→ Heartbeat 配信先のアカウント ID が無効。heartbeat skippedとreason=dm-blocked→agents.defaults.heartbeat.directPolicy（またはエージェントごとの上書き）がblockに設定されている間に、Heartbeat の宛先が DM 形式の宛先として解決された。
Node はペアリング済みだが、ツールが失敗する
Node がペアリング済みでもツールが失敗する場合は、フォアグラウンド、権限、承認状態を切り分ける。- Node がオンラインで、期待される機能を持っている。
- カメラ、マイク、位置情報、画面に対する OS 権限付与。
- Exec 承認と許可リストの状態。
NODE_BACKGROUND_UNAVAILABLE→ Node アプリがフォアグラウンドにある必要がある。*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ OS 権限が不足している。SYSTEM_RUN_DENIED: approval required→ exec 承認が保留中。SYSTEM_RUN_DENIED: allowlist miss→ コマンドが許可リストでブロックされている。
ブラウザツールが失敗する
Gateway 自体は正常なのにブラウザツールのアクションが失敗する場合に使用する。plugins.allowが設定されており、browserを含んでいるか。- 有効なブラウザ実行ファイルパス。
- CDP プロファイルの到達可能性。
existing-session/userプロファイル向けのローカル Chrome の可用性。
Plugin / 実行ファイルのシグネチャ
Plugin / 実行ファイルのシグネチャ
unknown command "browser"またはunknown command 'browser'→ バンドルされたブラウザ Plugin がplugins.allowによって除外されている。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 / existing-session のシグネチャ
Chrome MCP / existing-session のシグネチャ
Could not find DevToolsActivePort for chrome→ Chrome MCP existing-session は、選択されたブラウザデータディレクトリにまだアタッチできなかった。ブラウザの inspect ページを開き、リモートデバッグを有効にし、ブラウザを開いたままにし、最初のアタッチプロンプトを承認してから再試行する。サインイン状態が不要な場合は、管理対象のopenclawプロファイルを優先する。No browser tabs found for profile="user"→ Chrome MCP アタッチプロファイルに、開いているローカル Chrome タブがない。Remote CDP for profile "<name>" is not reachable→ 設定されたリモート CDP エンドポイントに Gateway ホストから到達できない。Browser attachOnly is enabled ... not reachableまたはBrowser attachOnly is enabled and CDP websocket ... is not reachable→ attach-only プロファイルに到達可能なターゲットがない、または 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 つのアップロードを送信する。existing-session dialog handling does not support timeoutMs.→ Chrome MCP プロファイルのダイアログフックはタイムアウト上書きをサポートしていない。existing-session type does not support timeoutMs overrides.→profile="user"/ Chrome MCP existing-session プロファイルのact:typeではtimeoutMsを省略する。カスタムタイムアウトが必要な場合は、管理対象 / CDP ブラウザプロファイルを使用する。existing-session evaluate does not support timeoutMs overrides.→profile="user"/ Chrome MCP existing-session プロファイルのact:evaluateではtimeoutMsを省略する。カスタムタイムアウトが必要な場合は、管理対象 / CDP ブラウザプロファイルを使用する。response body is not supported for existing-session profiles yet.→responsebodyには引き続き、管理対象ブラウザまたは raw CDP プロファイルが必要。- attach-only またはリモート CDP プロファイルで、ビューポート / ダークモード / ロケール / オフラインの上書きが古い → Gateway 全体を再起動せずに、
openclaw browser stop --browser-profile <name>を実行してアクティブな制御セッションを閉じ、Playwright/CDP エミュレーション状態を解放する。
アップグレード後に何かが突然壊れた場合
アップグレード後の破損の多くは、設定のずれ、またはより厳格なデフォルトが現在適用されていることが原因。1. 認証と URL 上書きの挙動が変更された
1. 認証と URL 上書きの挙動が変更された
gateway.mode=remoteの場合、ローカルサービスが正常でも CLI 呼び出しはリモートを対象にしている可能性がある。- 明示的な
--url呼び出しは、保存済み認証情報にフォールバックしない。
gateway connect failed:→ URL ターゲットが間違っている。unauthorized→ エンドポイントには到達できるが、認証が間違っている。
2. bind と認証のガードレールがより厳格になった
2. bind と認証のガードレールがより厳格になった
- 非 loopback bind（
lan、tailnet、custom）には、有効な Gateway 認証パスが必要。共有トークン / パスワード認証、または正しく設定された非 loopback のtrusted-proxyデプロイメント。 gateway.tokenのような古いキーはgateway.auth.tokenの代替にはならない。
refusing to bind gateway ... without auth→ 有効な Gateway 認証パスなしで非 loopback bind が行われている。Connectivity probe: failedでランタイムは実行中 → Gateway は稼働しているが、現在の認証 / URL ではアクセスできない。
3. ペアリングとデバイス ID 状態が変更された
3. ペアリングとデバイス ID 状態が変更された
- ダッシュボード / Node の保留中デバイス承認。
- ポリシーまたは ID 変更後の保留中 DM ペアリング承認。
device identity required→ デバイス認証が満たされていない。pairing required→ 送信者 / デバイスを承認する必要がある。