错误与问题反馈

当 Chat、API 或 imux 官方模型报错时，系统会给出可读说明 + 稳定错误码 + 排查参考（requestId）。本页说明如何快速定位问题，以及如何向我们反馈。

优先看错误末尾的「排查参考」行（例如 mbr_xxx · upstream_error · stage=upstream · HTTP 502）。把整行复制给我们，即可在服务端日志中精确关联。

错误会出现在哪里

imux 原生 App：Agent Chat 气泡中显示人话 + 排查参考；控制台有 [AgentChatProvider] 日志。
Web Chat / Playground（/playground · chat.clavue.com）：红色错误条 + 排查参考；浏览器控制台有 [clavue-chat] membership error。
API（api.clavue.com/v1/* / www.clavue.com/api/membership/v1/*）：JSON 信封 + 响应头 x-imux-request-id / x-imux-error-code / x-imux-error-stage。

如何读「排查参考」

典型格式：

官方模型上游暂时失败。请稍后重试，或切换模型（如 clavue-2.1-fast）。
请稍后再试。

排查参考: mbr_mrz… · upstream_error · stage=upstream · HTTP 502 · up=500

片段	含义
`mbr_…`	requestId，一次请求的全局关联 ID
`upstream_error`	稳定错误码 code，决定如何恢复
`stage=upstream`	失败阶段：auth / quota / upstream / validation…
`HTTP 502`	返回给你的 HTTP 状态（可能已映射，如上游 401→503）
`up=500`	上游原始状态（若有）

30 秒排查流程

确认已登录（账号页显示邮箱 / 套餐）。
看 code：额度 / 限流 → 账号与定价；upstream_* → 重试或换模型。
换一个官方模型（auto ↔ clavue-2.1-fast）再试一次。
仍失败：复制完整错误（含排查参考）反馈。

常见错误码

`code`	HTTP	含义	你可以做什么
`sign_in_required`	`401`	未登录，或会话 / Token 已失效	打开账号页重新登录；CLI 重新做设备码登录
`rate_limited`	`429`	请求过于频繁（IP 或套餐 RPM）	稍后再试；升级套餐可提高 RPM
`quota_exceeded`	`402`	日 / 周 / 月额度或加油包用尽	升级、购买加油包、每日签到，或等待额度重置
`official_models_only`	`400`	请求了非官方模型 ID	改用 auto · clavue · clavue-2.1 · -fast · -pro · -rev · -search（官方 MCP）
`upstream_error`	`502`	官方模型上游失败（例如 openai_error）	重试；切换模型（如 clavue-2.1-fast）；持续失败时带排查参考反馈
`upstream_rate_limited`	`429`	上游模型服务限流	放慢频率，稍后再试
`upstream_not_configured`	`503`	服务侧上游未配置（运营侧）	稍后重试；若持续出现请带 requestId 反馈
`upstream_model_unavailable`	`502`	产品模型对应的上游不可用	切换其他官方模型；若全部失败请反馈
`context_length_exceeded`	`400`	对话内容超出模型上下文	新开对话，或缩短本次请求
`internal_error`	`500`	服务内部异常	重试；若反复出现请带 requestId 反馈

开发者完整信封字段见开发者文档与仓库 docs/membership-api-errors.md。

以前有些上游错误会显示成 openai_error，容易误以为没登录。现在：

真正未登录 → code=sign_in_required，stage=auth
官方上游挂了 → code=upstream_*，stage=upstream（会自动退还本次额度）
额度不够 → code=quota_exceeded，stage=quota

额度与加油包

查看用量：/account · /usage
升级套餐：/pricing
加油包：账号页签到 / 邀请 / 限时抢购；用尽 Free 额度后自动扣加油包。

如何反馈问题

反馈时请尽量附带下面信息，我们才能按 requestId 一秒定位：

完整错误文本（含「排查参考」或 Ref 行）
发生位置：imux App / Web Chat / API / CLI
大约时间（含时区）与所用模型（auto / clavue-2.1-fast…）
是否可复现；换模型 / 新对话后是否仍失败
API 用户：响应头 x-imux-request-id 与响应 JSON

请勿粘贴 API Key、密码、完整会话 Cookie 或隐私对话内容。requestId 与错误码已足够排查。

渠道：GitHub Issues · 应用内反馈（若可用）· 开发者社区公告栏。

官方 MCP · 联网搜索

Clavue 官方 MCP（server=clavue）提供 web_search 工具，对应产品模型 clavue-2.1-search（非自由对话）。imux Agent 可直接调用 mcp__clavue__web_search；chat.clavue.com 的「调研」也会走同一路径。输出为 agent 统一 JSON（clavue.search.v1），含合规安全网关。完整使用说明 →

# List official tools
curl -s https://api.clavue.com/v1/mcp -H "Authorization: Bearer $TOKEN"

# Call search
curl -s https://api.clavue.com/v1/mcp/tools/call \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"name":"web_search","arguments":{"query":"..."} }'

API 自检示例

# Expect 401 + requestId + code=sign_in_required when logged out
curl -si https://api.clavue.com/v1/chat/completions \
  -H "content-type: application/json" \
  -H "x-imux-request-id: mbr_cli_demo_001" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}' \
  | head -40

# Signed-in call (replace TOKEN)
curl -si https://api.clavue.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'