Transcript Hygiene 處理機制：搞定不同 Provider 的格式癖好
你是否有過這種經驗？在開發 AI 應用時，同樣的對話邏輯在 OpenAI 跑得好好的，換到 Gemini 或 Claude 就因為格式不符直接報錯。每個 Provider 對於對話順序、Tool ID 格式、甚至是圖片大小都有各自的「地雷」，手動處理這些瑣事既煩人又容易出錯。
這篇文章會告訴你系統如何透過 Transcript Hygiene 機制，在不改動原始存檔的情況下，自動幫你搞定這些 Provider 的特殊要求。
需要準備的東西
Section titled “需要準備的東西”- 核心 Policy 邏輯：
src/agents/transcript-policy.ts - Sanitization 實作：
src/agents/pi-embedded-runner/google.ts - 檔案修復邏輯：
src/agents/session-file-repair.ts - 圖片處理工具：
src/agents/tool-images.ts
Transcript Hygiene 是一套在記憶體中執行的修正程序，它發生在建立 Model Context 之前。這意味著你的磁碟 JSONL 檔案不會被隨意改寫，只有在載入模型前才會即時調整內容。
- 自動修復損壞檔案：在 Session 載入前，
repairSessionFileIfNeeded會檢查 JSONL，丟棄無效行並備份原檔。 - 決定修正策略：系統會根據
provider、modelApi和modelId從transcript-policy.ts挑選適合的規則。 - 執行記憶體修正：透過
sanitizeSessionHistory處理 Tool Call ID 或對話順序。 - 圖片自動縮放：所有 Provider 都會經過圖片 Sanitization，防止 base64 圖片過大被拒絕。
無論你使用哪個 Provider，以下兩條規則都會生效：
- 圖片 Sanitization：自動重新壓縮或縮小過大的圖片，避免觸發 Provider 的 Size Limit。
- 清理殘缺的 Tool Calls：如果 Assistant 的 Tool Call 區塊少了
input或arguments（常見於 Rate Limit 失敗後的殘留），系統會直接丟棄該區塊。
Provider 修正矩陣
Section titled “Provider 修正矩陣”Google (Gemini / Antigravity)
Section titled “Google (Gemini / Antigravity)”- Tool ID 限制：強制轉換為嚴格的英數組合（Alphanumeric）。
- 對話順序修正：確保符合 Gemini 的輪流對話（Turn Alternation）規範。如果歷史紀錄開頭是 Assistant，會自動在前面補一個微小的 User 訊息。
- Thinking 處理：正規化 Thinking 簽名，丟棄沒有簽名的思考區塊。
Anthropic / Minimax
Section titled “Anthropic / Minimax”- 回合驗證：如果連續出現多個 User Turns，會自動合併它們以符合嚴格的輪流規範。
- Tool 修復：包含 Tool Result 配對修復與合成 Tool Results。
Mistral
Section titled “Mistral”- Tool ID 限制：強制執行
strict9規範（長度為 9 的英數組合）。
OpenAI / OpenAI Codex
Section titled “OpenAI / OpenAI Codex”- 極簡處理：除了圖片縮放外，基本上不對 Transcript 做任何改動（No-touch）。
- 模型切換：只有在切換到 OpenAI 時，會移除孤立的 Reasoning Signatures。
OpenRouter Gemini
Section titled “OpenRouter Gemini”- 簽名清理：移除所有非 base64 的
thought_signature內容。
JSONL 檔案損壞怎麼辦？
Section titled “JSONL 檔案損壞怎麼辦？”如果 JSONL 檔案格式有誤，repairSessionFileIfNeeded 會在 Session 載入前自動移除無效行。別擔心原始資料遺失，系統會在原路徑下建立一個備份檔案。
為什麼 Tool Call 被丟棄了？
Section titled “為什麼 Tool Call 被丟棄了？”如果你的 Assistant 訊息包含 Tool Call，但裡面完全沒有 input 或 arguments 欄位，Hygiene 機制會判定這是無效的殘留片段並將其移除，以防止 Provider 回傳 400 錯誤。
歷史變更說明 (2026.1.22)
Section titled “歷史變更說明 (2026.1.22)”在 2026.1.22 版本之前，系統有多層重複的 Sanitization 邏輯，導致 OpenAI 的 call_id 配對經常出錯。現在所有邏輯已集中到 Runner 處理，並確保對 OpenAI 採取最小干預原則。
想要更自動化的設定嗎？試試 AI Setup Assistant。
OpenClaw Expert
還是卡住了？
如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。