新手快速入门

如果你第一次使用 API 中转服务，请按本页顺序操作。先完成最小测试，再添加插件、人物卡或复杂参数。

上图是本页的完整顺序。每一步的可复制字段和值仍以正文为准。

1. 登录并确认余额

打开 DuckMans 并登录。
如果你拿到的是兑换码，先在控制台的钱包页面兑换。
确认余额已经更新。已有余额时可以跳过兑换。

兑换码只用于兑换余额，不能填写到客户端。

在 有兑换码吗？ 输入框粘贴兑换码，再点击 兑换额度。不要把这里的兑换码复制到客户端。

出现 兑换成功 提示后再确认余额。图中金额已隐藏；实际金额以你的兑换结果为准。

2. 创建独立 API Key

进入 API 密钥/令牌管理，为当前客户端新建一个 Key。名称可以写成 ChatBox-手机 或 Cherry-Studio-电脑，便于以后单独停用。

客户端填写的是 API Key，不是登录密码或兑换码。
分组选择账号实际可用的分组。
如果后台支持额度或有效期限制，先设置一个满足测试需要的小额度。
创建后立即保存；公开示例只能写 YOUR_API_KEY 或 sk-abcd••••wxyz。

查看完整步骤：创建 API Key →

3. 确认分组与模型

同一个 Key 能使用哪些模型，取决于它所属的分组和 DuckMans 后台当前配置。

查看 Key 所属分组。
在控制台或客户端获取模型列表。
选择列表中真实出现的 后台当前可用模型 ID。

不要照抄其他教程中的模型名。模型列表为空时，先检查 Key、分组和地址，不要凭空填写一个模型。

4. 选择使用方式

你的需求	推荐工具	教程
电脑聊天，界面简单	ChatBox	电脑端 ChatBox
电脑聊天，多模型管理	Cherry Studio	Cherry Studio
角色扮演、人物卡、世界书	酒馆（SillyTavern）	SillyTavern
iOS 或 Android 聊天	ChatBox 手机端	手机端 ChatBox
消息渠道或本机 Agent	OpenClaw	OpenClaw
终端编程	Codex CLI	Codex CLI
桌面端编程	ChatGPT 桌面端（Codex）	查看教程
VS Code、Cursor 或 Windsurf	Codex IDE 插件	查看教程
开源终端编程助手	OpenCode	查看教程
JetBrains IDE	Kilo Code	查看教程
自己写程序调用接口	DuckMans API	API 概览

不确定地址填什么时，先看地址与客户端选择。

5. 填写核心信息

普通 OpenAI 兼容客户端通常填写：

字段	内容
类型	`OpenAI Compatible` / `OpenAI 兼容`
Base URL	`https://duckmans.com/v1`
API Key	`YOUR_API_KEY`
Model	后台当前可用模型 ID

地址不是全部都一样

ChatBox 的 API Host、Cherry Studio 的自定义 OpenAI API 地址 以及 Claude/Anthropic 客户端都使用 https://duckmans.com，但它们追加的路径不同。其他普通 OpenAI Compatible Base URL 通常填写 https://duckmans.com/v1。请以对应客户端教程为准，避免重复 /v1。

6. 完成最小测试

保存配置，新建一个空白对话，选择刚才确认的模型并发送：

text

你好，请只回复：DuckMans 配置成功。

收到这句回复后，基础配置才算完成。随后再添加人物卡、长提示词、消息渠道或第三方扩展。

7. 按错误现象排查

现象	优先检查
`401` / invalid key	是否把兑换码当成 Key；Key 是否完整、已删除或带空格
`403`	Key 的分组、权限或额度限制
`404`	地址是否缺少 `/v1`，或客户端是否又自动追加导致 `/v1/v1`
`429`	是否请求过快、达到并发限制或暂时没有可用额度
模型不存在	重新获取模型列表，改用后台当前可用模型 ID
一直转圈或返回空白	关闭流式输出后重试，并检查网络和客户端代理设置
`5xx`	稍后用同一条最小消息重试；持续出现时记录时间和报错原文

仍未解决时，查看常见问题。提供截图时必须遮住完整 API Key。

新手快速入门 ​

1. 登录并确认余额 ​

2. 创建独立 API Key ​

3. 确认分组与模型 ​

4. 选择使用方式 ​

5. 填写核心信息 ​

6. 完成最小测试 ​

7. 按错误现象排查 ​