Codex作为面向开发者的本地AI编程Agent工具，兼具CLI命令行终端、桌面客户端、IDE插件多种形态，能够直接读取本地项目代码，完成代码生成、文件修改、Bug排查、项目重构、单元测试编写等工程任务。原生环境默认绑定官方模型，很多开发者希望替换为DeepSeek V4‑Flash作为底层推理基座，该模型具备优秀代码生成能力、强大工具调用效果，同时拥有不错的响应速度与可控调用成本。
Codex底层使用Responses API协议，而DeepSeek开放接口为标准Chat Completions格式，二者协议存在差异，早期接入需要部署本地代理完成协议转换，配置链路复杂，普通开发者容易出现配置失败。随着官方适配完成，现在提供一键部署脚本，自动完成配置备份、模型元数据写入、参数修改，无需手动搭建代理服务；同时也保留完整手动配置方案，适合需要深度自定义参数的进阶用户。本文完整讲解前置准备、一键脚本完整实操、手动配置文件编写、运行验证、项目实战、高频故障排查，附带可直接复制的命令与配置片段，覆盖Windows、macOS、Linux全操作系统，帮助开发者把DeepSeek V4‑Flash完整接入Codex编程工作流。详情👉访问阿里云百炼大模型服务平台页面 了解。
一、前置环境准备工作
在开始接入操作之前，必须完成环境校验，缺少前置条件会直接导致脚本执行失败，配置目录无法生成。
1、软件版本要求
首先已经完成Codex安装，可以是Codex CLI命令行版本，也可以是Codex桌面客户端。CLI版本最低要求0.144.0及以上，版本过低会出现模型元数据不兼容问题。
查看版本命令：
codex --version
版本较低执行更新命令升级：
codex update
重要前提：必须至少启动运行一次Codex，不管是终端执行codex命令，还是打开桌面客户端。第一次启动会自动生成
.codex配置目录，脚本会读写该目录下面的配置文件，如果目录不存在，脚本执行直接报错无法完成配置。
macOS与Linux系统配置目录路径：~/.codex
Windows系统配置目录路径：%USERPROFILE%\.codex
2、获取DeepSeek API Key
登录开放平台，进入API密钥管理页面，创建新的API Key，密钥以sk‑开头，复制保存。注意密钥不要泄露，禁止直接硬编码写入代码文件，优先使用环境变量方式加载密钥。同时确认账户余额充足，避免调用时报额度不足。
3、系统网络环境
本机需要能够正常访问接口服务；一键脚本会从CDN拉取脚本文件，终端需要允许网络访问，Windows PowerShell需要放开脚本执行权限，部分设备管理员权限不足会出现文件写入失败。
检查配置目录是否正常生成，macOS/Linux执行：
ls ~/.codex
Windows PowerShell执行：
ls $env:USERPROFILE\.codex
能够看到config.toml文件，代表目录生成正常。
阿里云部署AI Agent：OpenClaw/Hermes Agent全网最简单，只需两步，详情👉访问阿里云OpenClaw/Hermes一键部署专题页面了解。
Token Plan Token 最便宜/支持多模型切换：👉访问订阅阿里云百炼Token Plan AI大模型服务 。支持多模型切换，用于多模态模型灵活调用，实现多模型、多工具、多场景下的额度共享与统一管理，兼顾灵活性、稳定性与安全性，大幅降低企业使用大模型的门槛与成本。
二、方案一：官方一键脚本部署（推荐新手使用）
官方一键脚本会自动完成整套流程：备份原有Codex配置文件到backup‑deepseek备份文件夹、生成models.json模型元数据文件、修改config.toml配置项，支持模型切换、恢复原始配置，全程只需要复制执行一行命令，交互式输入选项即可完成全部接入，不需要手动修改任何配置文件。
macOS / Linux终端执行命令
打开终端，复制下面脚本执行：
bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)
Windows PowerShell执行命令
右键以管理员身份打开PowerShell，执行下面命令：
irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex
脚本运行之后会弹出交互式菜单：
请选择要执行的操作：
1. 修改Codex配置，使用deepseek‑v4‑flash模型
2. 修改Codex配置，使用deepseek‑v4‑pro模型
3. 恢复默认的Codex配置（删除deepseek相关配置）
请输入 1 / 2 /3：
输入数字1选择DeepSeek‑V4‑Flash，回车确认。
接下来脚本提示输入API Key：
请输入 DeepSeek API Key（以 sk‑开头）：
粘贴复制好的密钥回车。如果本机已经配置环境变量DEEPSEEK_API_KEY，脚本会自动读取，跳过密钥输入步骤。
脚本自动执行备份、写入模型元数据、更新配置，输出大量OK提示代表执行成功。脚本会把原始config.toml备份到~/.codex/backup‑deepseek/目录，后续需要还原原始配置，可以再次运行脚本输入3一键恢复原始配置，不会丢失原有配置文件。
脚本执行完成之后，必须完全关闭Codex全部进程，桌面客户端彻底退出，终端杀掉codex进程，重新启动Codex，新配置才会加载生效。
脚本执行完成后简单验证
CLI终端执行进入codex交互：
codex
输入简单测试指令：写一段Python快速排序代码，观察模型输出。
查看当前生效模型：
codex config show
输出内容中model字段显示deepseek‑v4‑flash，代表切换成功。
三、方案二：手动配置完整流程（进阶自定义使用）
当网络环境无法访问外部脚本，或者需要深度自定义模型参数、调整推理参数、增加多模态模型配置，就可以使用手动配置方式，手动完成备份、编写models.json、修改config.toml、配置API密钥整套流程，理解每一项配置含义，方便后续调试排错。
步骤1：备份原有配置文件
修改配置前务必备份原有文件，防止配置出错无法回滚。
macOS / Linux：
mkdir -p ~/.codex/backup-manual
cp ~/.codex/config.toml ~/.codex/backup-manual/config.toml.bak
cp ~/.codex/models.json ~/.codex/backup-manual/models.json.bak 2>/dev/null
Windows PowerShell：
New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex\backup-manual" -Force
Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\backup-manual\config.toml.bak"
步骤2：编写models.json模型元数据文件
在.codex目录新建models.json，该文件告诉Codex模型上下文窗口、工具调用能力、输入模态、推理档位等元信息，是接入的核心文件。写入如下JSON内容：
{
"models": [
{
"slug": "deepseek-v4-flash",
"prefer_websockets": false,
"support_verbosity": true,
"default_verbosity": "low",
"apply_patch_tool_type": "freeform",
"web_search_tool_type": "text",
"input_modalities": ["text"],
"supports_image_detail_original": false,
"truncation_policy": {
"type": "rolling",
"max_context_tokens": 128000
}
}
]
}
保存文件，注意JSON格式严格，逗号、引号不能写错，格式错误会直接导致Codex读取模型失败。可以使用下面命令校验JSON语法：
#macOS/Linux校验json
python3 -m json.tool ~/.codex/models.json
步骤3：修改config.toml主配置文件
打开~/.codex/config.toml，修改模型、模型供应商相关配置，指定使用deepseek‑v4‑flash模型。
cli_auth_credentials_store = "file"
model = "deepseek-v4-flash"
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/v1"
wire_api = "responses"
requires_openai_auth = true
保存config.toml文件。
步骤4：配置API密钥
方式A：环境变量（推荐，不会明文存放在配置文件）
macOS/Linux终端临时设置：
export DEEPSEEK_API_KEY="sk-你的密钥"
写入shell配置文件实现永久生效，以zsh为例：
echo 'export DEEPSEEK_API_KEY="sk-你的密钥"' >> ~/.zshrc
source ~/.zshrc
Windows PowerShell临时设置环境变量：
$env:DEEPSEEK_API_KEY="sk-你的密钥"
方式B：写入auth.json认证文件
在.codex目录新建auth.json：
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-你的密钥"
}
步骤5：重启Codex并验证配置
完全退出Codex所有进程，重新打开终端运行codex。
查看当前全部配置：
codex config show
执行简单代码任务测试，验证工具调用是否正常。
手动配置回滚：把backup‑manual目录下面备份的config.toml.bak复制回原文件名，删除models.json，即可恢复原始Codex配置。
四、Codex项目实战测试
配置完成之后，在本地项目目录测试完整编程Agent能力，进入本地代码项目文件夹。
cd ./demo-project
codex
输入任务指令示例：
读取当前项目目录，分析现有Python代码，新增用户登录接口，生成对应的单元测试文件。
正常情况下Codex会调用文件读取工具，读取本地源码，生成代码，直接修改本地项目文件，完成完整工程任务，代表DeepSeek V4‑Flash接入完整生效。
同时可以测试工具调用链路，让模型列出当前目录文件：
列出当前目录下全部源码文件
模型成功调用list_dir工具返回文件列表，代表Function Calling链路正常。
五、常用运维命令汇总
#查看codex版本
codex --version
#查看当前加载配置
codex config show
#查看登录认证状态
codex login status
#重置codex全部配置（谨慎使用，会清空自定义配置）
codex config reset
#一键脚本恢复原始配置（脚本方式部署推荐）
bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup.sh)
#输入数字3执行恢复
六、高频踩坑与故障排查指南
故障1：运行一键脚本提示.codex目录不存在
原因：没有启动过一次Codex，配置文件夹没有生成。
解决：执行一次codex命令，或者打开桌面客户端，进入交互界面之后关闭，再重新运行脚本。
故障2：配置完成之后，启动Codex提示unknown model
原因一：models.json JSON语法错误，逗号、引号写错；
原因二：没有完全退出Codex进程，旧配置仍然驻留内存；
解决：校验models.json JSON语法，彻底关闭Codex全部进程，重新启动。
故障3：调用返回鉴权401错误
原因：API Key复制不全，存在多余空格换行；密钥余额耗尽；环境变量没有正确加载。
解决：重新复制密钥，确认账户余额；环境变量配置之后新开终端窗口测试。
故障4：模型只能回答文本，无法调用本地文件工具
排查config.toml中wire_api = "responses"配置缺失；models.json内工具相关元数据字段丢失。重新核对手动配置文件，或者重新运行一键脚本自动修复配置。
故障5：Windows PowerShell执行脚本报错被阻止
原因：PowerShell默认执行策略阻止远程脚本。
解决：管理员打开PowerShell，临时放开执行策略：
Set‑ExecutionPolicy RemoteSigned -Scope CurrentUser
脚本执行完成之后，可按需恢复策略。
故障6：切换模型之后，桌面客户端看不到模型下拉选项
该现象偶发，不需要纠结界面显示，优先使用CLI命令codex config show确认实际生效模型，直接下发编程任务，功能可以正常运行。
故障7：网络超时请求失败
检查本机网络连通性；确认base_url地址填写正确；如果内网环境，排查代理是否拦截接口请求。
七、两种部署方案选型建议
一键脚本方案适合绝大多数普通开发者，自动备份、自动校验配置，出错可以一键回滚，操作门槛最低，优先选用。
手动配置方案适合：网络无法访问外部CDN脚本；需要自定义模型参数、调整上下文窗口；需要同时维护多个模型配置的进阶用户。手动配置需要仔细校验JSON、toml语法，配置写错会直接导致程序异常。
八、能力边界与使用注意事项
1、DeepSeek‑V4‑Flash具备优秀代码生成、工具调用能力，但是复杂超大型架构设计任务，依旧会存在推理局限，复杂任务可以结合多轮迭代，增加单元测试校验输出结果。
2、API密钥妥善保管，不要提交到代码仓库，优先使用系统环境变量加载密钥。
3、每次修改配置文件之后，必须完全退出Codex进程重新启动，新配置才会加载，热修改不会即时生效。
4、脚本会自动备份原有配置，但是建议重要配置自行额外备份，防止意外丢失。
5、调用产生Token计费，关注账户余额，设置余额告警，避免超额消耗。
总结
Codex接入DeepSeek V4‑Flash，官方一键脚本极大降低了部署门槛，只需要一行命令，即可自动完成备份、元数据写入、配置修改，不用搭建本地协议转换代理；手动配置模式可以满足深度自定义场景，完整掌握配置每一项参数含义。完成接入之后，DeepSeek V4‑Flash强大的代码能力、工具调用能力，就可以赋能Codex本地编程Agent，直接读写本地项目文件，完成代码编写、重构、Bug修复等各类开发任务。
遇到异常优先检查配置目录是否生成、JSON/TOML语法是否正确、密钥是否有效，重启Codex进程是绝大多数配置变更之后必须执行的步骤。开发者可以根据自身网络环境，选择一键脚本或者手动配置，完成本地AI编程工作流升级。
