openclaw-debugging

OpenClaw のデバッグ

ローカルテスト、実際のモデル、プロバイダー、コードモード、Tool Search、Crabbox、CI で動作が異なる場合は、推測する前にデバッグ情報を取得してください。

まず読むもの

• docs/logging.md：ログファイル、openclaw logs、対象を絞ったデバッグフラグ。
• docs/reference/test.md：ローカルテストのコマンド。
• docs/tools/code-mode.md：コードモードの exec/wait とツールカタログのルール。
• $openclaw-testing：テストレーンの選択。
• $crabbox：幅広い検証、Docker、パッケージ、Linux、実際のキー、CI との同等性を確認する証拠。

デフォルトの手順

1. 疑わしい境界を明確にします：設定、ツール構築、プロバイダーのペイロード、fetch、 ストリーム/SSE、トランスクリプトの再生、ワーカー/ランタイム、パッケージ/dist、CI。
2. その境界を証明できる最小限の情報を追加または有効にします。
3. 同じプロバイダー/モデル/設定で再現します。モデル自体を検証対象にする場合を除き、 モデルを無作為に切り替えないでください。
4. 設定状態と実際の実行時の有効化状態を比較します。
5. 根本原因を修正します。
6. 失敗したプローブを正確に再実行し、契約上必要な場合にのみ範囲を広げます。

モデルの通信ログ

モデルリクエストの形状やストリームのタイミングを確認するには、グローバルなデバッグより対象を絞った環境変数フラグを使います。

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

便利なフラグ：

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1：リクエスト開始、fetch の応答、SDK ヘッダー、最初の SSE イベント、ストリーム完了、通信エラーを info に記録します。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary：範囲を制限したペイロードの概要を記録します。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools：モデルに表示されるすべてのツール名を記録します。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted：上限を設け、機密情報を伏せた JSON ペイロードを記録します。 デバッグ中のみ使用してください。プロンプトやメッセージ本文が表示される場合があります。
• OPENCLAW_DEBUG_SSE=events：最初のイベントとストリーム完了のタイミングを記録します。
• OPENCLAW_DEBUG_SSE=peek：機密情報を伏せた最初の 5 件の SSE イベントを記録します。
• OPENCLAW_DEBUG_CODE_MODE=1：コードモードのツールサーフェスに関する診断情報を記録します。

ログを確認します：

openclaw logs --follow

よくある境界

• 設定と有効化： 有効な設定でも、実行時のツールが無効、raw run、許可リストが空、 モデルがツールをサポートしていない、といった状態が併存する場合があります。プロバイダーのペイロードに関する不変条件を適用する前に、実際に表示される ツールを確認してください。
• ツールサーフェス： レジストリ/設定だけでなく、最終的にモデルに表示されるツール名を確認してください。コードモードで exec と wait のみになるのは、 実際に有効化された後です。
• プロバイダーのペイロード： SDK の呼び出し前に、フィールド、モデル ID、サービス階層、 推論、入力サイズ、メタデータキー、プロンプトキャッシュキーの有無、ツール名を記録します。
• fetch と SSE： fetch の応答は HTTP ヘッダーの到着を示します。最初の SSE イベントはプロバイダーの本文が進行したことを示します。この間に遅延がある場合は、 ツールの実行ではなく、ストリーム/本文/プロバイダーの問題です。
• ワーカー/dist： ワーカー、動的インポート、パッケージのエクスポート、遅延ランタイムの境界、公開パスに触れた場合は、pnpm build を実行します。
• 実際のキー： プロバイダーキーがない場合は、実際の検証がブロックされていると判断する前に、設定済みのシークレットワークフローを実行します。環境変数の確認は存在の有無に限定し、シークレットを表示しないでください。

セッションとトランスクリプトの取得

チャットセッションのバグ報告：実際のトランスクリプト、送信者の帰属、 証拠となる添付ファイルを取得します。

まず CLI を使用します（インストールの設定が必要です。稼働中のゲートウェイに影響しません）。

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

ドキュメント：ストアのレイアウトは docs/reference/database-schemas.md、 CLI は https://docs.openclaw.ai/cli/sessions を参照してください。

未加工のストア：CLI が使用できない場合（例：SSH 経由のリモートホスト）、またはイベントレベルの詳細が必要な場合：

• エージェントごとのデータプレーン：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。 正式なスキーマ：src/state/openclaw-agent-schema.sql。
• ホスト環境／systemd の状態：root ではなく、サービスユーザーのホーム（例：/home/openclaw/.openclaw/...）にあります。
  root に別のエージェントが存在する、無関係なインストールがある場合もあります。 想定されるエージェントディレクトリが見つからない場合は、次のコマンドで実際の DB を探します。 find / -maxdepth 6 -name openclaw-agent.sqlite
• Web チャットの URL にあるセッション ID のフラグメント：/chat/<agentId>/<slug>-<hex>。 session_nodes で解決します：session_key LIKE '%<hex>%' → current_session_id、display_name。キーの形式： agent:<agentId>:<surface>:<uuid>。サブエージェントのセッションでは surface に subagent を使用します。
• トランスクリプト：transcript_events（session_id、seq、event_json）。 event_json.message：role（user／assistant／toolResult）と content（文字列、または text／toolCall／image 型のパーツ）。
• 送信者の出所情報：実際のユーザーメッセージには message.__openclaw （senderId、senderName、senderIsOwner）が含まれますが、ランタイムが合成した入力には含まれません。 これを使って、オペレーターが作成したテキストと挿入されたプロンプトを区別します。
• トランスクリプトの全文検索：session_transcript_fts。
• 添付ファイル：media://inbound/<file> URL → <state-dir>/media/inbound/<file>。
• ユーザーが添付した画像は image コンテンツパーツとは異なります。メッセージエンベロープには message.__openclaw.media[] エントリが含まれます：url（media://inbound/<file>）、 contentType、kind、fileName。パーツのみを対象とする抽出では、画像をすべて見落とします。 未加工の event_json を media:// で grep してください。リモートホストの場合は、ファイルをローカルに scp でコピーします （scp 引数ごとにリモートパスを 1 つ指定）。そこで読み取ります。

sqlite3 バイナリがないホストでも Node は使えます：node:sqlite に依存関係は不要です。

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <db-path> <session-id>

• 稼働中のストアは必ず readOnly: true で開きます。稼働中のゲートウェイの状態には書き込みません （root の AGENTS.md の検証ルール）。
• 実データを使った作業では、まず DB を開発用の状態ディレクトリにコピーします。

コードの参照箇所

• モデルのペイロードと Responses ストリーム： src/agents/openai-transport-stream.ts
• ガード付きフェッチ／タイミング： src/agents/provider-transport-fetch.ts
• OpenAI／Codex プロバイダーのラッパー： src/llm/providers/stream-wrappers/openai.ts
• ツールの構築、Tool Search、コードモードの有効化： src/agents/embedded-agent-runner/run/attempt.ts
• コードモードのランタイムとワーカー： src/agents/code-mode.ts src/agents/code-mode.worker.ts
• Tool Search カタログ： src/agents/tool-search.ts

検証方法の選択

• 単一のヘルパー／ペイロードのバグ：対象を絞ったローカルの Vitest。
• ドキュメント／ログのみ：pnpm check:docs + git diff --check。
• Worker／dist／遅延インポート／パッケージのインターフェース：対象を絞ったテスト + pnpm build。
• 実際のプロバイダー／モデルの動作：同じプロバイダー／モデル、デバッグフラグ、利用可能であれば実際のキーを使用。
• Docker／パッケージ／Linux／CI との同等性：対応可能な場合は、現在の専用 Linux ワーカーを使用。それ以外の場合は $crabbox。
• CI の失敗：正確な SHA、関連するジョブのみ。ログは失敗／完了後に限り確認します。

出力時の習慣

次の内容を報告します。

• テストした境界
• 正確なコマンド／環境変数の形式（値は秘匿）
• 観測されたシグナル（例：ツール名、または最初の SSE イベントまでの時間）
• 修正箇所
• 対象を絞った検証と残るリスク