NexusKey 文档

深色模式

DeepSeek V4 Pro 接入指南 ​

本文说明如何通过 NexusKey API Key 在 Claude Code、Codex、DeepSeek Harness 和 OpenAI 兼容客户端中选择 deepseek-v4-pro。这里的 Claude 指 Claude Code；不代表 Claude 官网聊天、普通 Claude 桌面聊天可以直接替换底层模型。

当前开放状态 · 2026-10-26 核验

当前核验的 Nexus 综合分组 Key 尚未获得 DeepSeek V4 Pro 的可用路由：该 Key 的 /v1/models 不包含 deepseek-v4-pro，Chat Completions、Anthropic Messages、Responses 三条路径的短请求均返回 503。

因此，以下是渠道开通后的接入步骤与配置样例，不是“目前已全客户端可用”的承诺。先由管理员确认 Pro 渠道、模型授权、费率及余额，再按本文验收；反复修改客户端配置不能解决渠道未开放。

deepseek-v4-flash-0731 免费体验是另一种模型与权限，不包含 Pro。请勿把 Flash 的成功回复当作 Pro 已接通。

1. 准备正确的 Key、模型和地址 ​

项目填写内容
控制台nexuskey.cn
API Key从 Nexus 控制台「API 密钥」创建的 Key
目标模型 IDdeepseek-v4-pro
OpenAI Chat / Responses Base URLhttps://nexuskey.cn/v1
Claude Code / Anthropic SDK Base URLhttps://nexuskey.cn
Harness OpenAI 兼容 provider Base URLhttps://nexuskey.cn/v1

1.1 控制台操作顺序 ​

  1. 登录控制台，确认账户可使用包含 Pro 的分组。若分组尚未开放，先联系管理员；创建 Key 不会自动开通模型。
  2. 在「API 密钥」创建一把专用于此客户端的 Key，绑定管理员指定的分组，设置合理额度与到期时间。
  3. 确认有效余额或该分组要求的计费条件。Pro 以 Nexus 显示的实际费率计费，免费 Flash 订阅、Claude 订阅和 ChatGPT 订阅不能抵扣这把 Nexus Key 的费用。
  4. 完成下面的模型查询和最小请求，成功后再接入编程代理。

不要填写 DeepSeek 官网 Key、控制台登录密码、浏览器登录令牌，或其他平台的 Key。不同平台的 Key 不能混用。也不要假设任意分组都会包含 Pro。

1.2 在终端安全设置 Key ​

macOS / Linux，使用 Python 的隐藏输入，避免把真实 Key 直接写进 shell 历史：

bash
export NEXUSKEY_API_KEY="$(python3 -c 'import getpass; print(getpass.getpass("Nexus API Key: "))')"

Windows PowerShell：

powershell
$secret = Read-Host "Nexus API Key" -AsSecureString
$env:NEXUSKEY_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
Remove-Variable secret

以上只为当前终端及其子进程设置变量。不要把真实 Key 写进项目、Git 仓库、截图或工单；分享日志时删除认证头。更换泄露的 Key 时，在控制台撤销旧 Key。

1.3 先查询，再实调 ​

下面的 curl 示例用于 macOS / Linux；PowerShell 中请使用 curl.exe 并按本机 shell 的规则传入 JSON。

bash
curl --fail-with-body -sS --max-time 30 \
  https://nexuskey.cn/v1/models \
  -H "Authorization: Bearer $NEXUSKEY_API_KEY"

确认 data 数组中有精确模型名 deepseek-v4-pro。控制台里显示模型名称、模型目录里有一条声明、客户端下拉框能选中，均不能单独证明该 Key 可以生成。

再调用原生 Chat 接口：

bash
curl --fail-with-body -sS --max-time 120 \
  https://nexuskey.cn/v1/chat/completions \
  -H "Authorization: Bearer $NEXUSKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"只回复 PRO_OK"}],"max_tokens":128}'

需要看到正常回答、正确的响应模型字段及 usage。若输出全部用于推理、finish_reason 为 length 或没有最终文本，不能算成功；按分组支持的参数调整输出预算后重新验证，不要无上限放大重试。

验收流式时，在同一 JSON 中加入 "stream":true 和 "stream_options":{"include_usage":true}，curl 加 -N。检查最终结束标记与 usage；Chat SSE 应正常收到 [DONE]。若该分组不支持流内 usage，应改查 Nexus 用量记录，不能仅凭文本认定计量正常。

2. Claude Code ​

2.1 协议和地址 ​

Claude Code 使用 Anthropic Messages。Nexus 的地址是 https://nexuskey.cn，由客户端请求 /v1/messages。

不要把 DeepSeek 官网教程中的 https://api.deepseek.com/anthropic 原样复制到 Nexus 配置；Nexus 不依赖该官网专用路径。也不要把 /v1/chat/completions 填作 Claude Code 的 Base URL。

2.2 推荐：仅当前启动使用 Pro ​

先完成第 1 节的 Key 设置，在 macOS / Linux 终端运行：

bash
env -u ANTHROPIC_API_KEY \
  ANTHROPIC_BASE_URL="https://nexuskey.cn" \
  ANTHROPIC_AUTH_TOKEN="$NEXUSKEY_API_KEY" \
  ANTHROPIC_MODEL="deepseek-v4-pro" \
  ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro" \
  ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro" \
  ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-pro" \
  ANTHROPIC_DEFAULT_FABLE_MODEL="deepseek-v4-pro" \
  CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-pro" \
  claude --model deepseek-v4-pro

这样不会覆盖已有 ~/.claude/settings.json。同时覆盖模型族别名和子代理模型，是为了避免主会话已经选 Pro，某个辅助调用仍请求 claude-*。旧版客户端可能没有 Fable 别名；保留该变量不代表当前分组支持 Claude Fable。

使用 ANTHROPIC_MODEL，不要依赖没有在这里验证的 CLAUDE_MODEL。如果已有 apiKeyHelper、托管配置或服务端凭据注入，还需检查它们是否覆盖本次认证配置；不要删除原有 OAuth 凭据或项目设置来试错。

PowerShell 可设置对应 $env:ANTHROPIC_* 变量后运行 claude --model deepseek-v4-pro；将 $env:ANTHROPIC_AUTH_TOKEN 设为 $env:NEXUSKEY_API_KEY，并清除当前会话中冲突的 $env:ANTHROPIC_API_KEY。

2.3 持久配置与回退 ​

需要长期使用时，在备份后合并以下字段到用户级 ~/.claude/settings.json。其中 Key 占位符必须换成你自己的真实 Key；Claude 不会自动把这个字符串当作 shell 环境变量展开。

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://nexuskey.cn",
    "ANTHROPIC_AUTH_TOKEN": "<NEXUS_API_KEY>",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-pro",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-pro"
  },
  "model": "deepseek-v4-pro"
}

不要用这个片段替换整个文件：保留权限、hooks、插件等原有设置。该文件含凭据，应仅当前用户可读。回退时恢复备份，或仅移除本次添加的环境变量和模型字段；重新打开终端及会话。第 2.2 节的单次启动退出后，原来的默认配置仍在。

2.4 Claude 专项验收 ​

先验证 Nexus 的 Messages 协议：

bash
curl --fail-with-body -sS --max-time 120 \
  https://nexuskey.cn/v1/messages \
  -H "x-api-key: $NEXUSKEY_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-pro","max_tokens":128,"messages":[{"role":"user","content":"只回复 PRO_OK"}]}'

然后在新 Claude Code 会话检查 /model，发送简短问题，再在你允许的测试目录验证一次读取文件、一次修改与检查。使用代理前还要确认 tool_use → tool_result 多轮正常；普通文本成功不代表工具链已兼容。

不要沿用指向 Claude 的旧会话来证明 Pro 已切换；也不要让 --fallback-model 自动切换到其他模型后，将成功误记为 Pro 成功。

3. Codex CLI、IDE 扩展与桌面客户端 ​

3.1 Codex 需要 Responses ​

当前 Codex 的自定义 provider 使用 wire_api = "responses"，不是 chat。必须验证 Nexus 的 /v1/responses 支持 Pro；仅 /v1/chat/completions 成功不能证明 Codex 可以使用。

此外，Codex 原生模型目录使用 models 数组与 slug；普通 OpenAI /v1/models 的 data/id 清单不是同一格式，不能直接改个 URL 当作 Codex 模型目录。

3.2 准备模型目录 ​

下载 Codex 模型目录样例，保存为：

text
~/.codex/nexus-deepseek-models.json

本样例已通过 Codex CLI 0.164.0 的本地目录解析，采用保守的 65,536 token 文本上下文，不声明图片、联网搜索或完整 1M 能力。它只提供客户端识别模型所需的元数据，不会开通 Nexus 路由，也不是实际生成或工具兼容性的实测证明。

客户端版本升级后，应按该版本的 Codex Models 格式复核目录；不要直接复用 GPT 的能力声明。若管理员提供经过验证的 Codex 原生目录，优先使用管理员的版本。

3.3 保留原配置，新增独立 profile ​

下载 Codex provider/profile 样例，将它合并到用户级 ~/.codex/config.toml：

toml
[model_providers.nexus_deepseek]
name = "Nexus DeepSeek"
base_url = "https://nexuskey.cn/v1"
env_key = "NEXUSKEY_API_KEY"
wire_api = "responses"
requires_openai_auth = false

[profiles.nexus_deepseek_pro]
model = "deepseek-v4-pro"
model_provider = "nexus_deepseek"
web_search = "disabled"

不要重复创建已经存在的 TOML 表；也不要把 provider 放进项目级 .codex/config.toml。不要设置 requires_openai_auth = true，否则会走 OpenAI 登录逻辑，不能据此使用 Nexus 的环境变量 Key。

启动专用会话：

bash
codex --profile nexus_deepseek_pro \
  -c "model_catalog_json=\"$HOME/.codex/nexus-deepseek-models.json\""

模型目录通过本次启动的 -c 显式指定，$HOME 会展开为本机绝对路径，不需要替换已有全局模型目录。这样保留原有全局默认模型。启动后检查所选 provider 和模型；回退时退出该会话，下次不加这个 profile，或恢复修改前的配置备份。

3.4 Codex 专项验收 ​

先测 Responses：

bash
curl --fail-with-body -N -sS --max-time 120 \
  https://nexuskey.cn/v1/responses \
  -H "Authorization: Bearer $NEXUSKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-pro","input":"只回复 PRO_OK","max_output_tokens":128,"stream":true,"store":false}'

必须有正常文本和成功的 response.completed，不能只检查 HTTP 200，也不能将 Chat 的 [DONE] 当作 Responses 完成事件。再启动 Codex 验证一个完整工具调用及结果续接；支持 previous_response_id、无状态历史、function/custom tools 等哪些组合，应以该分组的实际验收为准。

本次核验中，Pro 的 Responses 短请求返回 503，尚未进行成功的 Codex 端到端或工具链验收。不要通过 wire_api = "chat"、无限重试或开启 WebSocket 来绕过渠道问题。

3.5 IDE 与桌面端注意事项 ​

CLI、IDE 扩展和桌面端会读取用户级配置，但选中的 profile、应用内 provider 设置和环境变量继承未必一致。CLI 的 --profile 生效，不等于已经运行的 GUI 自动切换。

  • 完全重启相应客户端，检查它实际采用的模型/provider。
  • 从 Dock 或开始菜单启动的应用，通常不会继承当前终端刚 export 的 Key；应使用客户端或组织支持的凭据注入方式。
  • 如果版本没有 profile 切换入口，备份后将所需 model、model_provider、model_catalog_json、web_search 放到用户配置第一个 TOML 表之前作为顶层字段，并保留其余配置。这样会改变默认模型，完成后按备份回退。
  • 不要把真实 Key 放进模型目录、共享 TOML 样例或项目 Git 仓库。

4. DeepSeek Harness ​

4.1 新增独立 provider ​

这里以核对过的 dsh 0.1.1-rc.2 配置格式为例。推荐新增 nexus-deepseek provider，使用 OpenAI Chat 兼容接口，不覆盖已有 llm-deepseek 的本地 Flash/官方直连配置。

下载 Harness 配置覆盖层：

yaml
- id: llm-pi-ai
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      nexus-deepseek:
        displayName: Nexus DeepSeek
        apiKeyEnv: NEXUSKEY_API_KEY
        api: openai-completions
        baseURL: https://nexuskey.cn/v1
        compat:
          thinkingFormat: deepseek
        models:
          - id: deepseek-v4-pro
            name: DeepSeek V4 Pro · Nexus
            contextWindow: 65536
            maxTokens: 4096
            input: [text]
            reasoningEfforts: false

其中 baseURL、apiKeyEnv 的大小写，以及协议值 openai-completions 都有意义。不要写成完整的 /v1/chat/completions URL。这里的上下文和输出是保守客户端预算，不能用来推断模型服务的真实上限。

thinkingFormat: deepseek 用于 DeepSeek 风格的推理字段兼容，不会把一个未开放的模型变成可用。样例暂不向用户宣告推理档位能力；需要启用时先确认该分组接受的参数与多轮推理工具调用格式。

4.2 个人实例与托管实例 ​

个人实例：先按第 1 节设置环境变量，把覆盖层保存到本机，例如 ~/.config/nexus/harness-nexus-pro.yml，再为该实例的启动命令添加：

bash
dsh --patch "$HOME/.config/nexus/harness-nexus-pro.yml" web

不要在同一端口重复启动另一个已有实例。该示例只说明启动参数，不会自动替你安装依赖、开通模型或修改已运行的服务。

托管/共享实例：由管理员把覆盖层和 NEXUSKEY_API_KEY 配置到 Harness 后端进程的运行环境，再按实例规则加载。仅在你打开浏览器的电脑上 export 变量，不会改变远端 Harness 的凭据。不要把真实 Key 填进消息框或前端网页脚本。

共享实例的模型选择在某些版本会保存为全局默认；建议使用独立配置/实例，或先确认管理员的切换规则。保留现有 provider 和其他用户会话，普通使用者不要为接入 Pro 擅自重启共享服务。

4.3 在 UI 中选择并验证 ​

  1. 打开模型选择器，选择 Nexus DeepSeek → DeepSeek V4 Pro · Nexus。
  2. 新建会话，先发送“只回复 PRO_OK”。
  3. 确认会话实际请求的是 nexus-deepseek / deepseek-v4-pro，且已正常结束。
  4. 在控制台用量中核对模型及本次费用；确认没有请求到原有 Flash 或其他模型。
  5. 基础对话通过后，再验证一个受允许的工具调用、多轮对话和流式结束。

能在选择器看到新模型，只能证明本地目录配置已加载。若仍显示本地 Flash，通常是没有切换模型、仍在旧会话、覆盖层未加载或后端未读到环境变量。

5. 其他客户端与 SDK ​

客户端配置
Cursor、Cline、Roo Code、Cherry Studio选择 OpenAI 兼容提供商，Base URL 为 https://nexuskey.cn/v1，Key 为 Nexus Key，模型手动填 deepseek-v4-pro；具体功能以客户端版本及协议验收为准
OpenAI SDK设置 base_url="https://nexuskey.cn/v1"，Key 从环境变量读取
Anthropic SDK设置 base_url="https://nexuskey.cn"，用 Nexus Key，经 Messages 调用

Python OpenAI SDK 示例：

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEXUSKEY_API_KEY"],
    base_url="https://nexuskey.cn/v1",
)
result = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "只回复 PRO_OK"}],
    max_tokens=128,
)
print(result.choices[0].message.content)

不要直接开启图片、文件上传、网页搜索、1M 上下文或大规模并发。模型官网支持某项能力，不代表 Nexus 当前分组、协议桥接和所用客户端的组合已经验收；应逐项确认。

6. 排错与验收清单 ​

现象先检查什么
401是否用了 Nexus Key，是否失效/被撤销，认证头及后端环境变量是否正确；控制台登录令牌不是 API Key
402 / 余额或配额不足余额、Key 额度、所选分组/订阅条件；不要把免费 Flash 的额度当作 Pro 额度
403分组/来源/账户权限；不要关闭认证或代理的访问控制来试错
404 / model_not_found模型名必须精确为 deepseek-v4-pro，Key 分组必须授权该模型，Base URL 不应重复 /v1
429速率、并发或额度限制；按 Retry-After 等待，不要并发放大重试
503当前分组可能没有可用 Pro 渠道，或渠道正在恢复；先联系管理员查路由与账户状态。本次核验就是此情况
Chat 成功、Claude Code 失败单独验收 Messages、流式与工具转换，检查子代理是否仍请求其他模型
Chat 成功、Codex 失败单独验收 Responses、response.completed、目录格式和工具结果续接；不要改成 wire_api=chat
Harness TRANSPORT从 Harness 后端检查到 Nexus 的网络、代理与证书，确认 Base URL 和后端凭据；不等同于模型理解失败
GUI 提示环境变量不存在检查实际应用进程的环境；当前终端中有变量，不代表已启动的 GUI 或远端服务有变量
调通了但模型不对对照请求、响应及 Nexus 用量记录中的模型；模型自我介绍和 UI 名称不能单独作为证明

管理员或使用者交付“已可用”之前，应逐项确认：

  • [ ] 当前 Key 查询得到精确 Pro 模型，最小生成成功。
  • [ ] 所用客户端的协议、流式完成事件和至少一轮工具续接通过。
  • [ ] 模型没有自动回退，Key 的分组、模型和用量记录对应。
  • [ ] 费用、限额与凭据存放符合你的预期，原配置能够回退。

7. 核验范围与参考 ​

本页已核验：Nexus 实际分组授权查询及三协议短请求的未开放结果；Claude Code 2.1.289 的相关 CLI 入口；Codex CLI 0.164.0 的目录本地解析；dsh 0.1.1-rc.2 的 provider 配置字段。

本页未声称通过：Pro 在 Nexus 上成功生成、Claude/Codex/Harness 的 Pro 端到端运行、工具调用、长上下文、图片、联网搜索或 WebSocket。开通后应重新执行上述验收，并更新这段状态。

NexusKey · 一个 Key 接入多协议模型 API

Copyright © 2026 NexusKey