轉錄衛生（供應商修正）

本文件描述在執行前（建構模型上下文時）套用至轉錄的供應商專屬修正。這些是記憶體內的調整，用於滿足嚴格的供應商要求。這些衛生步驟不會改寫磁碟上儲存的 JSONL 轉錄；但在 session 載入前，另一個 session 檔案修復步驟可能會透過丟棄無效行來改寫格式錯誤的 JSONL 檔案。修復發生時，原始檔案會備份在 session 檔案旁邊。

範圍包含：

工具呼叫 id 清理
工具呼叫輸入驗證
工具結果配對修復
回合驗證 / 排序
思考簽名清理
圖片 payload 清理
使用者輸入出處標記（用於跨 session 路由的 prompt）

若需要轉錄儲存細節，參見：

/reference/session-management-compaction

執行位置

所有轉錄衛生集中在嵌入式 runner：

策略選擇：src/agents/transcript-policy.ts
清理/修復套用：src/agents/pi-embedded-runner/google.ts 中的 sanitizeSessionHistory

策略使用 provider、modelApi 和 modelId 決定要套用什麼。

獨立於轉錄衛生，session 檔案在載入前進行修復（若需要）：

src/agents/session-file-repair.ts 中的 repairSessionFileIfNeeded
從 run/attempt.ts 和 compact.ts（嵌入式 runner）呼叫

全域規則：圖片清理

圖片 payload 一律清理，防止因大小限制導致的供應商端拒絕（縮小/重新壓縮過大的 base64 圖片）。

這也有助於控制支援視覺的模型中由圖片驅動的 token 壓力。較低的最大尺寸通常減少 token 使用；較高的尺寸保留細節。

實作：

src/agents/pi-embedded-helpers/images.ts 中的 sanitizeSessionMessagesImages
src/agents/tool-images.ts 中的 sanitizeContentBlocksImages
最大圖片邊長可透過 agents.defaults.imageMaxDimensionPx（預設：1200）設定。

全域規則：格式錯誤的工具呼叫

缺少 input 和 arguments 的助理工具呼叫區塊在建構模型上下文前被丟棄。這防止部分持久化的工具呼叫（例如速率限制失敗後）導致供應商拒絕。

實作：

src/agents/session-transcript-repair.ts 中的 sanitizeToolCallInputs
在 src/agents/pi-embedded-runner/google.ts 的 sanitizeSessionHistory 中套用

全域規則：跨 session 輸入出處

當代理透過 sessions_send（包含代理對代理的回覆/公告步驟）將 prompt 傳送至另一個 session 時，OpenClaw 持久化建立的使用者回合搭配：

message.provenance.kind = "inter_session"

此中繼資料在轉錄附加時寫入，不改變角色（role: "user" 保持不變以供供應商相容）。轉錄讀取者可用此避免將路由的內部 prompt 視為終端使用者撰寫的指示。

在上下文重建期間，OpenClaw 也在記憶體中為那些使用者回合前置簡短的 [Inter-session message] 標記，讓模型可區分它們與外部終端使用者指示。

供應商矩陣（目前行為）

OpenAI / OpenAI Codex

僅圖片清理。
丟棄孤立的推理簽名（無後續內容區塊的獨立推理項目），適用於 OpenAI Responses/Codex 轉錄。
不做工具呼叫 id 清理。
不做工具結果配對修復。
不做回合驗證或重排序。
不做合成工具結果。
不做思考簽名去除。

Google（Generative AI / Gemini CLI / Antigravity）

工具呼叫 id 清理：嚴格英數。
工具結果配對修復和合成工具結果。
回合驗證（Gemini 風格的回合交替）。
Google 回合排序修正（歷史以助理開始時前置一個微小的使用者啟動訊息）。
Antigravity Claude：正規化思考簽名；丟棄未簽名的思考區塊。

Anthropic / Minimax（Anthropic 相容）

工具結果配對修復和合成工具結果。
回合驗證（合併連續使用者回合以滿足嚴格交替）。

Mistral（包含基於 model-id 的偵測）

工具呼叫 id 清理：strict9（英數長度 9）。

OpenRouter Gemini

思考簽名清理：去除非 base64 的 thought_signature 值（保留 base64）。

其他一切

僅圖片清理。

歷史行為（2026.1.22 以前）

在 2026.1.22 發布前，OpenClaw 套用多層轉錄衛生：

轉錄清理擴充套件在每次上下文建構時執行，可以：
- 修復工具 use/result 配對。
- 清理工具呼叫 id（包含保留 _/- 的非嚴格模式）。
Runner 也執行供應商專屬清理，造成工作重複。
額外的變異發生在供應商策略之外，包含：
- 持久化前從助理文字去除 <final> 標籤。
- 丟棄空的助理錯誤回合。
- 在工具呼叫後裁剪助理內容。

這種複雜性導致跨供應商的回歸（特別是 openai-responses 的 call_id|fc_id 配對）。2026.1.22 清理移除了擴充套件、集中邏輯至 runner，並讓 OpenAI 在圖片清理以外不做觸碰。