FAQ

最后整理：2026-04-21 15:32:54Z

当前 issue 正文保存的是已合并去重后的 FAQ 主体。
后续只有新的 FAQ 主题才会追加到 comment，已存在主题默认不再重复追加。

流式请求异常、重试不生效、日志中出现大量“已取消”

• 现象：
  • 配置了重试策略，但流式请求失败时有时不会触发重试，而是直接失败。
  • 可能出现 stream ended without terminal event or completed response 错误。
  • 也可能出现请求显示“已完成”，但 token 显示 -、耗时极短，或者日志里出现大量“已取消”状态。
  • 某些截断请求（例如无 usage 信息）看起来像成功结束，但实际响应并不完整。
• 原因：
  • 流式响应一旦已经向客户端发送了部分 chunk，就无法中途切换到其他渠道继续返回，这是流式架构本身的限制。
  • stream ended without terminal event or completed response 通常是上游流式响应异常，AxonHub 无法在中途把已开始的流式结果拼接成另一条正常响应。
  • “已取消”通常不是用户手动取消，而是客户端（如 Codex）因为上游超时、响应异常或连接问题主动终止请求。
• 解决方案：
  • 如果你更看重失败后的稳定重试能力，优先考虑非流式请求（stream: false）。
  • 检查上游渠道稳定性，优先使用更稳定的渠道。
  • 根据需要调整负载均衡 / 故障切换策略，避免持续命中不稳定渠道。
  • 如果日志里频繁出现“已取消”或 stream ended without terminal event，通常应优先排查上游渠道，而不是只看 AxonHub 本身。
• 相关 Issues：#1402、#1385、#1330、#1323、#1248

/admin/graphql 访问很慢

• 现象：
  • /admin/graphql 响应很慢，后台首页、渠道页、请求页、日志页等虽然前端已渲染，但数据加载可能要等待 10 秒以上。
  • 问题可以稳定复现，影响后台页面可用性。
• 原因：
  • 已确认的常见原因是请求日志保留时间过长，导致数据库日志体量过大，从而拖慢后台相关查询。
• 解决方案：
  • 优先检查请求日志保留时长、数据库体量和日志清理策略。
  • 已有反馈表明：将请求日志保留时间从 14 天缩短到 3 天，并清理数据库日志后，问题可以恢复正常。
  • 如果仍然缓慢，再补充数据量、数据库类型、存储配置、GC 配置等信息继续排查。
• 相关 Issues：#1343

Codex 追踪不生效

• 现象：
  • 配置了 Codex tracing 后，请求能正常发出，但“追踪”或“线程”里看不到按会话聚合的记录。
  • Claude Code 正常，只有 Codex 看起来没有被正确聚合。
• 原因：
  • 已确认的常见原因是前置 Nginx 默认会忽略包含下划线的请求头，导致追踪相关 header 没有透传到 AxonHub。
• 解决方案：
  • 如果前面用了 Nginx，检查并开启：underscores_in_headers on;
  • 同时对照 Codex 集成文档检查 tracing 配置是否完整。
• 相关 Issues：#971

使用 Claude Code 时报错：metadata 参数仅允许在 store 启用时使用

• 现象：
  • 使用 Claude Code 对接某些渠道（如 GPT-5.4）时，请求直接报错：Invalid param: The 'metadata' parameter is only allowed when 'store' is enabled.
• 原因：
  • 上游渠道不支持在未启用 store 时传入 metadata 字段，而 Claude Code 默认会带上这部分参数。
• 解决方案：
  • 方案一：换用 Codex 渠道，绕开这个兼容性问题。
  • 方案二：使用参数覆盖功能删除 metadata 字段。
• 相关 Issues：#1380

渠道的 BaseURL 配置不正确

• 现象：
  • 添加某些 OpenAI 兼容渠道后直接报错，复制 curl 命令检查发现请求地址和官方文档不一致。
• 原因：
  • 这类渠道往往需要手动配置正确的 BaseURL，如果配置错了，请求会直接失败。
• 解决方案：
  • 对照对应服务商的官方文档核对并修正 BaseURL。
  • 例如讯飞 Token Plan / CodingPlan 这类接口，需要使用它们文档指定的 OpenAI 兼容地址，而不是通用地址。
• 相关 Issues：#1377

Anthropic 格式接入某些渠道报 422 错误

• 现象：
  • 使用 Anthropic Messages 格式（/v1/messages）接入某些第三方 API 站点时，返回 422 错误。
  • 同一站点用 OpenAI 格式接入可能是正常的。
• 原因：
  • 上游渠道可能并不是标准 Anthropic API，而是逆向或转发服务，对 Anthropic 格式兼容性有限。
  • 某些逆向渠道实际后端更接近 Claude Code，而不是真正的 Anthropic 接口。
• 解决方案：
  • 先查看请求详情中的具体错误。
  • 如果上游实际上是 Claude Code，改用 Claude Code 渠道类型，不要使用 Anthropic 渠道。
  • 如果 Anthropic 格式持续不兼容，可优先尝试 OpenAI 格式。
• 相关 Issues：#1373

Nebius 渠道请求失败

• 现象：
  • Nebius 渠道之前可用，后来开始返回 Bad Request，但在其他工具中调用又可能正常。
  • 某些模型失败，另一些模型正常。
• 原因：
  • 更像是上游渠道或特定模型的兼容性问题，不一定是 AxonHub 本身的通用故障。
• 解决方案：
  • 查看请求详情中的具体错误信息。
  • 对比成功请求和失败请求的参数差异，逐个排查。
  • 直接用请求详情里的 URL 复现，以确认是否是上游限制。
• 相关 Issues：#1361

因错误次数而被禁用的渠道依然一直被请求

• 现象：
  • 渠道设置了“错误 N 次后自动禁用”，但被禁用后后续请求仍然会继续尝试该渠道，无法正确跳过。
  • 在渠道数较多、模型映射较复杂，或 Docker + SQLite 等环境下更容易被观察到。
• 原因：
  • 已知问题与缓存刷新有关：渠道被禁用后，缓存状态不一定立即刷新成功，导致旧状态继续被命中。
• 解决方案：
  • 先查看日志，确认是否存在缓存刷新失败。
  • 如果缓存没有及时刷新，可尝试重启服务。
  • 新版本如果提供缓存诊断能力，优先使用诊断工具检查缓存状态。
• 相关 Issues：#1386

自定义模型名称与多渠道模型路由管理

• 现象：
  • 用户希望把多个渠道的不同模型 ID 统一映射成同一个对外模型名，但在别名、模型关联、隐藏原始模型等功能组合使用时，容易遇到限制、重复展示或 UI 行为不直观的问题。
• 解决方案：
  • 在模型关联页面先选择已有 developer/model，再修改为想要的自定义值后保存。
  • 如果保存行为异常，检查是否有浏览器扩展或油猴脚本干扰表单输入。
• 相关 Issues：#1432

/v1/models 查询结果不符合预期

• 现象：
  • /v1/models 查询到了渠道的模型,而不仅仅是在页面配置的模型
• 解决方案：
  • 在模型列表页上面的模型配置里面关闭查询所有渠道模型。
• 相关 Issues：#1432