Transcript Hygiene (Provider Fixups)

Tài liệu này mô tả các bản vá theo từng provider được áp dụng cho transcript trước khi chạy (xây dựng model context). Đây là các điều chỉnh trong bộ nhớ dùng để đáp ứng các yêu cầu nghiêm ngặt của provider. Chúng không ghi đè file transcript JSONL đã lưu trên ổ đĩa.

Phạm vi bao gồm:

  • Làm sạch tool call id
  • Sửa chữa cặp tool result
  • Kiểm tra / sắp xếp lượt hội thoại
  • Dọn dẹp thought signature
  • Làm sạch image payload

Nếu các bạn cần chi tiết về cách lưu trữ transcript, xem:

Nơi chạy

Tất cả transcript hygiene được tập trung trong embedded runner:

  • Chọn policy: src/agents/transcript-policy.ts
  • Áp dụng sanitization/repair: sanitizeSessionHistory trong src/agents/pi-embedded-runner/google.ts

Policy sử dụng provider, modelApi, và modelId để quyết định áp dụng gì.

Quy tắc toàn cục: làm sạch image

Image payload luôn được làm sạch để tránh provider từ chối do vượt quá giới hạn kích thước (giảm kích thước/nén lại các ảnh base64 quá lớn).

Triển khai:

  • sanitizeSessionMessagesImages trong src/agents/pi-embedded-helpers/images.ts
  • sanitizeContentBlocksImages trong src/agents/tool-images.ts

Ma trận provider (hành vi hiện tại)

OpenAI / OpenAI Codex

  • Chỉ làm sạch image.
  • Khi chuyển model sang OpenAI Responses/Codex, bỏ các reasoning signature mồ côi (các reasoning item đứng độc lập không có content block theo sau).
  • Không làm sạch tool call id.
  • Không sửa chữa cặp tool result.
  • Không kiểm tra hoặc sắp xếp lại lượt hội thoại.
  • Không tạo synthetic tool results.
  • Không loại bỏ thought signature.

Google (Generative AI / Gemini CLI / Antigravity)

  • Làm sạch tool call id: chỉ chữ và số nghiêm ngặt.
  • Sửa chữa cặp tool result và tạo synthetic tool results.
  • Kiểm tra lượt hội thoại (luân phiên kiểu Gemini).
  • Sửa thứ tự lượt hội thoại Google (thêm một user bootstrap nhỏ vào đầu nếu lịch sử bắt đầu bằng assistant).
  • Antigravity Claude: chuẩn hóa thinking signatures; bỏ các thinking block không có chữ ký.

Anthropic / Minimax (tương thích Anthropic)

  • Sửa chữa cặp tool result và tạo synthetic tool results.
  • Kiểm tra lượt hội thoại (gộp các lượt user liên tiếp để đáp ứng luân phiên nghiêm ngặt).

Mistral (bao gồm phát hiện dựa trên model-id)

  • Làm sạch tool call id: strict9 (chữ và số độ dài 9).

OpenRouter Gemini

  • Dọn dẹp thought signature: loại bỏ các giá trị thought_signature không phải base64 (giữ lại base64).

Tất cả các provider khác

  • Chỉ làm sạch image.

Hành vi lịch sử (trước 2026.1.22)

Trước bản phát hành 2026.1.22, OpenClaw áp dụng nhiều lớp transcript hygiene:

  • Một transcript-sanitize extension chạy trên mỗi lần xây dựng context và có thể:
    • Sửa chữa cặp tool use/result.
    • Làm sạch tool call ids (bao gồm chế độ non-strict giữ lại _/-).
  • Runner cũng thực hiện sanitization theo provider, dẫn đến trùng lặp công việc.
  • Các thay đổi bổ sung xảy ra bên ngoài provider policy, bao gồm:
    • Loại bỏ thẻ <final> khỏi văn bản assistant trước khi lưu.
    • Bỏ các lượt assistant error rỗng.
    • Cắt bớt nội dung assistant sau tool calls.

Sự phức tạp này gây ra các regression giữa các provider (đáng chú ý là cặp call_id|fc_id của openai-responses). Bản dọn dẹp 2026.1.22 đã loại bỏ extension, tập trung logic vào runner, và làm cho OpenAI không động chạm ngoài việc làm sạch image.