分组链使用指南#

分组链把多个分组保存为一条有顺序的备用线路。多个 API 密钥可以绑定同一条链；以后调整这条链的分组或顺序，绑定的密钥会一起使用新配置，客户端不需要换密钥或修改地址。

本文按控制台默认的繁体中文界面说明。「分組鏈」在英语界面显示为 Group chains。

使用前准备#

1. 登录 Freecode 控制台，打开 模型广场，确认目标模型在哪些分组可用。
2. 选择你有权限使用的分组，并查看各分组的价格。分组链不会增加分组权限，也不会把一个模型转换成另一个模型。
3. 在 钱包 确认余额；检查密钥有效期、额度和模型限制。

建议先用单个分组跑通请求，再添加备用分组。准备作为备用的分组也应支持同一个完整模型 ID 和你使用的接口。

第一步：创建分组链#

1. 打开 API 密钥 页面，点击顶部「分組鏈」。
2. 点击「新增分組鏈」，填写容易辨认的「分組鏈名稱」，例如 日常编程备用线路。
3. 在「新增分組」中依次选择你要使用的分组。
4. 在「分組順序」列表中拖动条目，或使用上移、下移按钮调整顺序。首选分组放在最上面；删除某个条目只会把它从这条链中移除。
5. 点击「儲存」。列表会显示链名称、分组顺序和绑定的 API 密钥数量。

可以按下面的思路排列；表中名称是示意，请从你自己的可用分组中选择：

每个账户最多创建 10 条链，每条链包含 1–20 个不重复的分组。名称不能重复，最长 100 个字符。「自动选择分组 / auto」不能作为链中的一个成员。

第二步：把 API 密钥绑定到链#

1. 返回 API 密钥列表，编辑你要使用的密钥；也可以创建一把新密钥。
2. 打开「分組」下拉框，搜索并选中刚保存的链名称。
3. 检查密钥的模型限制和额度，然后保存。选择分组链后，系统会启用跨分组重试。
4. 在列表的「分組」列确认显示的是链名称。

只创建链、没有编辑密钥绑定它，原来的密钥仍使用原来的分组。不同工具可以使用不同密钥，并绑定同一条链。

第三步：正常调用并确认结果#

客户端继续使用自己的 Freecode API 密钥、原来的接口地址和模型 ID。无需在请求正文或 HTTP Header 中添加链名称，也无需填写分组名。

配置方法见 Codex CLI、Claude Code、OpenAI SDK 和 Anthropic SDK。

发出一次实际请求后，打开 使用日志，按密钥和时间查找记录，核对实际使用的模型、分组与费用。路由预览或模型列表可见，只说明配置符合对应条件；确认可用仍需一次成功的实际调用。

系统什么时候切换分组#

分组链的正常选择顺序是从上到下，同一个请求成功后就停止，不会同时向所有分组发送请求。

• 当前分组没有目标模型的可用渠道时，会继续寻找后面的分组。
• 上游请求失败时，只有服务器判定为可重试的错误，才会继续重试。系统可能先尝试同一分组内的其他渠道；达到该分组的重试限制后，再尝试后面的分组。
• 鉴权、参数、额度等在进入上游前就被拒绝的请求，不会因绑定分组链而自动恢复。明确不可重试的错误也会直接返回。
• 重试次数、重试状态码和管理员设置会影响结果。若管理员设置了会话亲和或严格会话绑定，同一会话还可能优先复用已有渠道，或限制切换。
• 链内所有分组都必须保持对你可用。某个分组被取消权限或移除倍率配置时，整条链可能在校验阶段被拒绝；请编辑链删除这个分组。

因此，分组链不保证每种错误都能切换成功，也不会自动把请求中的模型 ID 换成其他模型。

费用如何计算#

按实际使用的模型和实际路由到的分组计费。链中的倍率不相加，也不会按第一组的价格锁定后续分组。

如果备用组更贵，切换后的成功请求可能产生更高费用。请先在模型广场比较各分组价格，再确定顺序，并在使用日志中确认扣费。分组链不会绕过账户余额或密钥额度限制。

修改与删除#

**修改链：**在「分組鏈」弹窗中点击目标链的编辑按钮，修改名称、分组或顺序并保存。绑定这条链的所有密钥都会使用新配置，之后发出的请求按新配置处理；不需要逐个重新绑定。

**从链中删除一个分组：**只改变链的备用顺序，不会删除平台分组、渠道或 API 密钥。

**删除整条链：**会保留原来的 API 密钥，并将它们改为「自动选择分组」，清空原来的自定义分组顺序，同时启用跨分组重试。自动选择使用平台提供的可用分组顺序，可能与被删除的链不同。

如果你希望删除后仍固定使用某个分组，请先编辑相关密钥，改绑到指定分组或另一条链，再删除旧链。链列表中的密钥数量可帮助确认影响范围。

常见问题#

其他接入问题见 常见问题。