古法编程

Appearance

OpenClaw在构建模型上下文前对转录记录执行提供商专属的修复，以满足严格提供商要求。修复在内存中执行，不修改磁盘文件，但会话文件加载前也会修复格式错误的行。如果遇到提供商拒绝或奇怪的错误，可以检查当前配置的提供商是否需要特定的工具调用ID格式、图像尺寸上限或轮次交替规则。

OpenClaw 转录清洗：排查提供商请求拒绝 ​

OpenClaw 在运行前（构建模型上下文时）对转录记录应用提供商专属修复。这些调整仅在内存中进行，用于满足严格提供商要求，不会重写磁盘上存储的 JSONL 转录文件。但单独的会话文件修复过程可能在加载前丢弃无效行或重写格式错误的 JSONL 行。当发生修复时，原始文件会被备份为 *.bak-<pid>-<ts> 文件，原子替换成功后删除备份；仅当清理失败时备份才会保留（此时会报告路径）。

范围包括：

  • 运行时上下文不存入用户转录
  • 工具调用 ID 清洗
  • 工具调用输入验证
  • 工具结果配对修复
  • 轮次验证与排序
  • 思考签名清理
  • 思考块签名清理
  • 图像载荷净化
  • 空白文本块清除（提供商回放前）
  • 用户输入来源标记（用于跨会话路由提示词）
  • 空助手错误轮次修复（Bedrock Converse 回放）

如需转录存储详情，见：

全局规则：运行时上下文不存入用户转录 ​

运行时/系统上下文可以在单轮中获得模型提示，但它们不是最终用户创作的内容。OpenClaw 为 Gateway 回复、排队后续消息、ACP、CLI 和嵌入式 Pi 运行保留独立的转录可见提示体。存储的可见用户轮次使用该转录体，而非运行时增强的提示。

对于已持久化运行时包装器的旧会话，Gateway 历史表面会在返回消息给 WebChat、TUI、REST 或 SSE 客户端前应用显示投影。

清洗规则的执行位置 ​

所有转录清洗集中在嵌入式运行器中：

  • 策略选择：src/agents/transcript-policy.ts
  • 净化/修复应用：sanitizeSessionHistory 位于 src/agents/pi-embedded-runner/replay-history.ts

该策略使用 provider、modelApi 和 modelId 决定应用哪些规则。

独立于转录清洗，会话文件在加载前（如需要）会被修复：

  • repairSessionFileIfNeeded 位于 src/agents/session-file-repair.ts
  • 从 run/attempt.ts 和 compact.ts（嵌入式运行器）调用

全局规则：图像净化 ​

始终对图像载荷进行净化，防止因尺寸限制导致提供商端拒绝（降尺寸/重压缩超大 base64 图像）。这也有助于控制视觉能力模型的图像驱动 token 压力。较低的最大尺寸通常减少 token 用量，较高的尺寸保留细节。

实现：

  • sanitizeSessionMessagesImages 在 src/agents/pi-embedded-helpers/images.ts
  • sanitizeContentBlocksImages 在 src/agents/tool-images.ts
  • 最大图像边长可通过 agents.defaults.imageMaxDimensionPx 配置（默认：1200）。
  • 当该过程遍历回放内容时，空白文本块会被移除。助手轮次若因此变空，将从回放副本中丢弃；用户和工具结果轮次若变空，将替换为非空的省略内容占位符。

全局规则：格式错误的工具调用 ​

在构建模型上下文之前，缺少 input 和 arguments 的助手工具调用块会被丢弃。这可以防止因部分持久化的工具调用（例如在速率限制失败后）导致的提供商拒绝。

实现：

  • sanitizeToolCallInputs 在 src/agents/session-transcript-repair.ts
  • 在 sanitizeSessionHistory（src/agents/pi-embedded-runner/replay-history.ts）中应用

全局规则：跨会话输入来源标记 ​

当智能体通过 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 遵循 Codex 线协议：回放之前 Responses 的推理/消息/函数载荷时不带先前项 ID，同时保留会话的 prompt_cache_key。
  • 不进行工具调用 ID 净化。
  • 工具结果配对修复可能移动实际匹配的输出并合成 Codex 风格的 aborted 输出用于缺失的工具调用。
  • 不进行轮次验证或重排序。
  • 缺失的 OpenAI Responses 系列工具输出合成为 aborted 以匹配 Codex 回放归一化。
  • 不进行思考签名剥离。

OpenAI-compatible Chat Completions ​

  • 在回放前剥离历史助手思考/推理块，使本地和代理风格的 OpenAI-compatible 服务器不接收前轮推理字段（如 reasoning 或 reasoning_content）。
  • 当前同轮工具调用延续保持助手推理块附加到工具调用上，直到工具结果被回放。
  • 提供商自有的异常可以选择退出，当它们的线协议要求回放推理元数据时。

Google（Generative AI / Gemini CLI / Antigravity） ​

  • 工具调用 ID 净化：严格字母数字。
  • 工具结果配对修复和合成工具结果。
  • 轮次验证（Gemini 风格轮次交替）。
  • Google 轮次排序修复：如果历史以助手开头，则在其前添加一个小型用户启动。
  • Antigravity Claude：归一化思考签名；丢弃未签名的思考块。

Anthropic / Minimax（Anthropic 兼容） ​

  • 工具结果配对修复和合成工具结果。
  • 轮次验证：合并连续用户轮次以满足严格交替要求。
  • 当思考启用时，从传出 Anthropic Messages 载荷中剥离尾部助手预填充轮次（包括 Cloudflare AI Gateway 路由）。
  • 缺失、空或空白的回放签名的思考块在提供商转换前被剥离。如果这导致助手轮次变空，OpenClaw 保留轮次形状，并填充非空省略推理文本。
  • 必须剥离的旧思考-only 助手轮次替换为非空省略推理文本，以便提供商适配器不丢弃回放轮次。

Amazon Bedrock（Converse API） ​

  • 在回放前将空助手流错误轮次修复为非空回退文本块。Bedrock Converse 拒绝 content: [] 的助手消息，因此持久化的 stopReason: "error" 且内容为空的助手轮次在加载前也会被修复。
  • 仅包含空白文本块的助手流错误轮次会从内存回放副本中丢弃，而不是回放无效空白块。
  • 缺失、空或空白的回放签名的 Claude 思考块在 Converse 回放前被剥离。如果导致助手轮次变空，OpenClaw 保留轮次形状，填充非空省略推理文本。
  • 必须剥离的旧思考-only 助手轮次替换为非空省略推理文本，以保证 Converse 回放保持严格轮次形状。
  • 回放过滤 OpenClaw 投递镜像和 gateway 注入的助手轮次。
  • 图像净化通过全局规则应用。

Mistral（包括基于 model-id 的检测） ​

  • 工具调用 ID 净化：strict9（长度为 9 的字母数字）。

OpenRouter Gemini ​

  • 思考签名清理：剥离非 base64 的 thought_signature 值（保留 base64）。

OpenRouter Anthropic ​

  • 当推理启用时，从已验证的 OpenRouter OpenAI-compatible Anthropic 模型载荷中剥离尾部助手预填充轮次，匹配直接 Anthropic 和 Cloudflare Anthropic 回放行为。

其他所有提供商 ​

  • 仅图像净化。

历史行为（2026.1.22 之前） ​

在 2026.1.22 版本之前，OpenClaw 应用了多层转录清洗：

  • 转录净化扩展在每次上下文构建时运行，可以：
    • 修复工具使用/结果配对。
    • 净化工具调用 ID（包括保留 _/- 的非严格模式）。
  • 运行器还执行提供商特定的净化，造成重复工作。
  • 额外的变更发生在提供商策略之外，包括：
    • 在持久化前从助手文本中剥离 <final> 标签。
    • 丢弃空的助手错误轮次。
    • 在工具调用后修剪助手内容。

这种复杂性导致了跨提供商回归（尤其是 openai-responses 的 call_id|fc_id 配对问题）。2026.1.22 清理版本移除了该扩展，将逻辑集中到运行器，并使 OpenAI 在图像净化之外不做任何处理。

相关文档 ​

常见问题 ​

图像过大导致提供商拒绝怎么调整？ ​

通过 agents.defaults.imageMaxDimensionPx 配置最大图像边长（默认 1200）。该配置控制图像降尺寸/重压缩的边界，适用于所有提供商。降低该值可以减少 token 用量，提高值保留更多细节。

为什么我的 Anthropic 对话报错提示连续 user 轮次？ ​

Anthropic 要求严格交替的 user/assistant 轮次。OpenClaw 会自动合并连续 user 轮次，但在某些边界情况下（例如手动构造的载荷）可能仍会出错。确保你的应用逻辑不连续发送 user 消息而不等待助手回复。

工具调用 ID 格式错误需要手动配置吗？ ​

不需要。OpenClaw 根据提供商自动清洗工具调用 ID：Google 使用严格字母数字，Mistral 使用 strict9（9 位字母数字），OpenAI 不做清洗。你无法通过配置改变这些规则，它们由 provider、modelApi 和 modelId 决定。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策