Technical reference

トランスクリプトの衛生管理

OpenClaw は実行前（モデルコンテキストの構築時）に、トランスクリプトへプロバイダー固有の修正を適用します。その大半は、厳格なプロバイダー要件を満たすためのメモリ内調整です。これとは別に、セッションの読み込み前にセッションファイル修復処理が保存済み JSONL を書き換える場合もありますが、対象は不正な行、または永続的な記録として無効な保存済みターンに限られます。配信済みのアシスタント応答はディスク上に保持されます。プロバイダー固有のアシスタント事前入力の除去は、送信ペイロードの構築時にのみ行われます。

修復が行われる場合、アトミック置換の前に元のファイルが一時的な同階層ファイル *.bak-<pid>-<ts> へ書き込まれ、置換が成功すると削除されます。バックアップが保持されるのはクリーンアップ自体が失敗した場合のみで、その際はパスが報告されます。

対象範囲は次のとおりです。

実行時専用のプロンプトコンテキストを、ユーザーに表示されるトランスクリプトターンへ含めない
ツール呼び出し ID のサニタイズ
ツール呼び出し入力の検証
ツール結果のペアリング修復
ターンの検証／並べ替え
思考署名のクリーンアップ
Thinking 署名のクリーンアップ
画像ペイロードのサニタイズ
プロバイダーへの再送前に空のテキストブロックをクリーンアップ
プロバイダーへの再送前に、未完了の推論のみで構成された出力上限到達ターンをクリーンアップ
ユーザー入力の出所タグ付け（セッション間でルーティングされたプロンプト向け）
Bedrock Converse 再送用の空のアシスタントエラーターン修復

トランスクリプトの保存に関する詳細は、セッション管理の詳細を参照してください。

グローバルルール：実行時コンテキストはユーザートランスクリプトではない

実行時／システムコンテキストは、ターンのモデルプロンプトへ追加できますが、エンドユーザーが作成したコンテンツではありません。OpenClaw は、Gateway 応答、キューに入れられたフォローアップ、ACP、CLI、および埋め込み OpenClaw 実行のために、トランスクリプト向けのプロンプト本文を別途保持します。保存される表示可能なユーザーターンには、実行時情報で拡張されたプロンプトではなく、このトランスクリプト本文が使用されます。

実行時ラッパーがすでに保存されている旧形式のセッションでは、Gateway の履歴サーフェスが WebChat、TUI、REST、または SSE クライアントへメッセージを返す前に、表示用のプロジェクションを適用します。

実行箇所

トランスクリプトの健全性維持処理は、すべて埋め込みランナーに集約されています。

ポリシーの選択：src/agents/transcript-policy.ts （provider、modelApi、modelId をキーとする resolveTranscriptPolicy）
サニタイズ／修復の適用： src/agents/embedded-agent-runner/replay-history.ts の sanitizeSessionHistory

トランスクリプトの健全性維持処理とは別に、必要に応じてセッションファイルが読み込み前に修復されます。

src/agents/session-file-repair.ts の repairSessionFileIfNeeded
src/agents/embedded-agent-runner/run/attempt.ts および src/agents/embedded-agent-runner/compact.ts から呼び出される

グローバルルール：画像のサニタイズ

サイズ制限によるプロバイダー側の拒否を防ぐため、画像ペイロードは常にサニタイズされます（サイズ超過の base64 画像を縮小／再圧縮します）。これは、画像対応モデルで画像によるトークン負荷を制御するうえでも役立ちます。最大寸法を小さくするとトークン使用量が減り、大きくすると詳細が保持されます。

実装：

src/agents/embedded-agent-helpers/images.ts の sanitizeSessionMessagesImages
src/agents/tool-images.ts の sanitizeContentBlocksImages
画像の最大辺は agents.defaults.imageMaxDimensionPx で設定可能（デフォルト：1200）
この処理で再送コンテンツを走査する際、空のテキストブロックも削除されます。その結果、空になったアシスタントターンは再送用コピーから除外されます。空になったユーザーターンとツール結果ターンには、空ではないコンテンツ省略プレースホルダーが設定されます。

グローバルルール：不正なツール呼び出し

input と arguments の両方が欠けているアシスタントのツール呼び出しブロックは、モデルコンテキストの構築前に除外されます。これにより、一部だけ保存されたツール呼び出し（たとえば、レート制限エラー後）によるプロバイダーの拒否を防ぎます。

実装：

src/agents/session-transcript-repair.ts の sanitizeToolCallInputs
sanitizeSessionHistory （src/agents/embedded-agent-runner/replay-history.ts）で適用

グローバルルール：未完了の推論のみのターン

Thinking または秘匿化された Thinking コンテンツだけを含む状態でプロバイダーの出力上限に達したアシスタントターンは、メモリ内の再送用コピーから除外されます。このようなターンには未完了のプロバイダー状態が含まれ、部分的な Thinking 署名を保持している可能性があります。

空の出力上限到達ターンは変更されません。表示可能なテキスト、ツール呼び出し、または不明なコンテンツブロックを含む出力上限到達ターンも同様です。保存済みトランスクリプトは書き換えられません。

実装：src/agents/embedded-agent-runner/replay-history.ts の normalizeAssistantReplayContent

グローバルルール：セッション間入力の出所

エージェントが sessions_send を介して別のセッションへプロンプトを送信する場合（エージェント間の応答／通知ステップを含む）、OpenClaw は作成されたユーザーターンを message.provenance.kind = "inter_session" として保存します。

OpenClaw は、ルーティングされたプロンプトテキストの前に、同じターン内の [Inter-session message] ... isUser=false マーカーも付加します。これにより、実行中のモデル呼び出しは、別セッションからの出力と外部エンドユーザーからの指示を区別できます。このマーカーには、利用可能な場合、送信元セッション、チャンネル、ツールが含まれます。プロバイダーとの互換性のため、トランスクリプトでは引き続き role: "user" を使用しますが、表示テキストと出所メタデータの両方で、そのターンがセッション間データであることを示します。

コンテキストの再構築時には、出所メタデータしか持たない古い保存済みのセッション間ユーザーターンにも、OpenClaw が同じマーカーを適用します。

プロバイダー対応表（現在の動作）

OpenAI / OpenAI Codex

画像のサニタイズのみ。
OpenAI Responses／Codex のトランスクリプトでは、孤立した推論署名（後続のコンテンツブロックがない独立した推論項目）を除外し、モデルのルート切り替え後には再送可能な OpenAI の推論も除外します。
暗号化された空の要約項目を含め、再送可能な OpenAI Responses の推論項目ペイロードを保持します。これにより、手動／WebSocket 再送時に必要な rs_* 状態とアシスタント出力項目のペアリングが維持されます。
ネイティブの ChatGPT Codex Responses は、セッションの prompt_cache_key を保持しつつ、以前の項目 ID を含めずに過去の Responses の推論／メッセージ／関数ペイロードを再送することで、Codex の通信形式との同等性を保ちます。
OpenAI Responses 系の再送では、同一モデルの正規の call_*|fc_* 推論ペアを保持しますが、不正または長すぎる call_id／関数呼び出し項目 ID は、pi-ai ペイロードへの変換前に決定論的に正規化します。
ツール結果のペアリング修復では、実際に一致した出力を移動し、不足しているツール呼び出しに対して Codex 形式の aborted 出力を合成する場合があります。
ターンの検証や並べ替えは行いません。思考署名も除去しません。

OpenAI 互換 Chat Completions

ローカルおよびプロキシ形式の OpenAI 互換サーバーへ reasoning や reasoning_content などの過去ターンの推論フィールドを送信しないよう、履歴内のアシスタントの Thinking／推論ブロックは再送前に除去されます。
現在の同一ターン内のツール呼び出し継続では、ツール結果が再送されるまで、アシスタントの推論ブロックをツール呼び出しに付加したままにします。
reasoning: true が設定されたカスタム／セルフホストのモデルエントリでは、再送された推論メタデータを保持します。
通信プロトコルで推論メタデータの再送が必要な場合、プロバイダー所有の例外によってこの処理を無効化できます。

Google（Generative AI / Gemini CLI / Antigravity）

ツール呼び出し ID のサニタイズ：厳密な英数字。
ツール結果のペアリング修復と合成ツール結果。
ターンの検証（Gemini 形式のターン交互化）。
Google のターン順序修正（履歴がアシスタントから始まる場合、小さなユーザー初期化ターンを先頭に追加）。
Antigravity Claude：Thinking 署名を正規化し、署名のない Thinking ブロックを除外。

Anthropic / Minimax（Anthropic 互換）

ツール結果のペアリング修復と合成ツール結果。
ターンの検証（厳密な交互化を満たすため、連続するユーザーターンを統合）。
Thinking が有効な場合、末尾のアシスタント事前入力ターンは送信する Anthropic Messages ペイロードから除去されます。Cloudflare AI Gateway 経由のルートも対象です。
セッションが Compaction 済みの場合、Compaction 前のアシスタント Thinking 署名はプロバイダーへの再送前に除去されます。Thinking 署名は生成時の会話プレフィックスへ暗号学的に結び付けられています。Compaction 後はプレフィックスが変化し（元の内容が要約された内容に置き換わるため）、元の署名を再送すると Anthropic は「Invalid signature in thinking block」というエラーでリクエストを拒否します。Thinking テキストは署名なしブロックとして保持され、その後、次のルールで処理されます。
再送用署名が欠落、空、または空白のみの Thinking ブロックは、プロバイダー形式への変換前に除去されます。その結果アシスタントターンが空になる場合、OpenClaw は空ではない推論省略テキストを設定してターンの形式を維持します。
除去が必要な古い Thinking のみのアシスタントターンは、プロバイダーアダプターが再送ターンを除外しないよう、空ではない推論省略テキストへ置き換えられます。

Amazon Bedrock（Converse API）

空のアシスタントストリームエラーターンは、再送前に空ではないフォールバックテキストブロックへ修復されます。Bedrock Converse は content: [] のアシスタントメッセージを拒否するため、stopReason: "error" かつコンテンツが空の保存済みアシスタントターンも、読み込み前にディスク上で修復されます。
空白のみのテキストブロックしか含まないアシスタントストリームエラーターンは、無効な空白ブロックを再送する代わりに、メモリ内の再送用コピーから除外されます。
セッションが Compaction 済みの場合、Anthropic と同じ理由により、Compaction 前のアシスタント Thinking 署名は Converse への再送前に除去されます。
再送用署名が欠落、空、または空白のみの Claude Thinking ブロックは、Converse への再送前に除去されます。その結果アシスタントターンが空になる場合、OpenClaw は空ではない推論省略テキストを設定してターンの形式を維持します。
除去が必要な古い Thinking のみのアシスタントターンは、Converse の再送で厳密なターン形式を維持できるよう、空ではない推論省略テキストへ置き換えられます。
再送時には、OpenClaw の配信ミラーターンと Gateway が挿入したアシスタントターンを除外します。
グローバルルールに従って画像のサニタイズを適用します。

Mistral（モデル ID に基づく検出を含む）

ツール呼び出し ID のサニタイズ：strict9（英数字、長さ 9）。

OpenRouter Gemini

思考署名のクリーンアップ：base64 ではない thought_signature 値を除去します（base64 は保持）。

OpenRouter Anthropic

推論が有効な場合、検証済みの OpenRouter OpenAI 互換 Anthropic モデルペイロードから、末尾のアシスタント事前入力ターンを除去します。これは、Anthropic への直接接続および Cloudflare Anthropic の再送動作と一致します。

その他すべて

画像のサニタイズのみ。

過去の動作（2026.1.22 より前）

2026.1.22 リリースより前の OpenClaw は、複数層のトランスクリプト健全性維持処理を適用していました。

トランスクリプトサニタイズ拡張機能がコンテキスト構築のたびに実行され、次の処理を行うことができました。
- ツール使用／結果のペアリングを修復。
- ツール呼び出し ID をサニタイズ（_／- を保持する非厳密モードを含む）。
ランナーもプロバイダー固有のサニタイズを実行していたため、処理が重複していました。
プロバイダーポリシーの外部でも追加の変更が行われていました。これには、永続化前のアシスタントテキストからの <final> タグ除去、空のアシスタントエラーターンの除外、ツール呼び出し後のアシスタントコンテンツの切り詰めが含まれていました。

この複雑さにより、プロバイダーをまたぐリグレッション（特に openai-responses の call_id|fc_id ペアリング）が発生しました。2026.1.22 のクリーンアップでは、この拡張機能を削除してロジックをランナーへ集約し、OpenAI に対しては画像のサニタイズを除き無変更としました。