从零安装 Codex CLI 并接入 DeepSeek 模型本文记录一次完整的从零安装过程不依赖 npm、不需要 Node 环境、国内网络直连可用最终把 Codex CLI 接到 DeepSeek 模型上。文中所有配置与报错都来自真机实测命令可照抄。一、先搞清楚要装的是什么Codex 是 OpenAI 开源的终端编码 AgentCodex CLI。它负责读代码、改文件、跑命令、执行测试底层再调用一个大模型。关键点Codex CLI 和模型是解耦的。CLI 通过 OpenAI 的Responses API协议跟模型通信所以只要某个模型服务实现了这套协议就能接进来——这正是 DeepSeek 能被直接接入的原因。组成部分作用本文方案Codex CLI终端里的编码 AgentGitHub Release 预编译二进制模型服务提供推理能力DeepSeek也可换 OpenAI / OpenRouter配置文件告诉 CLI 用哪个模型、怎么连config.tomlmodels.json环境要求很低不需要 Node.js、不需要 Python一个可执行文件即可。二、安装 Codex CLI2.1 三种安装方式怎么选方式命令适用情况npmnpm i -g openai/codex网络能正常访问 npm 源时最简单Homebrewbrew install codexmacOS 且 brew 源通畅Release 二进制下载解压即用网络受限时的首选本文采用我这次的机器到registry.npmjs.org和国内镜像registry.npmmirror.com都不通npm i -g必然失败所以直接走官方 Release 二进制——效果和 npm 安装完全一样还省掉 Node 依赖。2.2 Windows 安装步骤第 1 步下载打开 Release 页面 https://github.com/openai/codex/releases找到最新版本本文实测为rust-v0.163.0根据你的平台选包平台文件名Windows x64codex-x86_64-pc-windows-msvc.exe.zipWindows ARMcodex-aarch64-pc-windows-msvc.exe.zipmacOS (Apple 芯片)codex-aarch64-apple-darwin.tar.gzLinux x64codex-x86_64-unknown-linux-gnu.tar.gz第 2 步解压建议放到一个固定目录例如D:\CODEX\codex\bin。Windows 自带 tar 不支持 zip用 PowerShell 解压最省事Expand-Archive-PathD:\CODEX\.codex-install\codex-x86_64-pc-windows-msvc.exe.zip-DestinationPathD:\CODEX\codex\bin-Force解压后目录里会有这些文件不要只把主程序单独拷走codex-x86_64-pc-windows-msvc.exe ← 主程序约 325 MB codex-code-mode-host.exe ← 辅助进程 codex-command-runner.exe ← 命令执行器 codex-windows-sandbox-setup.exe ← Windows 沙盒支持 codex-package.json ← 包描述记录入口文件名别删 codex-resources\ ← 运行时资源 codex-path\ ← 附带工具如 rg.exe第 3 步验证cd D:\CODEX\codex\bin.\codex-x86_64-pc-windows-msvc.exe--version# 输出codex-cli 0.163.02.3 下载太慢怎么办从 GitHub 直下可能只有几十 KB/s我这次实测约 45 KB/s159 MB 要下近一小时。可以在下载链接前拼一个公共加速前缀来提速# 原链接https://github.com/openai/codex/releases/download/rust-v0.163.0/codex-x86_64-pc-windows-msvc.exe.zip# 加前缀后实测从 45KB/s 提升到约 4MB/s159MB 用时 38 秒https://ghfast.top/https://github.com/openai/codex/releases/download/rust-v0.163.0/codex-x86_64-pc-windows-msvc.exe.zip加速镜像属于第三方公共服务随时可能变动或失效请自行甄别来源下载后留意与官方 Release 的 SHA256 是否一致。2.4 macOS / Linux# macOSApple 芯片curl-Lhttps://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz|tarxzsudomvcodex-aarch64-apple-darwin /usr/local/bin/codex# Linux x64curl-Lhttps://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-gnu.tar.gz|tarxzsudomvcodex-x86_64-unknown-linux-gnu /usr/local/bin/codex codex--version三、让codex命令随处可用WindowsWindows 上不建议直接裸跑 exe因为还有三件事要处理指定配置目录、按需注入代理、规避一个启动报错。做法是写一个启动器批处理。3.1 加入 PATH# 用户级 PATH不影响系统变量$u[Environment]::GetEnvironmentVariable(Path,User)[Environment]::SetEnvironmentVariable(Path,$u.TrimEnd(;);D:\CODEX\codex,User)改完重开命令行窗口才生效。3.2 启动器D:\CODEX\codex\codex.cmdecho off setlocal enabledelayedexpansion set CODEX_HOMED:\CODEX\.codex set CODEX_BIND:\CODEX\codex\bin\codex-x86_64-pc-windows-msvc.exe set PROXY_CONFD:\CODEX\codex\proxy.conf rem ---- read proxy address: first non-# line of proxy.conf ---- set CODEX_PROXY if exist %PROXY_CONF% ( for /f usebackq tokens* delims; %%A in (findstr /r /v ^# %PROXY_CONF%) do ( if not defined CODEX_PROXY set CODEX_PROXY%%A ) ) if defined CODEX_PROXY ( set HTTP_PROXY%CODEX_PROXY% set HTTPS_PROXY%CODEX_PROXY% set ALL_PROXY%CODEX_PROXY% echo [codex] proxy %CODEX_PROXY% ) if not exist %CODEX_BIN% ( echo [codex] ERROR: binary not found: %CODEX_BIN% exit /b 1 ) rem ---- default to --no-daemon ---- set CODEX_ARGS%* echo %CODEX_ARGS% | findstr /i /c:--no-daemon nul if !errorlevel!0 ( %CODEX_BIN% %* ) else ( %CODEX_BIN% --no-daemon %* ) exit /b !ERRORLEVEL!配套的proxy.conf不需要代理时全部注释掉即可# 填你的代理地址只保留一行全部注释 直连3.3 为什么要默认加--no-daemon不加的话直接敲codex会报Error: the CLI package does not match this platform or executable To work without the background server, rerun the same command with --no-daemon原因是 Codex 启动时会拉起后台 app-server而它顺着 PATH 找到的是我们的.cmd启动器做包校验时对不上。加--no-daemon就走本地模式功能不受影响。如果你是直接跑 exe没用批处理包装则不会遇到这个报错。写批处理的两个坑我踩过文件里写中文注释在 GBK 控制台会被误解析成命令而报错——脚本注释保持英文。for /f eol# ... delims这种写法里空的delims会让eol失效注释行过滤不掉改用findstr /r /v ^#。另外块内判断返回值要用!errorlevel!并开启setlocal enabledelayedexpansion。四、配置文件体系Codex 的配置目录默认是~/.codexWindows 即C:\Users\你\.codex可以用环境变量CODEX_HOME改到任意位置实测有效本文改到了D:\CODEX\.codex。文件作用config.toml主配置用哪个模型、哪个提供方、沙盒权限、审批策略models.json模型目录告诉 CLI 模型的上下文长度、推理档位、工具调用格式auth.json登录态由codex login生成不要外传models.json容易被忽略但很关键。接入非内置模型时如果只改base_url而不提供模型目录会出现上下文长度识别错误、工具调用格式不匹配等问题。五、接入 DeepSeek本文推荐方案5.1 为什么能直接接Codex 只认 Responses API实测 0.163 版本里wire_api只有一个合法值responses。而DeepSeek API 已原生支持 Responses API并专门做了 Codex 适配所以不需要任何中转服务国内网络直连即可。官方文档接入 Codex 指南https://api-docs.deepseek.com/quick_start/agent_integrations/codex/Responses API 说明https://api-docs.deepseek.com/guides/responses_api/5.2 拿一个 API Key打开 https://platform.deepseek.com/api_keys 创建Key 以sk-开头。先单独验证 Key 是否有效不启动 Codex$h {Authorization Bearer sk-你的key}Invoke-RestMethodhttps://api.deepseek.com/v1/models-Headers$h5.3 写模型目录models.json从 DeepSeek 官方配置脚本里可以拿到现成的模型目录脚本地址见文末参考链接放到D:\CODEX\.codex\models.json。它声明了两个模型模型 slug上下文输入模态deepseek-flash1M文本 图片deepseek-v4-pro1M文本推理更强想自己拿完整内容官方一键脚本https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh里的models.json就是这段 JSON也可以直接在 Windows PowerShell 跑https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1让它自动配置它会备份原配置并写入这两个文件。5.4 写主配置config.toml# 沙盒权限只在工作区内可写工作区外只读 sandbox_mode workspace-write # 审批策略写文件或执行命令前先询问 approval_policy on-request # 不把会话响应内容上传服务端留存 disable_response_storage true # ---------- DeepSeek ---------- model deepseek-flash # deepseek-flash / deepseek-v4-pro model_provider deepseek preferred_auth_method apikey # 用 API Key 认证跳过 ChatGPT 账号登录 forced_login_method api model_reasoning_effort high # low / high / max越低越快越省 web_search disabled # DeepSeek 下官方要求禁用内置联网搜索 show_raw_agent_reasoning true # CLI 里按 CtrlT 查看思考过程 model_catalog_json D:/CODEX/.codex/models.json [model_providers.deepseek] name deepseek base_url https://api.deepseek.com/ wire_api responses experimental_bearer_token 把这里整段替换成你的 DeepSeek API Key [desktop] enabled-reasoning-efforts [low, medium, high, xhigh, ultra, max]字段说明字段作用model默认模型对应models.json里的 slugmodel_provider使用哪个提供方对应[model_providers.id]的 idpreferred_auth_method/forced_login_method用 API Key 认证跳过 ChatGPT 登录model_reasoning_effort推理强度越高越慢越贵model_catalog_json模型目录路径Windows 下用绝对路径更稳base_url服务端点wire_api通信协议当前只能是responsesexperimental_bearer_tokenAPI Key官方写法直接写在配置文件里5.5 启动验证新开终端进入项目目录cd D:\你的项目 codex启动横幅显示model: deepseek-flash即配置生效。之后就正常对话使用。换模型改一行即可model deepseek-v4-pro。六、接入 OpenAI 官方如果你有可用的 OpenAI 账号把 DeepSeek 相关字段注释掉恢复默认配置后登录codex login# 浏览器走 ChatGPT 账号授权codex login --device-auth# 设备码方式codex login status# 查看登录状态也可以用 API Keycodex login --with-api-key从 stdin 读入。关于地区限制OpenAI 目前未在中国大陆提供服务。如果网络出口或账号不在其支持范围内会收到明确的拒绝响应{error:{code:unsupported_country_region_territory,message:Country, region, or territory not supported}}这个报错说明网络是通的、卡在地区判定改配置解决不了。如需使用官方服务请使用其支持地区的网络与账号并遵守当地法律法规与 OpenAI 服务条款国内用户建议优先采用第五节这种国内合规服务方案。七、接入其他兼容服务以 OpenRouter 为例任何实现了 Responses API 的网关都能接写法是同一个套路model_provider openrouter model openai/gpt-5.3-codex [model_providers.openrouter] name OpenRouter base_url https://openrouter.ai/api/v1 wire_api responses env_key OPENROUTER_API_KEYKey 通过环境变量注入不要写进配置文件[Environment]::SetEnvironmentVariable(OPENROUTER_API_KEY,sk-or-v1-xxxx,User)env_key与experimental_bearer_token二选一前者从环境变量读更安全后者直接写在文件里DeepSeek 官方用的是这种。第三方网关属于非官方用法你的代码与提示词会经手第三方功能与稳定性也没有官方保证敏感项目请自行评估。八、排错手册以下都是本次实测踩到的坑现象原因解决npm i -g openai/codex失败npm 源不通改用 Release 二进制GitHub 下载 45KB/s国际链路拥塞用公共加速镜像前缀注意甄别来源codex不是内部或外部命令PATH 未生效重开命令行窗口Error: the CLI package does not match...后台 daemon 经.cmd启动器校验失败加--no-daemon启动器已默认加批处理报xxx 不是内部或外部命令.cmd里的中文注释被 GBK 控制台误解析脚本注释用英文unsupported_country_region_territory出口地区/账号不在 OpenAI 支持范围见第六节模型上下文长度或工具调用异常缺models.json补上官方模型目录切换提供方后旧会话消失Codex 按登录方式分组存储会话没丢切回原配置即恢复想升级—codex update想看完整自检—codex doctor九、安全与合规提醒不要把config.toml提交进公开仓库——里面可能含 API Key。密钥优先走环境变量env_key必须落盘时确认文件权限。第三方网关会经手你的代码涉及商业代码请先确认合规与安全边界。使用任何境外 AI 服务请确保网络出口与账号符合当地法律法规和对应服务条款。Codex 的sandbox_mode建议保持workspace-write不要轻易开danger-full-access。十、最终文件清单文件路径主程序D:\CODEX\codex\bin\codex-x86_64-pc-windows-msvc.exe启动器D:\CODEX\codex\codex.cmd已加入用户 PATH代理开关D:\CODEX\codex\proxy.conf主配置D:\CODEX\.codex\config.toml模型目录D:\CODEX\.codex\models.json使用说明D:\CODEX\codex\使用说明.md参考链接内容地址Codex 官方仓库https://github.com/openai/codexCodex Release 下载https://github.com/openai/codex/releasesCodex 官方文档https://developers.openai.com/codexDeepSeek 接入 Codex 官方指南https://api-docs.deepseek.com/quick_start/agent_integrations/codex/DeepSeek Responses API 文档https://api-docs.deepseek.com/guides/responses_api/DeepSeek API Keyshttps://platform.deepseek.com/api_keysDeepSeek API 文档首页https://api-docs.deepseek.com/OpenRouterhttps://openrouter.aiOpenRouter Responses API 文档https://openrouter.ai/docs/api_reference/responses/overviewGitHub 加速镜像第三方https://ghfast.top小结Codex CLI 的安装门槛其实很低——一个二进制、一份配置、一个 Key。真正的门槛在网络和协议网络不通就用 Release 二进制加镜像加速协议认准 Responses API模型则完全可换。国内用户直接接 DeepSeek 是最省事的一条路直连、无需代理、上下文 1M配好models.json就能当内置模型用。
