OpenClawデバッグ

OpenClawデバッグ は何をしますか？

動作はローカルテスト、ライブモデル、プロバイダ、コードモード、ツール検索、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. 疑わしい境界を特定する: 設定、ツール構築、プロバイダペイロード、フェッチ、ストリーム/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: リクエスト開始、フェッチ応答、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

よくある境界

• 設定とアクティベーション: 有効な設定は、無効な実行ツール、素の実行、空の許可リスト、欠落したモデルツールサポートと共存できます。プロバイダペイロードの不変条件を強制する前に、実際に可視のツールを確認してください。
• ツールサーフェス: レジストリ/設定だけでなく、最終的なモデル可視ツール名を検査します。コードモードは、実際のアクティベーション後は正確にexec + waitのみです。
• プロバイダペイロード: SDK呼び出しの前に、フィールド、モデルID、サービス層、推論、入力サイズ、メタデータキー、プロンプトキャッシュキーの有無、ツール名をログに記録します。
• フェッチとSSE: フェッチ応答は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状態: サービスユーザーのホームディレクトリ（例: /home/openclaw/.openclaw/...）、 ルートではない。ルートは別のエージェントを持つ別のインストールがある場合があります。 予期されるエージェントディレクトリが見つからない場合: 実際の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>; サブエージェントセッションは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を直接grepしてmedia://を探します。リモートホスト: 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で開くこと。実行中のゲートウェイの状態に書き込まないこと （ルート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
• ツール構築、ツール検索、コードモードアクティベーション: src/agents/embedded-agent-runner/run/attempt.ts
• コードモードランタイムとワーカー: src/agents/code-mode.ts src/agents/code-mode.worker.ts
• ツール検索カタログ: src/agents/tool-search.ts

証明の選択

• 単一ヘルパー/ペイロードバグ: ローカルターゲットのVitest。
• ドキュメント/ログのみ: pnpm check:docs + git diff --check。
• ワーカー/dist/遅延インポート/パッケージサーフェス: ターゲットテスト + pnpm build。
• ライブプロバイダ/モデル動作: 同じプロバイダ/モデル、デバッグフラグ、可能であれば実際のキー。
• Docker/パッケージ/Linux/CIパリティ: 可能な場合は現在の専用Linuxワーカーを使用; そうでなければ$crabbox。
• CI障害: 正確なSHA、関連ジョブのみ; ログは障害/完了後にのみ。

出力の習慣

報告:

• テストした境界
• 正確なコマンド/envの形状（編集済み）
• 観測されたシグナル（例: ツール名または最初のSSEイベントのタイミング）
• 修正箇所
• 狭い証明と残存リスク