请求卡住或失败，从这里查

English · 常见问题

从一次具体请求出发，通常比反复换模型更快。打开请求（Requests），找到对应时间或请求 ID，按下面的顺序看：

看到什么	下一步查什么
尚未发出上游尝试	身份、模型路由、协议与能力预检；如果正在等待，查看队列容量
已有失败尝试，随后恢复成功	失败线路、触发的恢复条件和最终成功线路；一次上游失败不等于客户端任务失败
等待或恢复后仍失败	是否还有兼容候选、恢复条件是否允许、预算是否用尽或客户端是否取消
已输出一部分内容后中断	最后一次上游尝试和流式终态；输出提交后不会拼接另一条上游流

配置恢复路由的步骤见长任务指南。以下是具体症状的处理入口。

先确认访问的是哪个实例。原生示例使用管理端口 7900、推理端口 7890；Compose 示例使用 17910 和 17810。自定义安装以实际配置为准。

修改 YAML 后没有生效

YAML 只在空库首次导入。已初始化实例使用 SQLite 中的配置，通过控制台或管理 API 修改。不要删除数据库来应用日常配置。

启动时报端口被占用

检查是否已有实例使用该地址。恢复出的配置也包含原监听地址，不能与原实例在同一主机同端口启动。先用 ferry -data-dir <directory> -startup-check 查看配置，或将恢复演练放到隔离环境。

客户端出现 401／403

确认使用推理 API Key 访问 /v1/*，使用 Management Token 访问 /api/*。核对身份是否启用、过期或被撤销，以及模型和协议范围。管理写入还可能需要管理员会话的 CSRF 校验或 Token 的高风险开关。

模型能列出来，却不能调用

目录发现与推理能力是两件事。检查 Logical Model 路由、Provider／Connection 状态、上游凭据、账号准入和协议；查看 Requests 中的选路失败或上游尝试。不要仅凭模型名开启工具、reasoning 或 Fast 声明。

普通请求正常，流式或工具调用失败

分别核对端点能力和请求参数。检查代理是否缓冲事件流、客户端是否识别终止事件、工具结果是否保留调用 ID。无法表达的跨协议参数会被拒绝。使用同一实例、同一模型和准确协议复现，避免混入另一路由的结果。

上游一直没有输出，为什么没有换路

先区分排队等待和已经调用上游。模型的 first_output_timeout_seconds 默认为 0，表示关闭首输出超时；启用后还需要路由允许对应超时恢复，并有可用候选。该计时从获得并发容量后开始，在首个有效文本、推理或工具输出后结束。它不会因为长响应还没结束就切断已经正常输出的流。

具体字段见管理 API，恢复条件与验证步骤见长任务指南。

原生账号已登录，但 Provider 不可用

登录保存账号凭据；Provider 的保存和启用仍需单独完成。重新打开编辑器读取账号状态。relogin_required 需要重新登录；Meta 的 key_pending 需要显式完成换取推理 Key。Vertex、Antigravity、Devin 使用准确模型 ID，不能依赖默认目录同步。参见驱动参考。

容器无法访问上游

容器里的 localhost 是容器自身。填写从容器内可达的地址，并检查 DNS、TLS、代理和目标鉴权。不要为了连通性把管理端口直接公开。

深色模式没有随系统变化

主题按钮在“跟随系统 → 浅色 → 深色”间切换。明确选择浅色或深色时会覆盖系统偏好；切回“跟随系统”即可。语言和主题保存在当前浏览器，其他浏览器不会自动同步。

升级后控制台还是旧样式

控制台嵌入二进制。修改源码文件不会更新已经运行的程序；重新构建并重启目标实例，再刷新浏览器。通过 /version 确认访问的是预期版本。

费用与上游账单不一致

核对时间窗口、模型价格、缓存 token、失败和回退尝试，以及订阅分摊。没有价格或用量证据的记录不能按免费处理。控制台统计不替代供应商账单，服务等级回显也不能单独证明加速或额外计费。

报告问题时提供什么

提供版本、运行方式、脱敏配置、复现步骤、预期结果、实际错误及请求时间／ID。先检查能否用最小输入复现。不要附数据库、备份、令牌或真实用户对话；疑似漏洞按 SECURITY.md 处理。