DeepSeek-V4-Pro 接入 Codex CLI：配置、排错与识图 Skill 指南

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，却把 API Key 和模型名写进了~/.claude/settings.json，Codex 启动后读取不到配置，启动后仍会使用默认模型。反过来，如果你把 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，再把这个目录加入 PATH：

export PATH="$(npm prefix -g)/bin:$PATH"

macOS 用户也可以使用 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 关键参数说明

配置看似简单，但任何一个字段填错，都会出现难以定位的报错。下面把常用参数列成速查表。

很多 400 错误并不是 Key 不对，而是base_url少了/v1。如果接口地址是https://api.example.com/v1/chat/completions，base_url就应该写https://api.example.com/v1，不要把完整的chat/completions也写进去。

3.3 设置 API Key 环境变量

不要直接把 API Key 明文写进config.toml。正确方式是通过环境变量：

export DEEPSEEK_API_KEY="sk-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 为什么需要 Skill

DeepSeek-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.sh

SKILL.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 模型名与配置文件类报错

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 相关报错

排查顺序上，建议先查“输入是否正确”：图片路径、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 发布前检查清单

下面这份清单可以直接复制到自己的项目文档中使用：

6.3 下一步可以扩展的方向

这套接入方式跑通后，还可以继续往下做：

• 在 Codex 中配置多个 provider，让deepseek-v4-pro负责常规任务，视觉模型负责识图任务。
• 把识图脚本扩展成批量图片识别，支持文件夹扫描和结果汇总。
• 将 Codex 命令集成到 CI 流程中，用codex exec自动执行代码审查或文档生成任务。
• 积累每次调用的 token 消耗和耗时，找出哪些任务更适合规则脚本，哪些任务必须用模型完成。

整条链路里，最容易让开发者困惑的是模型名校验错误。记住一个原则：Codex 只是客户端，模型名和 API 格式是否合法由模型提供方决定。先写一步 curl 验证接口，再回来看 Codex 的结构化报错，问题会清晰很多。识图 Skill 的加入不是为了替代主模型，而是给文本模型一条明确的路：当主模型看不懂图片时，知道该调用哪个工具、请求哪个视觉接口、如何把结果整理给用户。下一步建议你在自己的常用指令中固定 image-describe 的调用约定，把脚本从单文件扩展成可配置的多视觉模型工具，逐步补齐团队项目的自动化能力。