DeepSeek-V4-Pro 接入 Codex 的难点不在模型本身而在配置模型名、指定 API 地址、处理客户端校验报错这三个环节。这篇教程会从零开始先安装最新版 Codex CLI再把 DeepSeek-V4-Pro 配成 Codex 的模型提供方最后通过一个识图 Skill 把视觉能力补上。整个过程按可复现的方式展开所有命令和配置都可以直接复制到自己的环境里实验再根据实际报错调整。Codex 命令行工具提供了交互式编程助手能力但真正决定“能不能用”的是它背后的模型提供方配置。DeepSeek-V4-Pro 如果通过一个 OpenAI 兼容端点提供Codex 就能通过自定义 provider 方式接入。最容易出问题的地方也在这里客户端、模型、服务端三者的名称不统一时会出现deepseek-v4-pro is not a model this version of claude code recognizes或者the supported api model names are deepseek-v4-pro, deepseek-v4-flash...这类 400 错误。文章会把这几个报错拆开解释并给出对应的排查顺序。1. 接入前先分清 Codex、Claude Code 和模型提供方1.1 三类对象不是同一个东西很多同学看到“接入”两个字第一反应是找一个配置文件把模型名填进去。但 Codex CLI、Claude Code 和 DeepSeek-V4-Pro 在项目中扮演的角色完全不同。Codex CLI 是 OpenAI 推出的命令行编程助手负责接收你的自然语言指令调用模型执行命令或读写文件。Claude Code 是 Anthropic 的同类工具适合 Claude 模型和 Anthropic 生态。DeepSeek-V4-Pro 是模型名真正处理文本理解和代码生成的是它而不是 Codex 或 Claude Code 本身。这三者一旦混在一起就会产生一个非常典型的现象你在 Claude Code 的配置文件里写了deepseek-v4-pro但 Claude Code 不认这个模型名于是报出deepseek-v4-pro is not a model this version of claude code recognizes。这个报错不是 Codex 的问题也不是 DeepSeek 模型的问题而是你配置到了一把打不开这把锁的“钥匙环”上。1.2 两类工具使用不同的配置文件Codex 和 Claude Code 各自维护自己的配置目录不能共用。Codex 使用~/.codex/config.toml管理模型提供方和默认模型Claude Code 使用~/.claude/settings.json管理 API 配置和模型信息。工具配置文件主要用途Codex CLI~/.codex/config.toml设置默认模型、模型提供方、API 地址、环境变量Claude Code~/.claude/settings.json设置 Anthropic API 配置、模型名称、权限策略如果你本来想用 Codex却把 API Key 和模型名写进了~/.claude/settings.jsonCodex 启动后读取不到配置启动后仍会使用默认模型。反过来如果你把 DeepSeek-V4-Pro 写进 Claude Code就会出现“该版本无法识别这个模型”的提示。实际操作时先确认自己要用哪个 CLI再决定改哪个配置文件。本教程以 Codex 为例所有配置都放到~/.codex/config.toml。1.3 模型名校验为什么失败模型名校验由谁负责取决于请求到达的位置。Codex 客户端会把model字段作为普通请求参数发给 API不会自己去判断“DeepSeek-V4-Pro”是否合法。API 服务端收到请求后如果支持的模型列表里没有这个名字就会返回 400并附带支持的模型名列表。报错信息里出现the supported api model names are deepseek-v4-pro, deepseek-v4-flash...时说明服务端支持这些名称但你的请求里写的 model 与它不完全一致。可能的差异包括大小写、前缀、版本号中的空格或短横线以及是否携带了deepseek/这种命名空间前缀。理解这一层之后再看到任何“is not a model … recognizes”类错误就不会急着改 Codex 配置而是先问一句这个报错来自哪个工具配置写到了哪个配置文件API 服务端真正支持哪些模型名。2. 安装最新版 Codex CLI 并验证二进制可用2.1 推荐使用官方安装命令而不是第三方安装包标题里提到的“最新版 Codex 安装包”有两点需要提醒第一不要相信来路不明的压缩包或网盘安装包这些文件可能内置了修改过的二进制存在密钥窃取风险第二正确做法是使用官方渠道或者下载后校验哈希。以 npm 安装为例先查看最新版本号再安装npm config get registry npm view openai/codex dist-tags.latest npm install -g openai/codex安装完成后检查版本codex --version如果网络环境不便使用 npm也可以去官方 GitHub Releases 页面下载对应平台的二进制文件。下载后不要立刻解压运行先校验哈希shasum -a 256 codex-darwin-arm64将输出结果和官方页面提供的 SHA256 摘要对比一致后再放入 PATH 目录。2.2 Windows、macOS、Linux 的 PATH 处理Codex 安装完成但命令找不到时一般不是没装上而是 PATH 没配好。Windows 用户安装 npm 全局包后可执行文件通常位于 npm 目录的上一层或全局 node_modules 所在目录macOS 和 Linux 用户则常常安装在/usr/local/bin或用户目录下的.npm-global/bin。先看实际安装到了哪里npm prefix -g ls -l $(npm prefix -g)/bin/codex如果输出中存在codex再把这个目录加入 PATHexport PATH$(npm prefix -g)/bin:$PATHmacOS 用户也可以使用 Homebrew 安装具体命令以 Homebrew 官方 formula 为准。但无论哪种方式安装后要执行一次版本验证避免后续错误都被错误归因到模型配置上。2.3 找不到 Codex CLI 二进制时的处理在某些 IDE 插件或桌面端工具中即使 CLI 已经安装也会出现unable to locate the codex cli binary. set codex cli path or ensure the elec...这样的提示。这是因为宿主程序没有读取到 PATH或没有按它自己的规则定位 Codex。常见做法是设置CODEX_CLI_PATH环境变量直接指向二进制文件的绝对路径export CODEX_CLI_PATH$HOME/.codex/bin/codex先确认这个路径下确实有可执行文件再重新启动宿主程序。修改环境变量后如果是在图形界面里启动的工具最好先注销当前 shell 或重启编辑器确保变量被重新加载。2.4 安装完成后先跑通最小命令建议不要直接进入复杂配置先执行一次最简单的帮助命令codex --help正常情况下会输出可用的子命令选项。看到exec、login、install等条目说明 CLI 能正常运行。接下来再进入~/.codex/config.toml配置模型提供方。注意只验证codex --version还不够要继续验证codex exec ping能发起一次真实模型请求才能确定 API Key 和模型配置都正确。3. 把 DeepSeek-V4-Pro 配置成 Codex 的模型提供方3.1 配置文件的最小结构Codex 的模型提供方配置放在~/.codex/config.toml中。下面是一个最小可运行的示例model deepseek-v4-pro model_provider deepseek model_reasoning_effort medium [model_providers.deepseek] name DeepSeek base_url https://api.example.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这段配置里model deepseek-v4-pro是默认模型名model_provider deepseek指向下方定义的 provider 块base_url是服务商提供的兼容地址env_key是从哪个环境变量读取 API Key。wire_api字段需要特别注意。如果服务商提供的是/v1/chat/completions这种 OpenAI Chat Completions 格式就写chat如果服务商提供的是responses接口可能需要写responses。不确定时优先用 curl 验证一次接口再决定。3.2 关键参数说明配置看似简单但任何一个字段填错都会出现难以定位的报错。下面把常用参数列成速查表。参数含义常见值填错时的表现model发送给 API 的默认模型名deepseek-v4-pro400模型名不存在model_provider使用下方哪个 provider 配置deepseek找不到 providerbase_urlAPI 服务地址需包含接口前缀https://api.example.com/v1404、401、连接失败env_key存放 API Key 的环境变量名DEEPSEEK_API_KEY401 或权限不足wire_api客户端与服务端的协议格式chat、responses400请求格式不匹配model_reasoning_effort推理强度low、medium、high部分服务端不支持该字段很多 400 错误并不是 Key 不对而是base_url少了/v1。如果接口地址是https://api.example.com/v1/chat/completionsbase_url就应该写https://api.example.com/v1不要把完整的chat/completions也写进去。3.3 设置 API Key 环境变量不要直接把 API Key 明文写进config.toml。正确方式是通过环境变量export DEEPSEEK_API_KEYsk-xxxxxx为了让配置长期生效把这一行写入当前 shell 的~/.bashrc或~/.zshrc中。随后检查是否读取成功echo ${#DEEPSEEK_API_KEY}如果输出数字大于 0说明变量已设置。此处使用${#}是为了避免把完整 Key 打印到日志或终端记录中。3.4 用 curl 验证接口连通性配置 Codex 之前先用 curl 直接请求一次 API这样做可以把“服务端是否可用”和“Codex 配置是否正确”分开排查。以 Chat Completions 接口为例curl -sS https://api.example.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-v4-pro, messages: [{role: user, content: ping}] }如果服务商使用 Responses 接口则改成curl -sS https://api.example.com/v1/responses \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-v4-pro, input: ping }正常响应会返回choices或output字段。如果返回the supported api model names are...就把model改成服务端列出的名字注意保持大小写一致。3.5 回到 Codex 验证一次请求curl 验证通过后再执行codex exec ping如果输出正常说明 DeepSeek-V4-Pro 已经被 Codex 正确调用。如果仍然报 400查看 Codex 实际发出的请求体通常可以用 debug 模式或查看日志。多数情况下问题出在wire_api与接口不匹配或者model名称多了一个空格。注意不要在一个接口用chat格式、在另一个接口用responses格式最后却在config.toml中写反了协议类型。curl 测一次Codex 测一次两边结果对齐后再继续下一步。4. 给 Codex 加一个识图 Skill 补齐视觉能力4.1 为什么需要 SkillDeepSeek-V4-Pro 如果只支持文本输入你直接把图片路径传给模型模型看不到图片内容。此时需要一个识图 Skill通过脚本把图片发给支持视觉输入的模型再把返回结果交还给 Codex。如果把 Skill 理解成“一个人为定义的工具包”就很容易明白模型看到图片路径后知道调用你写好的脚本脚本负责图片编码、请求视觉模型、返回文字描述模型再根据返回结果回答用户。整个过程不需要修改模型权重也不需要更换 Codex 主模型。不同 Codex 版本对 skill 的加载方式可能不一致。本教程采用“脚本 全局指令”的轻量实现不依赖特定 skill 协议多数版本都能使用。4.2 创建 Skill 目录结构在用户目录下创建mkdir -p ~/.codex/skills/image-describe/scripts目录结构如下~/.codex/skills/image-describe/ ├── SKILL.md └── scripts/ └── describe_image.shSKILL.md负责告诉模型“这个 skill 是干什么的”describe_image.sh负责真正执行图片识别。4.3 编写 SKILL.md# image-describe 当用户提供本地图片路径或图片 URL 时使用这个 skill 识别图片内容。 ## 触发条件 - 用户请求描述图片 - 用户上传图片文件 - 用户给出图片路径询问图片内容 ## 使用方式 执行以下脚本 bash ~/.codex/skills/image-describe/scripts/describe_image.sh 图片路径 脚本会把图片编码后发送给视觉模型并输出文字描述。SKILL.md 的核心作用不是给用户看而是给模型看。因此描述要尽量明确触发条件和调用方式避免模型在真正需要时不知道该调用哪个脚本。4.4 编写识别脚本脚本负责将本地图片转成 base64再调用视觉模型接口。下面是一个 Open AI 兼容格式的示例#!/usr/bin/env bash set -euo pipefail IMAGE_PATH${1:-} if [[ -z $IMAGE_PATH ]]; then echo 请提供图片路径 exit 1 fi if [[ ! -f $IMAGE_PATH ]]; then echo 文件不存在: $IMAGE_PATH exit 1 fi BASE_URL${VISION_BASE_URL:-https://api.example.com/v1} API_KEY${VISION_API_KEY:-${OPENAI_API_KEY:-}} MODEL${VISION_MODEL:-gpt-4o-mini} if [[ -z $API_KEY ]]; then echo 未设置 VISION_API_KEY 或 OPENAI_API_KEY exit 1 fi MIME_TYPE$(file --mime-type -b $IMAGE_PATH) BASE64_IMAGE$(base64 $IMAGE_PATH | tr -d \n) PAYLOAD$(cat JSON { model: $MODEL, messages: [ { role: user, content: [ {type: text, text: 请描述这张图片的内容}, {type: image_url, image_url: {url: data:$MIME_TYPE;base64,$BASE64_IMAGE}} ] } ] } JSON ) curl -sS $BASE_URL/chat/completions \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d $PAYLOAD \ | python3 -c import sys,json; print(json.load(sys.stdin)[choices][0][message][content])给脚本添加执行权限chmod x ~/.codex/skills/image-describe/scripts/describe_image.sh脚本中base64 $IMAGE_PATH比base64 -i更兼容macOS 和 Linux 都能使用。file --mime-type -b用于获取图片 MIME 类型如果当前环境没有file命令可以安装file或者直接根据文件后缀设置默认值。4.5 通过全局指令让 Codex 知道这个 Skill创建~/.codex/AGENTS.md文件# 全局指令 - 当用户需要识别图片时使用 image-describe skill。 - 执行识别脚本前先确认图片路径是否存在。 - 如果脚本输出错误将错误信息原样返回给用户不要编造图片内容。Codex 启动时会读取这个文件模型在回答时就知道了 image-describe skill 的存在。4.6 验证识图 Skill在 Codex 交互模式中提问请描述 /tmp/screenshot.png 的内容正常响应会返回图片内容的文字描述。如果返回错误先单独运行脚本排查bash ~/.codex/skills/image-describe/scripts/describe_image.sh /tmp/screenshot.png如果能直接输出文字说明脚本和视觉模型接口正常问题出在 Codex 没有正确调用 skill需要检查 AGENTS.md 是否被读取或者模型在回答时跳过了工具调用。如果脚本输出file: command not found说明缺少file命令。如果输出 JSON 解析错误说明视觉接口返回格式与 Python 解析逻辑不一致需要先打印原始返回内容确认字段名。5. 常见报错排查清单5.1 模型名与配置文件类报错报错现象常见原因检查方式处理建议deepseek-v4-pro is not a model this version of claude code recognizes模型名写进了 Claude Code而 Claude Code 不认这个名称查看~/.claude/settings.json是否存在model字段使用 Codex 时改~/.codex/config.toml不要改 Claude Code 配置the supported api model names are deepseek-v4-pro, deepseek-v4-flash...客户端请求中的 model 与服务端支持的模型名不一致查看服务端返回的模型列表复制完整模型名修正config.toml里的model字段注意大小写和前缀api error: 400 ...base_url 路径错误、wire_api 写错或模型名不匹配用 curl 直接请求服务端接口观察返回信息按 curl 验证结果修改配置配置修改后仍然用默认模型回答修改的文件不是 Codex 读取的文件执行codex --info或查看~/.codex/config.toml是否生效确认配置文件名是config.toml并重启 Codex 会话5.2 CLI 路径类报错unable to locate the codex cli binary. set codex cli path or ensure the elec...是桌面端或插件加载 Codex 时报的错和模型配置无关。按以下顺序排查which codex npm prefix -g ls -l $(npm prefix -g)/bin/codex如果which codex没有输出说明 PATH 里没有 Codex。如果路径存在但插件仍找不到设置export CODEX_CLI_PATH$(npm prefix -g)/bin/codex还要检查环境变量是否真的传到了桌面端进程中。很多图形界面程序不会继承 shell 里临时导出的变量需要把它写入~/.zshrc、~/.bashrc或系统环境变量再重启应用。5.3 本地端点和网络类报错如果错误信息中包含cc switch local proxy failed while handling codex endpoint /responses说明 Codex 配置的base_url指向了本机某个端口但该端口上没有服务在监听。检查方法curl -v http://127.0.0.1:8080/v1/responses如果连接失败确认本机服务是否启动端口是否写对。如果 Codex 配置的 base_url 不是本机端口而是某个远程地址则要确认该地址是否可以从当前网络环境正常访问以及是否需要在环境变量中设置正确的域名解析和访问策略。5.4 识图 Skill 相关报错报错现象常见原因检查方式处理建议file: command not found系统缺少 file 命令which file安装 file或改写 MIME 获取逻辑base64: illegal optionLinux 和 macOS 的 base64 参数差异对比脚本中的写法使用base64 文件方式返回 JSON 解析错误视觉接口返回格式与脚本解析逻辑不符去掉管道直接打印返回 JSON修改 Python 解析字段定位choices[0].message.contentCodex 不调用脚本AGENTS.md 加载失败或模型未理解 skill 描述在 Codex 中询问“你读取了哪些指令文件”检查~/.codex/AGENTS.md是否存在并重启 Codex排查顺序上建议先查“输入是否正确”图片路径、API Key、模型名再查“工具是否可用”curl、file、python3、脚本权限然后查“接口返回”把 curl 原始响应打出来看最后才考虑是不是 Codex 没有正确加载 skill。6. 最佳实践与上线前检查清单6.1 学习环境与生产环境的配置差异学习环境里为了快速跑通可以直接在~/.codex/config.toml写好 API Key 的引用临时把模型名试错很多次。但生产环境不能这样处理。生产环境至少需要做到以下几点API Key 不写入配置文件从环境变量或密钥管理服务读取。日志中不打印完整 Key 和完整请求体避免敏感信息泄漏。对模型调用做 token 用量和失败率统计便于观察成本与稳定性。配置变更前先备份config.toml变更后保留上一版本方便回滚。模型服务商返回支持的模型名列表后把当前使用的版本号明确记录在一个 README 中避免多人协作时各写各的模型名。6.2 发布前检查清单下面这份清单可以直接复制到自己的项目文档中使用检查项完成状态验证命令CLI 已安装且版本正常可选codex --version环境变量已设置必选echo ${#DEEPSEEK_API_KEY}API 连通性已用 curl 验证必选curl 请求后观察状态码config.toml中 model 名正确必选codex exec pingbase_url不含多余接口路径必选观察 404/400 日志Skill 脚本有执行权限必选bash codex skill 脚本SKILL.md 和 AGENTS.md 被读取可选重启 Codex 后询问模型旧配置已备份推荐执行cp ~/.codex/config.toml ~/.codex/config.toml.bak6.3 下一步可以扩展的方向这套接入方式跑通后还可以继续往下做在 Codex 中配置多个 provider让deepseek-v4-pro负责常规任务视觉模型负责识图任务。把识图脚本扩展成批量图片识别支持文件夹扫描和结果汇总。将 Codex 命令集成到 CI 流程中用codex exec自动执行代码审查或文档生成任务。积累每次调用的 token 消耗和耗时找出哪些任务更适合规则脚本哪些任务必须用模型完成。整条链路里最容易让开发者困惑的是模型名校验错误。记住一个原则Codex 只是客户端模型名和 API 格式是否合法由模型提供方决定。先写一步 curl 验证接口再回来看 Codex 的结构化报错问题会清晰很多。识图 Skill 的加入不是为了替代主模型而是给文本模型一条明确的路当主模型看不懂图片时知道该调用哪个工具、请求哪个视觉接口、如何把结果整理给用户。下一步建议你在自己的常用指令中固定 image-describe 的调用约定把脚本从单文件扩展成可配置的多视觉模型工具逐步补齐团队项目的自动化能力。