外观
外接兼容与接入说明
本页作为外接兼容总入口，统一说明第三方客户端、IDE、网关、自定义前端接入 Vmvia 站点时的共性规则。具体请求头示例见 外接调用 User-Agent 说明。
适用场景
以下情况都建议先看本页，再看对应客户端页面：
- 通过 JetBrains、Trae、OpenClaw 等客户端外接 Claude / Codex / 国产模型
- 使用自定义 Base URL 将官方插件接到 Vmvia 站点
- 已填 API Key，但仍出现
403 block、401、模型不可用、1M 上下文不生效 - 想确认某个分组、协议、
User-Agent、模型名应该怎么对应
接入前先确认
开始配置前，先把这 5 项对应好：
| 项目 | 需要确认什么 |
|---|---|
| 分组 | 你当前的 Key 属于 Claude、Codex 还是国产模型分组；外接 Claude 必须用 sale_kiro，cc_max 只接受 Claude Code 客户端 |
| 协议 | 客户端要走 Anthropic Messages、OpenAI Responses，还是 OpenAI Chat Completions |
| Base URL | Claude 类不带 /v1，Codex / 国产模型类带 /v1 |
| 请求头 | 外接场景通常需要补对应的 User-Agent |
| 模型 | 有些分组允许留空，有些必须填写准确模型 ID |
如果这 5 项有一项对不上，最常见的结果就是：
403 block/403 Forbidden401 Unauthorized- 模型列表为空
- 明明是长上下文模型，但实际仍按默认上下文工作
按模型类型填写
| 接入类型 | 常见协议 | Base URL | 分组 | 模型填写建议 | 补充说明 |
|---|---|---|---|---|---|
| Claude 外接 | Anthropic Messages | https://www.vmvia.com | sale_kiro | 大多数场景可留空，或按客户端要求填写 Claude 模型名 | 需要 Claude CLI 风格 User-Agent |
| Codex 外接 | OpenAI Responses | https://www.vmvia.com/v1 | codex / codex-wending | 推荐 gpt-5.6-sol | 需要 Codex CLI 风格 User-Agent |
| 国产模型外接 | OpenAI Chat Completions | https://www.vmvia.com/v1 | 国模 | 按模型广场中的模型 ID 填写 | 建议使用浏览器型 User-Agent |
| GPT 生图 | OpenAI Images | https://www.vmvia.com/v1 | gpt-image | gpt-image-2 / gpt-image-2.5 系列 | 按次计费 |
| Grok 外接 / MCP | OpenAI Responses | https://www.vmvia.com/v1 | grok（即将上架） | 以上架后的模型广场为准 | grok-search-mcp 读取的是 GROK_* 环境变量 |
详细请求头示例见 外接调用 User-Agent 说明。
通用接入流程
第一步：为每种接入类型准备令牌
在 控制台 · 令牌 按接入类型分别创建令牌，确认：
- 分组选择正确（外接 Claude 用
sale_kiro，不要用cc_max） - 已关闭「模型限制」
model没有填错
如果客户端支持直接读取本机 Claude / Codex 配置，先用 CC Switch 配好基础环境，通常能省掉一半手工配置。
第二步：按接入类型填写 Base URL
| 类型 | 正确写法 |
|---|---|
| Claude 类 | https://www.vmvia.com |
| Codex / 国产模型 / 生图 / Grok | https://www.vmvia.com/v1 |
最常见错误是：
- 把 Claude 的地址误写成带
/v1 - 把 Codex 的地址误写成不带
/v1
主站访问不畅时，把 www.vmvia.com 换成 api.vmvia.com，路径规则相同。
第三步：补齐 Header 或使用原生插件
如果客户端支持自定义 Header，按接入类型补对应 User-Agent。 如果客户端使用的是官方 Claude / Codex 插件，且只改 Base URL，通常可直接沿用插件自带请求头。
第四步：确认模型与上下文能力
长上下文、缓存、搜索、工具调用通常不是「只换个地址」就自动生效，还要看：
- 当前分组是否支持对应能力
- 客户端是否真的把相关字段传出
- 本地配置是否把默认值覆盖掉了
例如：
- Codex CLI 1M 上下文还需要本地
config.toml参数配合，见 Codex CLI 配置参考 - Claude 侧 1 小时缓存需要补环境变量，见 Claude Code 配置参考
- Grok 搜索 MCP 需要改成
/responses并使用GROK_*环境变量，见 Grok Search MCP 配置
第五步：需要直连 API 时，再看下方补充
如果你不是走官方 CLI / 官方插件，而是自己拼请求字段去接兼容 API，直接看下方「API 直连补充」。
API 直连补充
有些用户不是通过官方 CLI、官方插件或 CC Switch 落地，而是：
- 自己写请求脚本
- 在第三方前端中手工拼协议字段
- 直接拿 Key 接兼容层或网关
这类场景要特别注意，很多「客户端里看起来自动完成」的适配，换成直连后都需要自己补。
重点检查项
| 项目 | 说明 |
|---|---|
| 协议字段 | 目标端点要求的是 messages、responses 还是 chat/completions |
| 缓存组织 | 是否启用了缓存、缓存块怎样组织、是否被客户端拆散 |
| 上下文透传 | 长上下文参数是否真的发出，而不是只写在本地 UI 里 |
| 工具调用 | 搜索、联网、WebFetch、MCP 是否还需要额外工具参数 |
缓存建议
如果你自己构造缓存内容，建议：
- 先确认目标端是否已经自带缓存机制
- 不要重复叠加多层语义相近的缓存块
- 单次组织的缓存内容块尽量保持克制，避免拆得过碎
缓存块组织过多、过碎的常见后果：调试时很难判断哪一段真正生效，不同客户端复用时行为不一致，成本与效果不成正比。
推荐做法
能走官方 CLI / 官方插件 / CC Switch 的场景，优先不要自己重新发明一套请求封装。只有在以下情况再考虑直连：
- 当前客户端没有官方插件
- 你明确需要自定义协议层
- 你能自己维护请求体、缓存、错误处理和兼容升级
按客户端查看
| 客户端 | 说明 |
|---|---|
| JetBrains 外接 | 适合 IDE 内调用 Claude / Codex 的场景 |
| Trae 外接 | 适合使用官方 Claude / Codex 插件并改 Base URL 的场景 |
| OpenClaw 配置 | 适合通过网关统一接 Claude / Codex / 国产模型 |
常见排查顺序
403 block / 403 Forbidden
按顺序检查：
- 分组是否匹配当前接入类型（外接 Claude 是否误用了
cc_max） - Base URL 是否带错
/v1 User-Agent是否缺失或填成了别的模型类型- 客户端是否真的把 Header 发出去了
401 Unauthorized
优先检查：
- Key 是否仍有效
- 是否存在旧 OAuth 状态覆盖 API Key
- IDE 插件、MCP 或环境变量是否覆盖了本地配置
相关说明：
1M 上下文没生效
优先检查：
- 当前模型是否支持长上下文
- 客户端是否有单独的上下文参数
- 本地配置文件中是否仍沿用默认压缩阈值
搜索 / MCP 已连接但调用时报 Key 缺失
这类问题通常是「连上了，但真正发请求时才读取环境变量」。以 grok-search-mcp 为例，MCP 已显示已连接，不代表 GROK_API_KEY 一定传对了。
相关页面
| 页面 | 用途 |
|---|---|
| CC Switch 统一配置 | 统一配置入口 |
| 外接调用 User-Agent 说明 | 各类型请求头示例 |
| Claude Code 配置参考 | 缓存、官方渠道切换、环境变量 |
| Codex CLI 配置参考 | 1M 上下文与手动配置 |
| Grok Search MCP 配置 | Grok 联网搜索专题 |