• API网关
• LLM 网关
• 后端

DeepSeek 是当前 CCX（Claude / Codex / Gemini API Proxy）网关最常用的纯文本模型供应商之一。本指南基于仓库文档 docs/providers/deepseek.md 与源码实现，系统讲解如何在 CCX 中通过OpenAI Chat（/v1/chat/completions）、Claude Messages（/v1/messages）与Codex Responses（/v1/responses）三种协议入口接入 DeepSeek，包括渠道配置字段、模型映射规则、非标准 Chat role 规范化开关、视觉能力关闭与自动 failover，以及配置验证与故障排查。读完本文，你将能在单个 CCX 实例上同时服务 Claude Code CLI、Codex CLI/App 和任意 OpenAI 兼容工具，并让图片请求自动绕过 DeepSeek 路由到视觉渠道。

前置准备：获取 DeepSeek API Key

1. 访问 DeepSeek 开放平台（platform.deepseek.com）；
2. 注册并登录账号；
3. 进入 API Keys 页面；
4. 点击「创建 API Key」，复制生成的密钥。

该密钥将作为渠道的API Keys字段填入 CCX 管理界面。注意：DeepSeek API Key 仅用于 CCX 与上游之间的认证，客户端工具（Claude Code / Codex / OpenAI 兼容工具）使用的则是 CCX 自己的代理密钥（PROXY_ACCESS_KEY），两者不要混淆。

提示：PROXY_ACCESS_KEY通过环境变量注入，默认值可在 backend-go/.env.example 中查看，实际解析逻辑位于 backend-go/internal/config/env.go。若配置了EXTRA_PROXY_ACCESS_KEYS，管理界面与代理 API 会采用独立的ADMIN_ACCESS_KEY认证。

工作原理：一个 CCX 实例承载三种协议

CCX 通过协议入口隔离 + 上游端点映射的方式支持 DeepSeek：

Claude Code CLI ──→ /v1/messages ──→ CCX ──→ DeepSeek Anthropic 端点 Codex CLI/App ──→ /v1/responses ──→ CCX ──→ DeepSeek Chat 端点 OpenAI 兼容工具 ──→ /v1/chat/completions ──→ CCX ──→ DeepSeek Chat 端点

从源码看，这条双端点映射并非手写约定，而是由内置模型清单固化下来的：仓库 shared/builtin-models-manifest/builtin-models-manifest.json 为 DeepSeek 注册了两个 manifest 条目：

也就是说：Messages 入口的渠道应指向https://api.deepseek.com/anthropic，而 Chat / Responses 入口的渠道应指向https://api.deepseek.com。一个 CCX 实例可以同时服务所有路径，按需配置对应协议的渠道即可，互不干扰。

场景一：OpenAI Chat 协议（通用）

适用于所有兼容 OpenAI Chat 协议的工具，例如各类 ChatBox、OpenCat、自研脚本、curl直连等。

配置步骤

1. 进入 CCX 管理界面，选择Chat入口；
2. 点击「添加渠道」，切换到详细配置模式；
3. 填写以下信息：

4. 保存。

客户端配置

任意 OpenAI 兼容客户端只需把 Base URL 指向 CCX 的/v1路径，密钥换成 CCX 代理密钥：

export OPENAI_API_KEY="your-ccx-proxy-key" export OPENAI_BASE_URL="http://localhost:3000/v1"

场景二：Claude Code CLI

Claude Code CLI 使用 Anthropic Messages API。需要在Messages入口配置服务类型为Claude的渠道，上游指向 DeepSeek 的 Anthropic 兼容端点。

配置步骤

1. 进入 CCX 管理界面，选择Messages入口；
2. 点击「添加渠道」；
3. 填写以下信息：

4. 保存。

模型映射（推荐）

Claude Code CLI 默认使用 Claude 模型名（如claude-opus-4-7）发起请求，而 DeepSeek 上游不认识这些名字。在渠道上配置模型映射，让 CCX 自动把 Claude 模型名重定向到 DeepSeek 模型：

客户端配置

export ANTHROPIC_API_KEY="your-ccx-proxy-key" export ANTHROPIC_BASE_URL="http://localhost:3000"

验证：

claude "你好"

⚠️注意：ANTHROPIC_BASE_URL指向 CCX 网关根地址，不要加/v1或/v1/messages。Claude Code 会在该地址基础上自行拼接 Messages API 路径；若多写了/v1，会导致请求路径变成/v1/v1/messages而 404 或Connection refused（参见下文故障排查表）。

场景三：Codex CLI / App

Codex CLI 使用 OpenAI Responses API。需要在Responses入口配置服务类型为OpenAI Chat的渠道，CCX 会在内部把 Responses 请求转换为 Chat Completions 后转发给 DeepSeek。

配置步骤

1. 进入 CCX 管理界面，选择Responses入口；
2. 点击「添加渠道」；
3. 填写以下信息：

4. 保存后，编辑该渠道，启用规范化非标准 Chat role开关：

💡为什么需要启用？Codex 的 Responses 请求被 CCX 转换为 Chat Completions 后，消息数组中可能包含developer等 DeepSeek 不支持的 role。启用此选项后，CCX 会在发往上游前将这类非标准 role 规范化为user。

从源码看，该能力在配置层面对应兼容 traitnormalize_nonstandard_chat_roles（定义于 backend-go/internal/config/channel_compat_cache.go），注释明确指出其语义是"上游只接受标准 Chat role，需把非标准 role 降为 user"；生效判断函数IsNormalizeNonstandardChatRolesEnabled()位于 backend-go/internal/config/config.go，默认返回false（不降级），因此对 DeepSeek 这类只认标准 role 的上游，必须显式打开该开关或依赖 CCX 的运行时自动学习（trait 学习机制见 backend-go/internal/config/config_loader.go）。

模型映射（推荐）

Codex CLI/App 默认使用 GPT 模型名，配置映射让 CCX 自动重定向：

💡映射规则：CCX 优先使用更长的匹配键。gpt匹配gpt-5等常规模型，mini匹配gpt-5-mini等轻量模型。不要把 pro 路由键写成gpt-5，否则gpt-5-mini会先命中gpt-5，轻量请求被错误路由到旗舰模型。

客户端配置

Codex CLI：

export OPENAI_API_KEY="your-ccx-proxy-key" export OPENAI_BASE_URL="http://localhost:3000/v1" codex "你好"

Codex App（VS Code / JetBrains 插件）：

可用模型一览

在仓库的内置模型清单中，DeepSeek 官方端点还暴露了更多型号：deepseek-flash、deepseek-v4.1-flash、deepseek-v4-flash-vision-exp等（见 shared/builtin-models-manifest/builtin-models-manifest.json）。模型能力画像注册在 shared/model-registry/ccx_model_registry.json，例如 DeepSeek V4.1 Flash 在注册表中声明了 1M 上下文窗口（contextWindowTokens: 1000000）、thinkingMode: thinking、reasoningEfforts: [low/high/max]，以及vision: true、jsonOutput: true、toolCalls: true、contextCaching: true等能力位。

⚠️版本差异提醒：文档与本文的示例模型名以当前配置指南为准；实际可用型号以渠道modelsUrl（https://api.deepseek.com/models）返回为准，模型注册表与内置清单会随上游迭代更新，配置时建议以管理界面中渠道测试返回的真实模型名为依据。

图片 / 视觉支持：关闭后自动 failover

DeepSeek 上游不支持图片输入。在 CCX 中配置 DeepSeek 渠道时，建议关闭视觉支持：编辑渠道时点击右上角的眼睛图标，使其变为关闭状态。

关闭后的行为：

• 纯文本请求正常路由到 DeepSeek 渠道；
• 包含图片的请求会自动跳过该渠道，failover 到调度队列中下一个支持视觉的渠道；
• 无需手动干预，CCX 会自动完成路由切换。

如果你同时配置了 DeepSeek（纯文本）和另一个支持视觉的渠道，CCX 会智能区分请求类型：图片请求走视觉渠道，文本请求仍走 DeepSeek，两类流量互不挤占。

从源码看，这一行为由两个机制共同保障：

1. 渠道能力位：NoVision字段（"整个渠道不支持图片输入"）定义于 backend-go/internal/config/config.go，关闭视觉开关即写入该能力位；
2. 路由否决原因：智能路由器在候选筛选中遇到不支持图片的渠道时，会追加vision_unsupported否决原因（见 backend-go/internal/autopilot/smart_router.go），该原因同样登记在 backend-go/internal/autopilot/trace_contract.go 的路由追踪契约中；同时 backend-go/internal/handlers/common/failover.go 负责对上游"图片输入不被支持"类错误进行分类并触发下一渠道重试。

验证配置

渠道保存后，可通过 CCX 的模型列表接口验证：

curl http://localhost:3000/v1/models \ -H "Authorization: Bearer your-ccx-proxy-key"

返回的模型列表中应包含你配置的 DeepSeek 模型。更进一步的验证方式是直接发起一次最小请求（Chat 入口）：

curl http://localhost:3000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-ccx-proxy-key" \ -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}]}'

故障排查

补充两个高频细节：

• 角色报错：若在 Responses/Codex 场景收到"developerrole 不被上游接受"类错误，说明「规范化非标准 Chat role」开关未生效——检查渠道是否在保存后二次编辑并开启了该开关（对应 traitnormalize_nonstandard_chat_roles的默认关闭语义见 backend-go/internal/config/config_baseurl_test.go 的测试用例）。
• 视觉请求走错渠道：若图片请求仍被路由到 DeepSeek 渠道并报"图片输入不被支持"，请确认视觉开关已关闭（NoVision能力位），并确认存在其他支持视觉的可用渠道供 failover。

进阶阅读：模型解析与自动映射机制

除管理界面的模型映射表外，CCX 的智能路由层还内置了**模型画像自动解析（AutoResolve）**能力：配置项modelMapping.autoResolve定义于 backend-go/internal/config/autopilot_config.go，默认开启；模型解析器会依据模型注册表（shared/model-registry/ccx_model_registry.json）把请求模型解析为渠道可用的实际模型名，并校验能力下限（CapabilityFloorEnabled，见 backend-go/internal/autopilot/model_resolver.go）。这意味着除了 UI 上的显式映射，DeepSeek 渠道还可以享受"客户端写deepseek-v4-pro、网关自动匹配画像与价格"的一站式解析体验——两者可以配合使用：显式映射负责把 Claude/GPT 模型名"翻译"成 DeepSeek 模型名，AutoResolve 负责后续的画像校验与候选收敛。

总结

在 CCX 中接入 DeepSeek 的核心要点可归纳为三条：

1. 协议分入口、端点分清单：Chat/Responses 渠道用https://api.deepseek.com，Messages 渠道用https://api.deepseek.com/anthropic，内置清单 shared/builtin-models-manifest/builtin-models-manifest.json 已固化该映射；
2. 模型映射解决"名字不对"：Claude Code 用opus/sonnet/haiku三段映射，Codex 用gpt/mini两段映射，注意匹配键的最长优先规则；
3. 视觉开关解决"能力不对"：DeepSeek 渠道关闭视觉支持后，图片请求自动vision_unsupported否决并 failover 到视觉渠道（NoVision能力位 + backend-go/internal/autopilot/smart_router.go 路由原因）。

按本文三个场景完成配置后，你就可以用同一个 CCX 网关，让 Claude Code、Codex 与任意 OpenAI 兼容工具无缝共享 DeepSeek 的模型能力了。

• API网关
• LLM 网关
• 后端