通用接入原理

接入前先准备三样东西：地址、模型 API 密钥、模型 ID。再根据客户端支持的协议填写，不需要注册上游模型官方账号。

先复制这三项

项目	内容	从哪确认
API 地址	SDK / 大部分 OpenAI 客户端填 https://v1.123336.xyz/v1	下方地址规则
模型 API 密钥	目标分组的 sk- 密钥	创建密钥
模型 ID	如 gpt-6-astra、grok-4.7	模型广场 / 该密钥的模型列表

密钥与分组要配套

模型名相同，不代表所有密钥都能调用。先看分组选择指南，不同分组单独建密钥，客户端切换到对应供应商配置。

地址到底要不要带 /v1

使用方式	填什么	说明
OpenAI SDK、Codex、zCode、DSH	https://v1.123336.xyz/v1	客户端追加 /responses 等资源路径
Claude Code	https://v1.123336.xyz	客户端追加 /v1/messages
Cherry Studio 内置 New API	https://v1.123336.xyz	按协议补全版本路径
自己发 HTTP 请求	完整地址，如 https://v1.123336.xyz/v1/responses	见请求示例

备用域名为 api.123336.xyz，其余路径保持不变。不要把完整的 /chat/completions 地址粘贴进只需要 Base URL 的字段。 不清楚时，查看客户端最终请求的地址，避免 /v1/v1 或漏写 /v1。

协议选哪个

• Responses：适用于支持该协议的模型与 Agent 客户端；在模型详情核对 openai-response。
• Chat Completions：常见 OpenAI 兼容聊天协议，在模型详情核对 openai。
• Anthropic Messages：Claude Code 等客户端使用，在模型详情核对 anthropic。
• Gemini 原生：需要客户端支持，并在模型详情核对 gemini。

不要为了接入而把所有模型都强制选成同一协议。模型支持的协议也不等于兼容所有官方工具和托管功能。

接入顺序

1. 创建密钥，确认分组。
2. 打开客户端自定义供应商设置，填地址和密钥。
3. 获取模型列表，或复制模型 ID 手动添加。
4. 选择支持的协议，其他参数先保留默认。
5. 发一句简短消息，再到控制台查看使用日志。

配好了却用不了

现象	优先检查
401	密钥有无空格、是否失效、实际生效的是哪份配置
404 / HTML 页面	请求路径是否错了，是否把文档或控制台页面当成 API 地址
model not found / 无可用渠道	模型 ID、分组权限、模型当前是否可用
参数不支持	移除额外参数，以最小请求验证协议和模型
超时 / 中途断流	网络、上游状态与完整日志；必要时切换备用域名

具体教程：CC Switch · Claude Code · zCode · DSH · Cherry Studio。自己写代码看开发者接入，更多报错看常见问题。