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

OpenClawが誤動作する場合の修正方法をご紹介します。

クイックトリアージのレシピが必要な場合は、FAQの最初の60秒から始めてください。このページでは、ランタイムの障害と診断について詳しく説明します。

プロバイダー固有のショートカット: /channels/troubleshooting

ステータスと診断

クイックトリアージコマンド(順番に):

コマンド何を教えてくれるかいつ使うか
openclaw statusローカルサマリー: OS + アップデート、ゲートウェイ到達可能性/モード、サービス、エージェント/セッション、プロバイダー設定状態最初のチェック、クイック概要
openclaw status --all完全なローカル診断(読み取り専用、貼り付け可能、比較的安全)ログテールを含むデバッグレポートを共有する必要がある場合
openclaw status --deepゲートウェイヘルスチェックを実行(プロバイダープローブを含む。到達可能なゲートウェイが必要)「設定済み」が「動作中」を意味しない場合
openclaw gateway probeゲートウェイディスカバリー + 到達可能性(ローカル + リモートターゲット)間違ったゲートウェイをプローブしている疑いがある場合
openclaw channels status --probe実行中のゲートウェイにチャネルステータスを問い合わせる(オプションでプローブ)ゲートウェイは到達可能だがチャネルが誤動作する場合
openclaw gateway statusスーパーバイザーステータス(launchd/systemd/schtasks)、ランタイムPID/終了、最後のゲートウェイエラーサービスが「ロード済み」に見えるが何も実行されない場合
openclaw logs --followライブログ(ランタイム問題の最良のシグナル)実際の障害理由が必要な場合

出力の共有: openclaw status --allを推奨(トークンをリダクト)。openclaw statusを貼り付ける場合は、まずOPENCLAW_SHOW_SECRETS=0を設定することを検討してください(トークンプレビュー)。

関連項目: ヘルスチェックとログ。

一般的な問題

プロバイダー「anthropic」のAPIキーが見つかりません

これは、エージェントの認証ストアが空であるか、Anthropic認証情報が欠落していることを意味します。 認証はエージェントごとなので、新しいエージェントはメインエージェントのキーを継承しません。

修正オプション:

  • オンボーディングを再実行し、そのエージェントにAnthropicを選択します。
  • またはゲートウェイホストでセットアップトークンを貼り付けます: 
    openclaw models auth setup-token --provider anthropic
  • またはメインエージェントディレクトリから新しいエージェントディレクトリにauth-profiles.jsonをコピーします。

確認:

openclaw models status

OAuthトークンリフレッシュ失敗(Anthropic Claudeサブスクリプション)

これは、保存されたAnthropic OAuthトークンの有効期限が切れ、リフレッシュが失敗したことを意味します。 Claudeサブスクリプション(APIキーなし)を使用している場合、最も信頼できる修正はClaude Codeセットアップトークンに切り替え、ゲートウェイホストに貼り付けることです。

推奨(セットアップトークン):

# ゲートウェイホストで実行(セットアップトークンを貼り付け)
openclaw models auth setup-token --provider anthropic
openclaw models status

他の場所でトークンを生成した場合:

openclaw models auth paste-token --provider anthropic
openclaw models status

詳細: AnthropicとOAuth。

Control UIがHTTPで失敗(「デバイスIDが必要」/「接続失敗」)

プレーンHTTPでダッシュボードを開いた場合(例: http://<lan-ip>:18789/またはhttp://<tailscale-ip>:18789/)、ブラウザは非セキュアコンテキストで実行され、WebCryptoがブロックされるため、デバイスIDを生成できません。

修正:

  • Tailscale Serve経由でHTTPSを優先します。
  • またはゲートウェイホストでローカルに開きます: http://127.0.0.1:18789/。
  • HTTPのままにする必要がある場合は、gateway.controlUi.allowInsecureAuth: trueを有効にし、ゲートウェイトークンを使用します(トークンのみ。デバイスID/ペアリングなし)。Control UIを参照してください。

CI Secrets Scan Failed

これはdetect-secretsがベースラインにまだ含まれていない新しい候補を見つけたことを意味します。 シークレットスキャンに従ってください。

サービスはインストールされているが何も実行されていない

ゲートウェイサービスがインストールされているがプロセスがすぐに終了する場合、サービスは「ロード済み」のように見えますが、何も実行されていません。

チェック:

openclaw gateway status
openclaw doctor

Doctor/serviceはランタイムステータス(PID/最後の終了)とログヒントを表示します。

ログ:

  • 推奨: openclaw logs --follow
  • ファイルログ(常に): /tmp/openclaw/openclaw-YYYY-MM-DD.log(または設定したlogging.file)
  • macOS LaunchAgent(インストール済みの場合): $OPENCLAW_STATE_DIR/logs/gateway.logとgateway.err.log
  • Linux systemd(インストール済みの場合): journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

より多くのログを有効にする:

  • ファイルログの詳細度を上げる(永続化されたJSONL): 
    { "logging": { "level": "debug" } }
  • コンソールの詳細度を上げる(TTY出力のみ): 
    { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
  • クイックヒント: --verboseはコンソール出力にのみ影響します。ファイルログはlogging.levelによって制御されたままです。

フォーマット、設定、アクセスの完全な概要については/loggingを参照してください。

"ゲートウェイ起動がブロックされました: gateway.mode=localを設定してください"

これは、設定が存在するがgateway.modeが未設定(またはlocalではない)ため、ゲートウェイが起動を拒否していることを意味します。

修正(推奨):

  • ウィザードを実行し、ゲートウェイ実行モードをLocalに設定します: 
    openclaw configure
  • または直接設定します: 
    openclaw config set gateway.mode local

代わりにリモートゲートウェイを実行する場合:

  • リモートURLを設定し、gateway.mode=remoteを維持します: 
    openclaw config set gateway.mode remote
openclaw config set gateway.remote.url "wss://gateway.example.com"

アドホック/開発のみ: --allow-unconfiguredを渡して、gateway.mode=localなしでゲートウェイを起動します。

まだ設定ファイルがない場合? openclaw setupを実行してスターター設定を作成し、ゲートウェイを再実行します。

サービス環境(PATH + ランタイム)

ゲートウェイサービスは、シェル/マネージャーの混乱を避けるため、最小限のPATHで実行されます:

  • macOS: /opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
  • Linux: /usr/local/bin、/usr/bin、/bin

これは意図的にバージョンマネージャー(nvm/fnm/volta/asdf)とパッケージマネージャー(pnpm/npm)を除外しています。サービスはシェルの初期化をロードしないためです。DISPLAYのようなランタイム変数は~/.openclaw/.envに配置する必要があります(ゲートウェイが早期にロード)。 host=gatewayでのExec実行は、ログインシェルのPATHをexec環境にマージするため、ツールが見つからない場合は通常、シェルの初期化がエクスポートしていないことを意味します(またはtools.exec.pathPrependを設定)。/tools/execを参照してください。

WhatsApp + TelegramチャネルにはNodeが必要です。Bunはサポートされていません。サービスがBunまたはバージョン管理されたNodeパスでインストールされた場合、openclaw doctorを実行してシステムNodeインストールに移行してください。

サンドボックスでスキルのAPIキーが欠落

症状: スキルはホストで動作するが、サンドボックスでAPIキーが欠落して失敗します。

理由: サンドボックス化されたexecはDocker内で実行され、ホストprocess.envを継承しません。

修正:

  • agents.defaults.sandbox.docker.envを設定(またはエージェントごとにagents.list[].sandbox.docker.env)
  • またはカスタムサンドボックスイメージにキーを焼き込む
  • 次にopenclaw sandbox recreate --agent <id>(または--all)を実行

サービスは実行中だがポートがリスニングしていない

サービスが実行中と報告されているのに、ゲートウェイポートで何もリスニングしていない場合、ゲートウェイがバインドを拒否した可能性があります。

「実行中」の意味

  • Runtime: runningは、スーパーバイザー(launchd/systemd/schtasks)がプロセスが生きていると考えていることを意味します。
  • RPC probeは、CLIが実際にゲートウェイWebSocketに接続してstatusを呼び出せたことを意味します。
  • 常にProbe target:+Config (service):を「実際に何を試したか?」の行として信頼してください。

チェック:

  • openclaw gatewayとサービスにはgateway.modeがlocalでなければなりません。
  • gateway.mode=remoteを設定した場合、CLIはデフォルトでリモートURLになります。サービスはまだローカルで実行されている可能性がありますが、CLIが間違った場所をプローブしている可能性があります。openclaw gateway statusを使用してサービスの解決されたポート+プローブターゲットを確認します(または--urlを渡します)。
  • openclaw gateway statusとopenclaw doctorは、サービスが実行中に見えるがポートが閉じている場合、ログから最後のゲートウェイエラーを表示します。
  • 非ループバックバインド(lan/tailnet/custom、またはループバックが利用できない場合のauto)には認証が必要です: gateway.auth.token(またはOPENCLAW_GATEWAY_TOKEN)。
  • gateway.remote.tokenはリモートCLI呼び出し専用です。ローカル認証を有効にしません。
  • gateway.tokenは無視されます。gateway.auth.tokenを使用してください。

openclaw gateway statusが設定の不一致を示す場合

  • Config (cli): ...とConfig (service): ...は通常一致する必要があります。
  • 一致しない場合、サービスが別の設定を実行している間に1つの設定を編集している可能性がほぼ確実です。
  • 修正: サービスに使用させたい--profile / OPENCLAW_STATE_DIRからopenclaw gateway install --forceを再実行します。

openclaw gateway statusがサービス設定の問題を報告する場合

  • スーパーバイザー設定(launchd/systemd/schtasks)に現在のデフォルトが欠落しています。
  • 修正: openclaw doctorを実行して更新します(または完全な書き換えのためにopenclaw gateway install --force)。

Last gateway error:が「認証なしでバインドを拒否...」と記載している場合

  • gateway.bindを非ループバックモード(lan/tailnet/custom、またはループバックが利用できない場合のauto)に設定しましたが、認証を設定しませんでした。
  • 修正: gateway.auth.mode + gateway.auth.tokenを設定(またはOPENCLAW_GATEWAY_TOKENをエクスポート)し、サービスを再起動します。

openclaw gateway statusがbind=tailnetだがtailnetインターフェースが見つからなかったと言う場合

  • ゲートウェイはTailscale IP(100.64.0.0/10)にバインドしようとしましたが、ホストで検出されませんでした。
  • 修正: そのマシンでTailscaleを起動します(またはgateway.bindをloopback/lanに変更)。

Probe note:がプローブがループバックを使用すると言う場合

  • これはbind=lanの場合に予想されます: ゲートウェイは0.0.0.0(すべてのインターフェース)でリスニングし、ループバックでもローカル接続できるはずです。
  • リモートクライアントの場合、実際のLAN IP(不是0.0.0.0)とポートを使用し、認証が設定されていることを確認してください。

アドレスがすでに使用されています(ポート18789)

これは、何かがすでにゲートウェイポートでリスニングしていることを意味します。

チェック:

openclaw gateway status

リスナーと考えられる原因(ゲートウェイがすでに実行中、SSHトンネル)を表示します。 必要に応じて、サービスを停止するか、別のポートを選択してください。

追加のワークスペースフォルダが検出されました

古いインストールからアップグレードした場合、ディスク上に~/openclawがまだ残っている可能性があります。 複数のワークスペースディレクトリは、1つのワークスペースのみがアクティブであるため、認証や状態のドリフトを混乱させる可能性があります。

修正: 単一のアクティブワークスペースを保持し、残りをアーカイブ/削除します。エージェントワークスペースを参照してください。

メインチャットがサンドボックスワークスペースで実行されている

症状: pwdまたはファイルツールが~/.openclaw/sandboxes/...を表示しますが、ホストワークスペースを期待していました。

理由: agents.defaults.sandbox.mode: "non-main"はsession.mainKey(デフォルト"main")をキーにしています。 グループ/チャネルセッションは独自のキーを使用するため、非メインとして扱われ、サンドボックスワークスペースを取得します。

修正オプション:

  • エージェントにホストワークスペースが必要な場合: agents.list[].sandbox.mode: "off"を設定します。
  • サンドボックス内でホストワークスペースアクセスが必要な場合: そのエージェントにworkspaceAccess: "rw"を設定します。

"エージェントが中断されました"

エージェントが応答の途中で中断されました。

原因:

  • ユーザーがstop、abort、esc、wait、またはexitを送信した
  • タイムアウト超過
  • プロセスがクラッシュした

修正: 別のメッセージを送信するだけです。セッションは続行されます。

"返信前にエージェントが失敗しました: 不明なモデル: anthropic/claude-haiku-3-5"

OpenClawは意図的に古い/安全でないモデル(特にプロンプトインジェクションに対して脆弱なもの)を拒否します。このエラーが表示された場合、モデル名はサポートされなくなりました。

修正:

  • プロバイダーの最新モデルを選択し、設定またはモデルエイリアスを更新します。
  • どのモデルが利用可能かわからない場合は、openclaw models listまたはopenclaw models scanを実行し、サポートされているものを選択します。
  • 詳細な障害理由についてはゲートウェイログを確認してください。

関連項目: Models CLIとモデルプロバイダー。

メッセージがトリガーされない

チェック1: 送信者は許可リストに含まれていますか?

openclaw status

出力のAllowFrom: ...を探してください。

チェック2: グループチャットの場合、メンションは必要ですか?

# メッセージはmentionPatternsまたは明示的なメンションに一致する必要があります。デフォルトはチャネルグループ/ギルドにあります。
# マルチエージェント: `agents.list[].groupChat.mentionPatterns`がグローバルパターンをオーバーライドします。
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

チェック3: ログを確認

openclaw logs --follow
# またはクイックフィルタが必要な場合:
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

ペアリングコードが届かない

dmPolicyがpairingの場合、不明な送信者はコードを受信し、承認されるまでメッセージは無視されます。

チェック1: 保留中のリクエストがすでに待機していますか?

openclaw pairing list <channel>

保留中のDMペアリングリクエストは、デフォルトでチャネルごとに3つに制限されています。リストがいっぱいの場合、承認または期限切れまで新しいリクエストはコードを生成しません。

チェック2: リクエストは作成されたが返信が送信されなかったか?

openclaw logs --follow | grep "pairing request"

チェック3: そのチャネルのdmPolicyがopen/allowlistではないことを確認します。

画像+メンションが機能しない

既知の問題: 画像を(他のテキストなしで)メンションのみで送信すると、WhatsAppがメンションメタデータを含めないことがあります。

回避策: メンションと共にテキストを追加します:

  • ❌ @openclaw + 画像
  • ✅ @openclaw check this + 画像

セッションが再開されない

チェック1: セッションファイルはありますか?

ls -la ~/.openclaw/agents/<agentId>/sessions/

チェック2: リセットウィンドウが短すぎませんか?

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080  // 7日
    }
  }
}

チェック3: 誰かが/new、/reset、またはリセットトリガーを送信しましたか?

エージェントがタイムアウト

デフォルトのタイムアウトは30分です。長いタスクの場合:

{
  "reply": {
    "timeoutSeconds": 3600  // 1時間
  }
}

またはprocessツールを使用して長いコマンドをバックグラウンドで実行します。

WhatsAppが切断されました

# ローカルステータスを確認(認証情報、セッション、キューイベント)
openclaw status
# 実行中のゲートウェイ+チャネルをプローブ(WA接続 + Telegram + Discord API)
openclaw status --deep

# 最近の接続イベントを表示
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"

修正: 通常、Gatewayが実行されると自動的に再接続されます。行き詰まった場合は、Gatewayプロセスを再起動します(管理方法に応じて)、または詳細出力で手動で実行します:

openclaw gateway --verbose

ログアウト/リンク解除された場合:

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # ログアウトがすべてをクリーンに削除できない場合
openclaw channels login --verbose       # QRを再スキャン

メディア送信が失敗

チェック1: ファイルパスは有効ですか?

ls -la /path/to/your/image.jpg

チェック2: 大きすぎませんか?

  • 画像: 最大6MB
  • オーディオ/ビデオ: 最大16MB
  • ドキュメント: 最大100MB

チェック3: メディアログを確認

grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

高メモリ使用量

OpenClawは会話履歴をメモリに保持します。

修正: 定期的に再起動するか、セッション制限を設定します:

{
  "session": {
    "historyLimit": 100  // 保持する最大メッセージ数
  }
}

一般的なトラブルシューティング

"ゲートウェイが起動しません — 設定が無効です"

OpenClawは、設定に不明なキー、不正な形式の値、または無効な型が含まれている場合、起動を拒否するようになりました。 これは安全性のために意図的です。

Doctorで修正:

openclaw doctor
openclaw doctor --fix

注意:

  • openclaw doctorはすべての無効なエントリを報告します。
  • openclaw doctor --fixはマイグレーション/修復を適用し、設定を書き換えます。
  • openclaw logs、openclaw health、openclaw status、openclaw gateway status、openclaw gateway probeなどの診断コマンドは、設定が無効でも実行されます。

"すべてのモデルが失敗しました" — 最初に何を確認すべきですか?

  • 試行されているプロバイダーの認証情報が存在する(認証プロファイル + 環境変数)。
  • モデルルーティング: agents.defaults.model.primaryとフォールバックがアクセス可能なモデルであることを確認します。
  • /tmp/openclaw/…のゲートウェイログで正確なプロバイダーエラーを確認します。
  • モデルステータス: /model status(チャット)またはopenclaw models status(CLI)を使用します。

個人のWhatsApp番号で実行しています — なぜセルフチャットがおかしいのですか?

セルフチャットモードを有効にし、自分の番号を許可リストに追加します:

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"]
    }
  }
}

WhatsAppセットアップを参照してください。

WhatsAppがログアウトしました。再認証する方法は?

ログインコマンドを再度実行し、QRコードをスキャンします:

openclaw channels login

mainでのビルドエラー — 標準的な修正パスは?

  1. git pull origin main && pnpm install
  2. openclaw doctor
  3. GitHubの問題またはDiscordを確認
  4. 一時的な回避策: 古いコミットをチェックアウト

npm installが失敗(allow-build-scripts / tarまたはyargsがない)。どうすればいい?

ソースから実行している場合は、リポジトリのパッケージマネージャーを使用してください: pnpm(推奨)。 リポジトリはpackageManager: "pnpm@…"を宣言しています。

典型的な復旧:

git status   # リポジトリルートにいることを確認
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

理由: pnpmはこのリポジトリの設定されたパッケージマネージャーです。

gitインストールとnpmインストールを切り替える方法は?

ウェブサイトインストーラーを使用し、フラグでインストール方法を選択します。既存のインストールをアップグレードし、新しいインストールを指すようにゲートウェイサービスを書き換えます。

gitインストールに切り替え:

curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git --no-onboard

npmグローバルに切り替え:

curl -fsSL https://openclaw.bot/install.sh | bash

注意:

  • gitフローは、リポジトリがクリーンな場合にのみリベースします。最初に変更をコミットまたはスタッシュします。
  • 切り替え後、以下を実行します: 
    openclaw doctor
openclaw gateway restart

Telegramブロックストリーミングがツール呼び出し間でテキストを分割していません。なぜ?

ブロックストリーミングは完了したテキストブロックのみを送信します。単一のメッセージが表示される一般的な理由:

  • agents.defaults.blockStreamingDefaultがまだ"off"です。
  • channels.telegram.blockStreamingがfalseに設定されています。
  • channels.telegram.streamModeがpartialまたはblockでドラフトストリーミングがアクティブ(プライベートチャット+トピック)。この場合、ドラフトストリーミングがブロックストリーミングを無効にします。
  • minChars / coalesce設定が高すぎるため、チャンクがマージされます。
  • モデルが1つの大きなテキストブロックを出力(応答中のフラッシュポイントなし)。

修正チェックリスト:

  1. ブロックストリーミング設定をagents.defaultsの下に配置し、ルートには配置しない。
  2. 実際のマルチメッセージブロック返信が必要な場合は、channels.telegram.streamMode: "off"を設定します。
  3. デバッグ中は小さいチャンク/coalesceしきい値を使用します。

ストリーミングを参照してください。

DiscordがrequireMention: falseでもサーバーで返信しません。なぜ?

requireMentionは、チャネルが許可リストを通過した後のメンションゲートのみを制御します。 デフォルトではchannels.discord.groupPolicyはallowlistなので、ギルドを明示的に有効にする必要があります。 channels.discord.guilds.<guildId>.channelsを設定した場合、リストされたチャネルのみが許可されます。ギルド内のすべてのチャネルを許可するには省略します。

修正チェックリスト:

  1. channels.discord.groupPolicy: "open"を設定またはギルド許可リストエントリを追加(オプションでチャネル許可リスト)。
  2. channels.discord.guilds.<guildId>.channelsで数値チャネルIDを使用します。
  3. requireMention: falseをchannels.discord.guildsの下に配置(グローバルまたはチャネルごと)。 トップレベルのchannels.discord.requireMentionはサポートされているキーではありません。
  4. ボットにMessage Content Intentとチャネル権限があることを確認します。
  5. 監査ヒントについてはopenclaw channels status --probeを実行します。

ドキュメント: Discord、チャネルトラブルシューティング。

Cloud Code Assist APIエラー: 無効なツールスキーマ(400)。どうすればいい?

これはほとんど常にツールスキーマ互換性の問題です。Cloud Code Assistエンドポイントは、JSON Schemaの厳密なサブセットを受け入れます。OpenClawは現在のmainでツールスキーマをスクラブ/正規化しますが、修正はまだ最後のリリースに含まれていません(2026年1月13日時点)。

修正チェックリスト:

  1. OpenClawを更新:
    • ソースから実行できる場合は、mainをプルしてゲートウェイを再起動します。
    • それ以外の場合は、スキーマスクラバーを含む次のリリースを待ちます。
  2. anyOf/oneOf/allOf、patternProperties、additionalProperties、minLength、maxLength、formatなどのサポートされていないキーワードを避けます。
  3. カスタムツールを定義する場合は、トップレベルスキーマをtype: "object"とpropertiesおよびシンプルな列挙型に保ちます。

ツールとTypeBoxスキーマを参照してください。

macOS固有の問題

権限を付与するとアプリがクラッシュ(音声/マイク)

プライバシープロンプトで「許可」をクリックしたときにアプリが消えるか「Abort trap 6」が表示される場合:

修正1: TCCキャッシュをリセット

tccutil reset All bot.molt.mac.debug

修正2: 新しいバンドルIDを強制 リセットが機能しない場合は、scripts/package-mac-app.shのBUNDLE_IDを変更し(例: .testサフィックスを追加)、リビルドします。これにより、macOSがそれを新しいアプリとして扱うように強制します。

ゲートウェイが「起動中...」で停止

アプリはポート18789のローカルゲートウェイに接続します。停止したままの場合:

修正1: スーパーバイザーを停止(推奨) ゲートウェイがlaunchdによって管理されている場合、PIDをキルしても再生成されるだけです。最初にスーパーバイザーを停止します:

openclaw gateway status
openclaw gateway stop
# または: launchctl bootout gui/$UID/bot.molt.gateway (bot.molt.<profile>に置き換え。レガシーcom.openclaw.*はまだ機能します)

修正2: ポートがビジー(リスナーを見つける)

lsof -nP -iTCP:18789 -sTCP:LISTEN

管理されていないプロセスの場合は、最初に正常な停止を試み、その後エスカレートします:

kill -TERM <PID>
sleep 1
kill -9 <PID> # 最後の手段

修正3: CLIインストールを確認 グローバルopenclaw CLIがインストールされ、アプリバージョンと一致していることを確認します:

openclaw --version
npm install -g openclaw@<version>

デバッグモード

詳細ログを取得:

# 設定でトレースログをオンにする:
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# 次に詳細コマンドを実行してデバッグ出力をstdoutにミラーリング:
openclaw gateway --verbose
openclaw channels login --verbose

ログの場所

ログ場所
ゲートウェイファイルログ(構造化)/tmp/openclaw/openclaw-YYYY-MM-DD.log(またはlogging.file)
ゲートウェイサービスログ(スーパーバイザー)macOS: $OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log(デフォルト: ~/.openclaw/logs/...。プロファイルは~/.openclaw-<profile>/logs/...を使用)
Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
セッションファイル$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
メディアキャッシュ$OPENCLAW_STATE_DIR/media/
認証情報$OPENCLAW_STATE_DIR/credentials/

ヘルスチェック

# スーパーバイザー + プローブターゲット + 設定パス
openclaw gateway status
# システムレベルスキャンを含む(レガシー/追加サービス、ポートリスナー)
openclaw gateway status --deep

# ゲートウェイに到達可能か?
openclaw health --json
# 失敗した場合、接続詳細で再実行:
openclaw health --verbose

# デフォルトポートで何かがリスニングしているか?
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 最近のアクティビティ(RPCログテール)
openclaw logs --follow
# RPCがダウンしている場合のフォールバック
tail -20 /tmp/openclaw/openclaw-*.log

すべてをリセット

核オプション:

openclaw gateway stop
# サービスをインストールしていてクリーンインストールが必要な場合:
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # WhatsAppを再ペアリング
openclaw gateway restart           # または: openclaw gateway

⚠️ これはすべてのセッションを失い、WhatsAppの再ペアリングが必要です。

ヘルプを得る

  1. 最初にログを確認: /tmp/openclaw/(デフォルト: openclaw-YYYY-MM-DD.log、または設定したlogging.file)
  2. GitHubの既存の問題を検索
  3. 以下を含む新しい問題を開く:
    • OpenClawバージョン
    • 関連するログスニペット
    • 再現手順
    • あなたの設定(シークレットをリダクト!)

「オフにしてからオンにしてみましたか?」 — すべてのIT担当者

🦞🔧

ブラウザが起動しない(Linux)

"Failed to start Chrome CDP on port 18800"が表示される場合:

最も可能性の高い原因: UbuntuのSnapパッケージChromium。

クイック修正: 代わりにGoogle Chromeをインストール:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

次に設定で設定:

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

完全ガイド: browser-linux-troubleshootingを参照

← ドキュメントに戻る