常见问题
从错误和现象开始,定位账号、接入、代理、许可或部署问题。
返回 401
先核对调用 Key 是否为当前网关的软件授权码或已保存的自定义 Key;检查请求头和目标地址。不要使用账号 OAuth Token 代替网关调用 Key。
返回 403
查看响应中的具体原因:软件许可、调用来源白名单、客户端准入或其他规则都可能拒绝请求。白名单应填写实际公网出口,代理和 NAT 可能改变你看到的出口。
管理登录不受模型接口白名单限制,可以登录后台修正规则。
返回 429
查看是上游限制,还是 Token 的请求频率、并发或活跃会话达到限制。Count Tokens 有独立规则。先检查额度、负载和日志,避免持续重发造成更多限流。
返回 503
查看是否没有可用 Token、许可复核不可用、模型目录未就绪或本地依赖异常。自定义组不会自动借用其他组;检查账号是否启用、材料有效、处于冷却或达到限制。
模型找不到或无法选择
通过模型列表取得准确 ID。未知、停用或暂不可计价的模型不会作为正常可调用型号提供。检查“系统配置”中的模型价表状态,并区分目录问题和账号本身没有模型权限。
插件安装了但没有连接
确认 Chrome / Edge 扩展已启用,允许访问当前网关页面;回到网关刷新检查。更新时应替换原目录并重新加载扩展,再看页面识别到的版本。仅下载 ZIP 不会更新已安装插件。
授权后回调页面打不开
授权链接方式可以复制地址栏回调网址回到网关提交;使用插件方式时等待插件接管并返回原页面。不要因为本机回调端口没有服务就反复兑换同一授权码。
提示过期、账号不匹配或结果不确定时,先核对本次流程和列表;需要重做时创建新的授权流程。
邮件 magic link 应该在哪里打开
使用插件时,复制邮件中的完整登录链接,切回原来由插件打开的 Claude 授权标签页,按 Ctrl+L(macOS 为 ⌘+L)贴到地址栏并回车,在原标签继续登录和授权。不要在邮件打开的新标签、其他浏览器或无痕窗口中完成。
更顺畅的做法是先在同一浏览器、同一个人资料里登录目标 Claude 账号,再回网关开始授权。magic link 是登录链接,不能贴进网关的 OAuth 回调输入框。查看标注图和完整步骤。
额度为空或刷新失败
空值表示没有可靠数据,不代表真实零。核对授权状态、代理、资料权限及具体错误。额度查询和模型调用不是同一个操作,代理握手成功也不能证明额度接口必定可用。
流式响应迟迟不显示
检查客户端是否按 SSE 逐段处理,并关闭代理缓冲。宿主 Nginx 应使用交付示例中的流式设置;普通总超时、空闲超时和客户端本地缓冲需分别排查。
更新失败或重启后版本不对
先查看更新任务结果、实际应用版本、容器状态和日志。网页应用更新、初装镜像、运行底座和插件版本不同,不能只看镜像标签判断是否升级成功。
保持数据卷和原配置,按 安装与维护处理;不要通过清库解决版本或密码问题。
提交问题时提供什么
提供应用版本、发生时间、入口页面、请求错误码、最小复现步骤和必要日志。移除 Token、调用 Key、授权码、密码、邮箱及敏感请求正文后再发送诊断材料。