跳到主要内容

外接兼容与接入说明

本页作为外接兼容总入口，统一说明第三方客户端、IDE、网关、自定义前端接入 duoduo 站点时的共性规则。具体请求头示例见外接调用 User-Agent 说明。

适用场景​

以下情况都建议先看本页，再看对应客户端页面：

  • 通过 JetBrains、Trae 等客户端外接 Claude / Codex
  • 使用自定义 Base URL 将官方插件接到 duoduo 站点
  • 已填 API Key，但仍出现403 block、401、模型不可用、1M 上下文不生效
  • 想确认某个分组、协议、User-Agent、模型名应该怎么对应

接入前先确认​

开始配置前，先把这 5 项对应好：

项目需要确认什么
分组你当前的 Key 属于default还是codex0.3
协议客户端要走Anthropic Messages、OpenAI Responses，还是其他兼容协议
Base URLClaude 类通常不带/v1，Codex 类通常带/v1
请求头外接场景通常需要补对应的User-Agent
模型有些分组允许留空，有些必须填写准确模型 ID

如果这 5 项有一项对不上，最常见的结果就是：

  • 403 block/403 Forbidden
  • 401 Unauthorized
  • 模型列表为空
  • 明明是长上下文分组，但实际仍按默认上下文工作

按模型类型填写​

接入类型常见协议Base URL推荐分组模型填写建议补充说明
Claude 外接Anthropic Messageshttps://duoapi.zeabur.appdefault大多数场景可留空，或按客户端要求填写 Claude 模型名需要 Claude CLI 风格User-Agent
Codex 外接OpenAI Responseshttps://duoapi.zeabur.app/v1codex0.3推荐gpt-5.4，或填写其他可用 GPT / Codex 模型需要 Codex CLI 风格User-Agent

详细请求头示例见外接调用 User-Agent 说明。

通用接入流程​

第一步：先用 CC Switch 配好基础环境​

默认先在CC Switch 统一配置中配置好目标渠道，确认：

  1. Key 可用
  2. 分组选择正确
  3. model没有填错

如果客户端支持直接读取本机 Claude / Codex 配置，通常到这一步就已经省掉一半手工配置。

第二步：按接入类型填写 Base URL​

类型正确写法
Claude 类https://duoapi.zeabur.app
Codex 类https://duoapi.zeabur.app/v1

最常见错误是：

  • 把 Claude 的地址误写成带/v1
  • 把 Codex 的地址误写成不带/v1

第三步：补齐 Header 或使用原生插件​

如果客户端支持自定义 Header，按接入类型补对应User-Agent。 如果客户端使用的是官方 Claude / Codex 插件，且只改 Base URL，通常可直接沿用插件自带请求头。

第四步：确认模型与上下文能力​

长上下文、缓存、搜索、工具调用通常不是“只换个地址”就自动生效，还要看：

  • 当前分组是否支持对应能力
  • 客户端是否真的把相关字段传出
  • 本地配置是否把默认值覆盖掉了

例如：

第五步：需要直连官方 Key / API 时，再看下方补充​

如果你不是走官方 CLI / 官方插件，而是自己拼请求字段去接官方 Key 或兼容 API，直接看下方“官方 Key / API 直连补充”。

官方 Key / API 直连补充​

有些用户不是通过官方 CLI、官方插件或 CC Switch 落地，而是：

  • 自己写请求脚本
  • 在第三方前端中手工拼协议字段
  • 直接拿官方 Key 接兼容层或网关

这类场景要特别注意，官方 Key 往往只提供最基础的认证与协议能力，很多“客户端里看起来自动完成”的适配，换成直连后都需要自己补。

重点检查项​

项目说明
协议字段目标端点要求的是messages、responses还是其他结构
缓存组织是否启用了缓存、缓存块怎样组织、是否被客户端拆散
上下文透传长上下文参数是否真的发出，而不是只写在本地 UI 里
工具调用搜索、联网、WebFetch、MCP 是否还需要额外工具参数

MAX 场景的缓存建议​

如果你在 MAX 一类场景中自己构造缓存内容，建议：

  1. 先确认目标端是否已经自带缓存机制
  2. 不要重复叠加多层语义相近的缓存块
  3. 单次组织的缓存内容块尽量保持克制，避免拆得过碎

如果缓存块组织过多、过碎，常见后果是：

  • 调试时很难判断哪一段真正生效
  • 不同客户端复用时行为不一致
  • 成本与效果不成正比

推荐做法​

能走官方 CLI / 官方插件 / CC Switch 的场景，优先不要自己重新发明一套请求封装。 只有在以下情况再考虑直连：

  • 当前客户端没有官方插件
  • 你明确需要自定义协议层
  • 你能自己维护请求体、缓存、错误处理和兼容升级

如果只是想“把某个客户端接上去”，优先还是按本页的统一接入流程和客户端页面操作。

按客户端查看​

客户端说明
JetBrains 外接适合 IDE 内调用 Claude / Codex 的场景
Trae 外接适合使用官方 Claude / Codex 插件并改 Base URL 的场景

常见排查顺序​

403 block/403 Forbidden​

按顺序检查：

  1. 分组是否匹配当前模型类型
  2. Base URL 是否带错/v1
  3. User-Agent是否缺失或填成了别的模型类型
  4. 客户端是否真的把 Header 发出去了

401 Unauthorized​

优先检查：

  1. Key 是否仍有效
  2. 是否存在旧 OAuth 状态覆盖 API Key
  3. IDE 插件、MCP 或环境变量是否覆盖了本地配置

相关说明：

1M 上下文没生效​

优先检查：

  1. 当前分组是否支持长上下文
  2. 客户端是否有单独的上下文参数
  3. 本地配置文件中是否仍沿用默认压缩阈值

搜索 / MCP 已连接但调用时报 Key 缺失​

这类问题通常是“连上了，但真正发请求时才读取环境变量”。 以grok-search-mcp为例，MCP 已显示已连接，不代表GROK_API_KEY一定传对了。

相关页面​

页面用途
CC Switch 统一配置统一配置入口
外接调用 User-Agent 说明各类型请求头示例
Claude Code 配置参考缓存、官方渠道切换、环境变量
Codex CLI 配置参考1M 上下文与手动配置
Grok Search MCP 配置Grok 联网搜索专题