常见问题

遇到问题时，不要先重装客户端。请记录错误码，并按本页顺序检查。

示意图：先记录错误码，不要先重装客户端；可复制的地址、命令和代码仍以正文为准。

兑换码和 API Key 有什么区别？

内容	用途	填入客户端？
兑换码	在 DuckMans 钱包兑换余额	否
API Key	客户端请求模型的凭证，通常以 sk- 开头	是
Base URL	客户端连接 DuckMans 的接口地址	是

把兑换码填入客户端通常会返回 401。没有 API Key 时，先看创建 API Key。

示意图：两者不能互换，客户端还需要正确地址；可复制的地址、命令和代码仍以正文为准。

API 地址应该填什么？

• OpenAI Compatible 客户端通常填写 https://duckmans.com/v1。
• Claude/Anthropic 兼容配置通常填写 https://duckmans.com，由客户端追加 /v1/messages。
• 某些客户端会自动追加 /v1，必须按对应教程填写，避免形成 /v1/v1。

不确定时查看地址与客户端速查。

为什么获取不到模型列表？

按顺序检查：

1. Base URL 是否使用 https://，有没有重复 /v1。
2. API Key 是否复制完整，前后有没有空格或换行。
3. Key 是否启用、过期或设置了 IP 限制。
4. Key 所属分组是否包含目标模型。
5. 账户是否有可用余额。
6. 本地代理或公司网络是否阻止了请求。

可以使用查看模型列表中的命令独立测试。命令成功而客户端失败，问题通常在客户端配置。

401：API Key 无效

常见原因：

• 把兑换码当成 API Key。
• Key 少复制字符，或带有空格、引号、换行。
• Key 已删除、禁用或过期。
• 环境变量中仍保存旧 Key。

重新复制 Key 后完全退出并重开客户端。不要把完整 Key 发给客服。

403：没有权限

常见原因：

• Key 的分组不支持当前模型或接口协议。
• Key 启用了模型限制或 IP 白名单。
• Claude Code 误用了 OpenAI 分组，或 OpenAI 客户端误用了 Claude 分组。
• 客户端读取了旧环境变量。

先在 DuckMans 控制台核对 Key 的分组和限制，再换用该分组实际支持的模型。

404：接口路径错误

最常见的是 Base URL 填错：

• 漏掉 /v1。
• 客户端已自动补路径，又手动填写 /v1，最终请求成 /v1/v1/...。
• 把完整接口路径填进只需要 Base URL 的字段。

查看报错中的最终请求 URL，再按对应客户端教程修改。

429：请求过多或余额不足

429 可能表示余额不足、超过并发限制、当前渠道繁忙或上游限流。请先检查余额和用量记录，稍等后用短问题重试，不要连续快速点击发送。

5xx：服务暂时异常

500、502、503、504 通常与临时渠道或网络异常有关：

1. 新建会话，用一句短问题重试。
2. 换成同一分组内的另一个模型。
3. 检查 DuckMans 公告和用量记录。
4. 持续出现时，把时间、模型名、错误码和请求 ID 发给客服。

为什么发送消息后一直没有回复？

• 关闭客户端的流式输出后重试。
• ChatBox 可以开启“改善网络兼容性”。
• 新建空白会话，先发送一句短问题。
• 确认模型支持当前客户端使用的协议。
• 查看控制台是否产生用量记录；完全没有记录通常说明请求没有到达 DuckMans。

示意图：阶段完成后用交接摘要开启新会话；可复制的地址、命令和代码仍以正文为准。

为什么长会话越来越慢、费用越来越高？

客户端会把历史消息、文件摘要、工具调用和日志继续带入后续请求。上下文越大，处理时间和输入 Token 越多。

建议在一个阶段完成后，让模型生成交接摘要，然后新建会话继续：

请把当前任务整理成一份新会话可以继续使用的交接说明，包括目标、已完成事项、修改文件、验证结果、遗留问题和下一步。

不要反复粘贴完整构建日志、大型 JSON、无关源码或已经分析过的报错。

修改配置后为什么没有生效？

很多桌面客户端只在启动时读取配置。请从菜单栏或系统托盘完全退出应用，再重新打开。只关闭窗口或聊天面板通常不够。

如何查看用量？

进入 DuckMans 控制台的用量记录或日志页面，按 Key、模型和时间筛选。不同客户端使用独立 Key，更容易确认是哪台设备产生了消耗。

截图给客服时需要隐藏什么？

必须隐藏：

• 完整 API Key、兑换码和登录信息。
• 邮箱、手机号及个人目录。
• 请求头中的 Authorization。
• 包含业务源码或私密对话的内容。

API Key 只保留开头和末尾少量字符用于辨认，例如 sk-abcd••••wxyz。如果完整 Key 已经出现在公开截图中，请立即删除并重新创建。