Send x-opencode-session header on API requests (required by OpenCode Go from 09/05)

问题场景

用户通过 LiteLLM 的代理/网关调用 OpenCode Go 托管推理 API，正常发起 LLM 推理请求。OpenCode 从 09/05 起强制要求出站请求携带 x-opencode-session 头，用于按会话路由和优化，而 LiteLLM 在该时间点的版本中未发送此头，导致推理请求被判为无法路由并报错。评论中多位用户反馈因此无法继续使用 LiteLLM，并分别提交了 PR 或使用临时 header 方案。

报错原文

Error during LLM inference: 
   litellm.BadRequestError: 
OpenAIException - 
{
  "type": "error",
  "error": {
    "type": "MissingSessionID",
    "message": "Error from provider (Console Go): Request is missing x-opencode-session and cannot be routed efficiently. Please see https://opencode.ai/docs/go/#where-can-i-use-it"
  }
}

对应需求表述为：Send x-opencode-session header on API requests (required by OpenCode Go from 09/05)。

原因分析

最可能的原因是 LiteLLM 向 OpenCode Go 发出的推理 HTTP 请求中没有携带 x-opencode-session 头。OpenCode 侧已将该头作为强制校验项，缺失时返回 MissingSessionID 并拒绝路由。Issue 明确指出 LiteLLM 在发帖时所见的所有版本都未发送该头，因此这不是模型参数或鉴权问题，而是请求头构造问题。

环境排查

• 确认当前 LiteLLM 版本：Issue 中用户报错时出现 litellm/1.98.0，需核对你实际运行的版本。
• 确认所使用的 LiteLLM 路由方式（Issue 提到修复后覆盖“三类路由”，应核对你的调用路径是否在覆盖范围内）。
• 确认是否已升级到包含 PR #48121 的构建；仅看到 PR 合并不代表你的部署已生效。
• 确认模型配置中是否已有自定义 extra_headers，避免与实际请求头冲突。
• Issue 未提供操作系统、Python、CUDA、PyTorch、显卡信息，这些项目暂不作为本次排错依据。

解决步骤

1. 首选：升级 LiteLLM 到包含 PR #48121 的版本。Issue 中维护者确认该 PR 已修复并合并，稳定会话 ID 会在三类路由上自动转发。
2. 若暂时无法升级，采用评论中已验证可用的临时规避：在模型配置中加入 extra_headers，传入一个固定 UUID，例如 extra_headers = '{"x-opencode-session": "123e4567-e89b-12d3-a456-426614174000", "User-Agent": "my-agent/1.0"}'。可优先尝试，但这是静态值而非按会话生成的 ID。
3. 不建议依赖“回调自动注入 extra headers”的方案：评论反馈在健康检查场景下该方式不生效，且未得到维护者确认。
4. 完成配置后重启 LiteLLM 服务，使配置或新版本生效。
5. 升级后如需进一步优化，可向 OpenCode 方确认其遥测是否已收到会话头，Issue 中对方表示构建发布后愿意从遥测侧确认。

验证方法

再次发起同样的推理请求，确认不再出现 MissingSessionID 与 litellm.BadRequestError，且能正常返回模型输出。如条件允许，抓取或记录出站请求头，确认其中包含 x-opencode-session；升级到修复版本后，还应确认该值随对话变化，而不是固定 UUID。

参考来源

BerriAI/litellm #39503

相关 PR：BerriAI/litellm #48121（Issue 中确认已合并）

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。