故障排查：自定义 OpenAI 兼容后端的上下文 Token 使用量未追踪

症状

如果您使用的是自定义或非标准的 OpenAI 兼容后端（如 llama-cpp、LM Studio 或其他本地推理服务器），在升级到某些版本后可能会遇到以下症状：

• 流式响应中 Token 使用量始终显示为 0% 或 0 个 token
• 即使模型明显在消耗 token，上下文窗口追踪似乎也失效了
• 流式和非流式请求之间的行为不一致（非流式请求显示准确的用量，而流式请求显示 0%）

此问题特别影响来自替代后端的流式请求响应，而标准 OpenAI API 端点继续正确报告用量。

根因分析

OpenAI 传输层中的 buildOpenAICompletionsParams() 函数仅在 compat.supportsUsageInStreaming 计算结果为 true 时，才在请求负载中包含 stream_options: { include_usage: true } 字段。

对于标准 OpenAI 端点，此兼容性标志正确解析，允许网关的 resolveIncludeUsageForStreaming() 函数正确追踪用量。然而，对于 llama-cpp 和 LM Studio 等自定义后端，此标志解析为 false，导致该字段被完全省略。如果请求中不存在此字段，网关就没有数据可供处理，导致上下文 token 使用量始终显示为零。

逐步修复

升级到 v2026.4.19-beta.2 版本会自动解决此问题。无需进行任何配置更改。

1. 升级 OpenClaw 包至 v2026.4.19-beta.2 或更高版本
2. 重启网关服务以加载更新后的传输层
3. 验证修复：通过向自定义后端发起流式请求来验证修复

验证

确认修复是否有效：

1. 向自定义后端（llama-cpp、LM Studio 等）发送流式补全请求
2. 监控响应负载中 usage 字段是否出现在流式块中
3. 确认上下文 token 追踪现在显示实际 token 数量而非 0%

// 示例验证：检查流式响应中是否出现 usage
const response = await openai.chat.completions.create({
  model: 'your-model',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: true,
  stream_options: { include_usage: true }  // 现在始终包含
});

for await (const chunk of response) {
  if (chunk.usage) {
    console.log('Usage tracked:', chunk.usage);
  }
}

常见陷阱

• 代理干扰：某些 API 代理或中间件可能会从请求负载中剥离未知字段。如果使用自定义代理层，请验证它将 stream_options 完整转发到后端。

• 后端特定配置：虽然该字段现在始终包含，不支持的后端会安全地忽略它，但某些较旧的自定义后端在遇到未知字段时可能会有意外行为。请先在预发布环境中测试。

• 混合环境：如果您运行多个不同版本的网络实例，token 追踪将在请求之间不一致。请确保所有实例都升级到 v2026.4.19-beta.2 以获得统一的行为。

相关错误

• 上下文窗口耗尽未被检测：由于用量始终为 0%，系统无法在流式请求期间准确警告用户接近上下文限制。
• 用量报告不一致：由于流式请求始终报告零用量，无法比较流式和非流式请求之间的用量指标。

受影响版本：v2026.4.19-beta.2 问题参考：#68707 变更的文件：src/agents/openai-transport-stream.ts、src/agents/openai-transport-stream.test.ts