Codex CLI 接入 DeepSeek API 全流程：Skill、MCP与故障排查

最近技术社区最热的组合，大概是 DeepSeek 和 Codex 这两个词同时出现。很多开发者一边刷到“DeepSeek + Codex 王炸”的帖子，一边上手配置时被一堆报错拦住：模型名到底填什么、base_url 指到哪、为什么总是出现local proxy failed、Skill 该装在哪里、插件又该怎么调用。

这里先给一个明确判断：这套组合的真正价值，不在于某个网传的“神秘正式版”，而在于把 Codex CLI 的开源工程能力、DeepSeek 的开放 API，以及 Skill / MCP 插件机制组合成一条可复用的编程工作流。网络标题里的版本名词只能当话题入口，落地时一定要看官方 API 模型列表。你能不能用起来，取决于能不能把“Codex CLI + OpenAI 兼容 API + 项目指令 + 工具服务器”这条链路完整跑通。

本文会带你从零打通这条链路：安装 Codex CLI、用 DeepSeek API 作为模型后端、配置项目级 Skill、通过 MCP 接入插件，最后给出可复现的验证方法和常见错误排查清单。建议收藏备用，因为现在网上关于这个组合的教程大多是碎片化的，真正能在生产环境落地的细节反而不多。

1. 这篇文章真正要解决的问题

1.1 先别急着找安装包，先通链路

看到“DeepSeek V4 Flash 正式版”这类标题，很多人的第一反应是去搜索引擎找安装包、找下载链接，然后被各种来路不明的压缩包和“网盘资源”耽误时间。

实际上，如果你要用的是 Codex CLI + DeepSeek 这条路线，根本不需要什么特殊安装包。DeepSeek 提供的是 OpenAI 兼容的 HTTP API，Codex CLI 本身就是一个开源命令行工具，两者通过配置就能对接。你需要做的不是“下载一个新版本软件”，而是“把一个已有工具指向一个兼容 API 端点”。

这个认知非常重要。很多教程让人误以为 DeepSeek 和 Codex 的联动需要某个私有客户端，或者需要多模型切换工具才能做到，但真正打开代码编辑器、敲几行配置命令，你就能用上这套组合了。

1.2 这套组合降低的是哪类成本

相比传统 IDE 插件和在线编程助手，DeepSeek + Codex 的组合降低的是三层成本：

第一层是模型选择成本。Codex CLI 不绑定某个模型厂商，通过model_provider配置可以指向任何 OpenAI 兼容接口。今天用 DeepSeek，明天换其他厂商，只需要改配置，不需要换工具链。这种“模型可插拔”的灵活性，对个人开发者和对成本敏感的团队都很香。

第二层是工程集成成本。Codex 能读取项目目录、修改文件、执行命令，还能通过项目级指令文件约束行为。你不再需要把代码复制到网页对话框里，而是让 Agent 在真实工作区里操作，这对日常开发体验的改善是质变。

第三层是扩展成本。通过 Skill 机制可以注入项目规范，通过 MCP 可以调用 GitHub、文件系统等外部工具，这套组合从“问答机器人”变成了“可编排的工程助手”。

1.3 适合谁，不适合谁

坦诚地说，这套配置适合以下读者：

• 已经在用 Codex / Claude Code，但希望切换到 DeepSeek API 控制成本的开发者；
• 想把命令行 AI 助手接入团队项目约定的人；
• 对 Skill 和 MCP 插件机制感兴趣、想自己定制 Agent 能力的工程师；
• 关注“模型替换”和“API 成本”的团队负责人。

不适合的读者也有：完全零基础、希望“双击 exe 就能用 AI 写代码”的用户；或者期待某个“正式版”能一键做到全自动写代码、不需要任何人工审阅的用户。AI 编程工具目前仍然需要人类把关，认清这一点，使用体验会好很多。

2. 基础概念：Codex、Skill、插件、Harness 到底是什么

聊这套组合之前，有必要把几个高频术语拆开。因为很多读者看了几十条帖子，仍然分不清这些词之间的关系，结果配置的时候到处碰壁。

2.1 Codex CLI 是什么

Codex CLI 是 OpenAI 开源的一个命令行编程 Agent。它的核心能力是：读取项目文件、理解用户自然语言指令、生成或修改代码、在终端里执行命令，并在关键操作前请求用户审批。

重点在于，Codex CLI 并不强制使用 OpenAI 的模型。它通过model_provider配置支持接入其他 OpenAI 兼容服务，这就给 DeepSeek 留下了明确的入口。严格来说，这是一个“AI 编程前端”，模型后端是可替换的。

2.2 DeepSeek API 在其中扮演的角色

DeepSeek API 是模型供给方。它的接口与 OpenAI API 基本兼容，所以 Codex 可以通过修改配置把模型指向 DeepSeek 的端点。常见的模型名以官方模型列表为准，大部分时候你会看到deepseek-chat和deepseek-reasoner两类，前者适合日常编码和对话，后者适合需要深度推理的任务。上下文窗口和价格会随官方政策变动，生产环境要定期核对。

2.3 Skill 在 Codex 里的真实形态

很多开发者被“Skill”这个词搞晕，以为它是一个需要单独安装的插件包。在 Codex 语境里，Skill 最轻量、最可靠的实现方式其实是项目级指令文件，也就是AGENTS.md。

你可以把AGENTS.md理解成给 AI 的“入职手册”：里面写好项目语言、测试命令、编码风格、禁止事项。Codex 在项目目录启动时会自动读取这份文件，让它后续所有操作都遵守这些约定。这比每次对话都重复说“请用 pytest 测一下”要高效得多。

社区里还有一种做法是把多个 Skill 整理成.codex/skills/目录，每个子目录放一份SKILL.md和辅助文件，然后在AGENTS.md里按需引用。这种方式的普及度正在上升，但具体是否原生支持，取决于 Codex 版本和社区扩展，使用前建议先查官方文档。

2.4 插件 / MCP 又是什么

插件这个词在 Codex 生态里通常对应 MCP，也就是 Model Context Protocol。它解决一个关键问题：模型不能直接调用外部工具。

通过 MCP，Codex 可以连接 GitHub、文件系统、数据库等“工具服务器”。这等于给 Agent 装上了手脚，让它可以查 issue、读取磁盘、执行测试，而不仅仅是凭空生成代码。配置方式是在~/.codex/mcp.json里声明要启动哪些 MCP server。

2.5 Harness 是什么，为什么大家都在提

Harness 并不是 Codex 官方组件，而是社区对“Codex CLI + DeepSeek API + Skill + 插件 + 启动脚本”这一整套可复用工程模板的称呼。你可以把它理解成一个“预配置好的开发环境包”，把分散的配置和指令文件打包起来，方便团队快速复制。

这种“组合式工具包”本身没有魔法，真正的价值在于配置的复用。理解这一点后，你就不会被各种 harness 名词绕晕了。

3. 环境准备与前置条件

下面是实操部分。我先说明，这篇文章演示的是一套通用配置思路，具体版本号会随工具链更新变化，所以不要盲目照抄某个“最新版本号”，以实际安装时能看到的信息为准。

3.1 运行时依赖

你至少需要准备以下环境：

• Node.js LTS 版本，建议 20 及以上，因为 Codex CLI 通过 npm 分发；
• npm / npx，Node.js 自带；
• Git，Codex 在读取和修改项目文件时经常需要调用；
• 一个 DeepSeek 开放平台的账号和 API Key。

如果你还没有 Node.js，推荐用 nvm 安装，不建议直接 sudo 装全局包，后面权限问题会少很多。

3.2 生成 DeepSeek API Key

到 DeepSeek 开放平台控制台，创建一个 API Key。创建后注意，Key 可能只完整显示一次，一定要先复制保存，再关闭页面。

在开始之前，再确认一下账户里有没有足够余额。虽然是入门示例，但 API 是按 token 计费的，账户余额不足会直接报鉴权或余额错误。

3.3 安装 Codex CLI

执行以下命令全局安装：

npm install -g @openai/codex

安装完成后，验证版本：

codex --version

如果命令输出一个版本号，说明安装成功。如果提示找不到codex，通常是 npm 全局 bin 目录没有加入PATH，可以用npm config get prefix查看路径，然后手动添加。

3.4 一次性检查环境

建议把下面的命令都跑一遍，避免后面排查半天才发现问题：

node -v npm -v git --version codex --version

四条命令都能正常输出版本号，环境就算准备好了。

3.5 安装失败的常见原因

npm 安装失败的原因主要有两个：一是 Node 版本过旧，导致@openai/codex需要的 API 不支持；二是全局安装目录没有写入权限。前者用 nvm 升级 Node，后者检查 npm 的全局目录归属，不要直接使用 sudo，优先考虑修正目录权限。

4. Codex CLI 接入 DeepSeek API 的核心配置

这是整篇文章最关键的一步。配置正确，后面 Skill 和插件才有意义；配置错误，你会被各种报错卡住。

4.1 创建 Codex 配置文件

Codex CLI 的全局配置文件位于~/.codex/config.toml。如果文件不存在，就手动创建~/.codex目录。

mkdir -p ~/.codex

然后编辑~/.codex/config.toml，写入以下内容：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

这里拆开解释几个关键项：

• model：默认使用的模型名，这里填deepseek-chat。如果你需要深度推理型模型，可以后续改成deepseek-reasoner，前提是官方 API 仍然提供这个名字。
• model_provider：指向下方 provider 配置块的名称。
• base_url：DeepSeek API 的根地址。有些版本需要写成https://api.deepseek.com/v1，如果你后续请求 404，可以把这一项改掉再试。
• env_key：Codex 会从环境变量读取 API Key，这里指定读取DEEPSEEK_API_KEY。
• wire_api：最关键的一项。Codex 支持两种 API 协议，responses和chat。DeepSeek 提供的是 OpenAI Chat Completions 兼容接口，所以这里必须写chat。如果你保留默认的responses，很可能出现端点不存在或local proxy failed这类报错。

4.2 设置 API Key 环境变量

在终端里执行：

export DEEPSEEK_API_KEY="sk-你的Key"

为了以后不用每次重启终端都再 export 一次，可以把它写入 shell 配置文件：

# bash 用户 echo 'export DEEPSEEK_API_KEY="sk-你的Key"' >> ~/.bashrc source ~/.bashrc # zsh 用户 echo 'export DEEPSEEK_API_KEY="sk-你的Key"' >> ~/.zshrc source ~/.zshrc

注意：不要把真实 API Key 提交到 Git 仓库，也不要在 CSDN 文章或公开代码里贴出自己的 Key。

4.3 其他可选配置项

如果你的网络环境波动较大，可以在config.toml中增加重试参数：

[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat" stream_max_retries = 5 requests_max_retries = 5

stream_max_retries控制流式响应的重试次数，requests_max_retries控制普通请求的重试次数。这两个值不要设得太高，否则网络故障时反而会长时间卡住。

4.4 验证配置是否生效

启动一个最简单的对话：

codex "请只回答一个问题：你现在连接的模型提供商是谁？"

如果配置成功，Codex 会调用 DeepSeek API，并返回模型自身的说明或类似信息。如果你的 DeepSeek 账号还没有足够余额，这一步就会直接提示鉴权或余额问题。

4.5 为什么 wire_api 这么重要

这是新手最容易踩的坑。Codex 默认使用 OpenAI 的 Responses API 端点，但很多第三方 API 提供商只实现了 Chat Completions 兼容接口。当 Codex 请求/responses路径时，服务端返回 404，就可能被本地的代理工具或网关报成local proxy failed while handling codex endpoint /responses。

解决办法就是设置wire_api = "chat"，让 Codex 走/chat/completions路径。这个配置看起来平平无奇，但它能解决大量“看起来像是网络问题”的报错。

5. 配置 Skill：让 Codex 拥有项目级“技能包”

配置好模型后端之后，Codex 可以正常回答了。但如果你想让它真正符合团队规范，就要用 Skill 机制。下面介绍最稳妥的做法。

5.1 在项目根目录创建 AGENTS.md

Codex 会自动读取项目根目录下的AGENTS.md，这个文件就是最轻量的 Skill。它的作用范围是该项目，不会影响其他目录。

请在你的项目根目录新建AGENTS.md：

# 项目说明 - 语言：Python 3.11 - 包管理：pip + requirements.txt - 测试框架：pytest - 代码检查：ruff # 工作流要求 1. 修改代码后，必须补充或更新对应的测试用例 2. 命令行输出尽量使用中文 3. 不要删除现有测试文件 4. 如果涉及数据库变更，必须提示需要人工确认

保存后，再启动codex，它的行为就会明显偏向遵守这些约定。比如你让它“改一下计算逻辑”，它会更主动地检查测试文件有没有被影响。

5.2 用目录组织多个 Skill

项目变大之后，把所有指令堆在一个AGENTS.md里会很臃肿。社区常用的做法是创建.codex/skills/目录：

my-project/ ├── AGENTS.md ├── .codex/ │ └── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── changelog/ │ └── SKILL.md ├── src/ │ └── main.py └── tests/

然后在AGENTS.md里约定触发方式：

当需要做代码审查时，先读取 .codex/skills/code-review/SKILL.md，按照里面的检查清单执行。

这种方式的好处是每个技能独立成目录，可以单独维护、单独更新，也方便团队评审。

5.3 Skill 设计的实用建议

写 Skill 的时候，真正有效的不是空泛的“请编写高质量代码”，而是具体的工程约束。比如：

• 给出测试命令，让 Agent 修改代码后可以自己执行验证；
• 给出禁止事项，比如“不要直接修改数据库表结构”；
• 给出示例，比如“接口返回格式必须遵循{code, data, message}”。

一份好的 Skill 文件，往往像一份浓缩的团队开发规范。它不需要很长，但必须可执行、可验证。

6. 调用插件：通过 MCP 扩展能力

Skill 让 Codex 知道“该怎么做”，而 MCP 插件让 Codex“能操作什么”。两者的区别可以这样理解：Skill 是规则，插件是工具。

6.1 为什么需要 MCP

没有 MCP 时，Codex 只能基于已有的上下文内容生成代码，无法主动查询 GitHub Issue，无法读取指定目录以外的文件，也无法调用外部 API。这对真实项目来说限制太大。

MCP 解决了这个问题。它让 Codex 可以连接到各种工具服务器，比如文件系统、数据库、GitHub 等。

6.2 在 Codex 中配置 MCP 服务器

Codex 的 MCP 配置文件是~/.codex/mcp.json。示例配置如下：

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] } } }

配置里定义了两个 MCP server：一个是 GitHub，一个是文件系统。注意，具体的包名和参数可能随工具版本变化，请以 MCP 官方文档为准。这里展示的是配置文件的写法。

6.3 运行 Codex 验证插件是否生效

保存配置后，运行：

codex "请列出 /tmp 目录下的前 5 个文件"

如果 filesystem MCP server 正常连接，Codex 会调用对应的工具去读取目录，而不是自己猜测文件名。如果它只是凭空编造文件列表，说明 MCP 没有生效，或者包没有正确安装。

6.4 插件的安全边界

MCP 插件是一把双刃剑。一个能够读取文件系统和创建 GitHub Issue 的 Agent，如果权限过大，可能会执行危险性操作。建议遵循最小权限原则：不要给 Agent 配置生产环境数据库的写权限，不要让它持有生产环境的密钥。对 Codex 输出的命令，也要保留人工审查习惯。

7. 完整运行与效果验证

配置那么多，最终要落到“确实能用”这四个字上。下面给出一个可复现的验证流程。

7.1 最小链路验证

第一步，在项目目录启动 Codex：

codex

第二步，输入一个问题：“你是由哪个 API 提供方驱动的？”正常情况下，它会说明自己连接的是 DeepSeek 模型或其他兼容后端，说明链路已经通了。

第三步，输入一个编程任务：

codex exec "在当前目录创建 main.py，实现一个命令行斐波那契数列计算器，使用 argparse 接收 --count 参数"

预期结果是：Codex 当前目录生成main.py，并给出运行说明。

7.2 运行生成的结果

如果 Codex 成功生成了main.py，可以手动运行验证：

python main.py --count 10

如果输出了一串斐波那契数字，说明生成的代码基本没有语法问题。

7.3 判断 Skill 是否生效

最简单的办法是给AGENTS.md加一条非常显眼的约定，比如“每次输出代码前，先输出一行PROJECT_CONTEXT_LOADED”。然后让 Codex 写代码，观察它是否真的先输出这个标记。如果输出了，说明文件被读取，Skill 生效。

7.4 判断 MCP 插件是否生效

让 Codex 调用一个明确的外部工具，比如读取指定文件路径并打印内容。执行后查看 Codex 的日志输出，看是否出现 MCP 调用记录。如果你发现它完全没调用工具，而是靠猜的，那就要检查~/.codex/mcp.json的包名和路径。

7.5 失败时第一步应该看哪里

不要盲目改配置，先看日志：

ls ~/.codex/log tail -f ~/.codex/log/codex-*.log

也可以使用调试模式启动：

codex --debug

日志里通常可以看到请求发到了哪个 URL、返回了什么状态码、是网络错误还是鉴权错误。这比看终端里简单一句“failed”要有效得多。

8. 常见问题与排查思路

下面整理几个实际使用中高频出现的问题，建议先对照表格定位，再深入排查。

8.1 关于 local proxy failed 的进一步说明

这个报错最近频繁出现，而且报错信息很吓人，看起来像网络彻底断了。实际上，它背后往往只有两个原因：一个是 Codex 请求了/responses端点，但服务端没有实现该端点；另一个是你本机配置了 API 网关、多模型切换工具或调试代理，代理规则没有把/responses或/chat/completions转发到 DeepSeek 官方域名。

排查时不要急着关掉代理工具。先看日志，确认请求 URL 是哪一个路径。如果是/responses，优先改wire_api = "chat"。如果请求路径本来就是对的了，再检查网关的转发规则和认证头。

8.2 关于模型版本和价格变动

网络标题里出现的“V4 Flash 正式版”等说法，不一定等于 API 控制台里实际可用的模型名。搜索热词不能当版本依据，要不断核对 DeepSeek 官方模型列表。另外，API 价格可能会调整，生产环境建议记录每次请求的 token 用量，并设置费用告警，避免月底账单超出预期。

9. 最佳实践与工程建议

最后这部分写给真正想把 DeepSeek + Codex 组合用进日常开发的人。配置跑通只是开始，用得稳、用得久才是目的。

9.1 API Key 的管理

务必遵循最小权限和机密管理原则。API Key 使用环境变量或专门密钥管理服务，禁止写进项目仓库。.gitignore要忽略.env文件。

9.2 把 Skill 纳入版本管理

AGENTS.md和.codex/skills/目录应该提交到 Git 仓库。这样团队所有人都执行同一套规范，Agent 的行为是可预期的。Skill 的变更也要走代码评审流程。

9.3 不要默认关闭审批机制

Codex 自带命令执行审批和沙箱机制。在个人测试环境可以放开，但在生产环境或者涉及数据库、删除文件、修改权限的操作中，一定要保留人工审批。很多安全事故不是因为 AI 写错代码，而是因为人类把护栏拆得太彻底。

9.4 成本控制与限流

DeepSeek API 按 token 计费，价格可能调整。每次请求都消耗 token，尤其是把大量文件塞进上下文时，成本增长会很快。建议合理控制上下文长度，避免把整个仓库一次性喂给 Agent。可以在日志里记录 token 用量，按天统计。

9.5 保持可回滚

如果你想切换模型配置，先把现有配置备份好。比如这样：

cp ~/.codex/config.toml ~/.codex/config.toml.bak

然后小范围测试，确认没问题后再全量切换。不要在生产环境直接改配置，更不要一次性把团队所有人的模型后端都切到一个未经验证的新模型上。

9.6 不盲从社区热词

“DeepSeek harness”“王炸组合”这类热词听起来很提气，但真正决定生产力的，永远是你是否理解了配置背后的原理。能分清楚 Codex CLI 负责什么、DeepSeek API 负责什么、Skill 规则藏在哪、MCP 工具卡在哪，再热门的工具组合也不会让你手足无措。

下一步建议你亲手做一个小项目：配置好 DeepSeek API，写一份属于自己团队风格的AGENTS.md，再接一个文件系统 MCP server，跑通一个真实任务。流程走完一遍之后，你自然就知道这套组合的价值边界在哪里了。