如果你最近逛技术社区很可能已经被 Codex 这个词反复刷屏了。Codex 是 OpenAI 推出的 AI 编程助手但它不只是某个编辑器里的插件而是一个可以跑在自己电脑上的本地部署方案。简单来说你可以把 Codex 下载到本机环境配好模型和服务地址让它直接在命令行里帮你写代码、改文件、跑测试甚至完成一整套项目初始化。真正实用的是它不强制绑定 OpenAI 官方服务通过配置可以接到 DeepSeek、Ollama 这类第三方模型服务上。这篇内容我把从零开始下载、安装、配置、使用的完整过程写下来面向被各种教程搞得一头雾水的新手也适合想接入第三方模型的老手。整个过程中我踩过的坑、哪些配置是必填的、哪些网上流传的说法是错的都会在后面的章节里拆开讲清楚。1. 项目整体设计与部署思路1.1 Codex 到底是什么和普通 AI 插件有什么不同很多人一听到 AI 编程第一反应是 GitHub Copilot 或者 Cursor 这种编辑器侧边栏对话工具。Codex 的思路不太一样它更接近一个长在终端里的 AI 工程师你给它一句话它不只会生成片段还会真的读取项目文件、创建文件、修改已有代码、执行命令甚至跑测试确认改完没改坏。Codex 有两个形态一是命令行工具 Codex CLI通过 npm 安装后直接在终端使用二是桌面版应用适合不太习惯命令行的用户。我全程用的是 CLI原因很简单CLI 的配置路径、模型切换逻辑更透明出问题时能直接看到日志桌面版更像是给日常轻度用户准备的。它和 Copilot 的核心区别在于交互方式。Copilot 偏补全你在写代码时它帮你续写基本不主动改文件。Codex 偏执行任务你把描述扔给它它自己规划步骤、修改文件、执行命令然后给你汇报结果。这就意味着它的定位不是键盘辅助而是一个真正能接手小型开发任务的自动化工具。1.2 本地部署的核心收益与适用场景这里说的本地部署并不等于模型跑在本地而是指客户端工具跑在你自己的电脑上模型请求可以指向你自己的服务地址。这样做有三个实际好处。第一是数据可控。代码内容发给谁取决于你配置给哪个模型服务。如果你的团队有内网的大模型服务或者你本机跑了 Ollama那么代码完全不用出本机。对一些有保密要求的项目这一点比在线商业插件重要得多。第二是模型可替换。官方服务贵、限流、模型选择受限这是很多人转向第三方模型的核心原因。Codex 通过 model_provider 配置机制支持 OpenAI 兼容协议DeepSeek、Kimi、通义、Ollama 这类服务都能接进去选择的自由度一下就打开了。第三是团队工具链统一。你把配置文件和安装命令固化下来团队新成员跑一遍脚本就能获得同款环境避免了在我电脑上能跑这种经典尴尬。1.3 部署方案的选型逻辑我建议优先选择 npm 方式安装 CLI而不是桌面版。原因很简单命令行工具能写进自动化脚本也方便多版本管理。桌面版虽然安装容易但它的可配置深度和日志可见性都比 CLI 差一截。后面所有操作都以openai/codex这个 npm 包为准。至于模型服务端本地部署可以分两级如果你只是想省钱、想换模型那就接 DeepSeek 这类在线兼容 API如果你想数据完全不出本机那就在本机装 Ollama再拉一个代码能力强的模型比如 Qwen2.5-Coder 系列。两级方案我会在后面的实操章节分别给出可复现的配置。2. 环境准备与 Codex 下载安装2.1 安装前的环境清单先确认基础环境再动手装省得到时候排查起来怀疑人生。操作系统Windows 10/11、macOS 12、主流 Linux 发行版都行。Node.js建议 18 以上最好 20。Codex CLI 是 Node 工具链Node 版本太低会直接报错。npm随 Node 一起装建议 9 以上。Git不是安装 Codex 的硬性条件但后续用它操作代码仓库时基本都需要。检查命令如下node -v npm -v git --version如果 Node 没装去官网下载 LTS 版本安装时默认把 npm 一起带上。Windows 用户注意安装后要新开一个终端窗口不然 PATH 环境变量不刷新node命令会提示找不到。2.2 通过 npm 安装 Codex CLI环境没问题之后安装只需要一条命令npm install -g openai/codex安装完成后检查版本codex --version如果能看到版本号说明安装成功。如果提示codex: command not found大概率是 npm 全局安装目录没有写入系统 PATH。Windows 下先执行npm config get prefix查看全局目录把这个目录加到 PATH 里macOS/Linux 下常见于使用 nvm 时权限或路径配置问题检查~/.nvm的相关配置即可。npm 下载速度慢的话可以把 registry 切换到国内镜像这不会影响 Codex 本身的功能npm config set registry https://registry.npmmirror.com切换镜像后重新安装一次速度会提升很多。2.3 可选方案桌面版的下载安装桌面版在官网下载对应平台的安装包安装后首次启动会引导登录。桌面版的好处是操作直观适合不想碰命令行的人。但它和 CLI 的配置文件是通用的也就是说你在 CLI 里配置好的模型指向桌面版也能识别。我个人的建议是两条腿走路日常用桌面版可以但出问题时回到 CLI 配合codex --debug看日志定位问题效率高得多。2.4 登录与组织设置安装完先登录。执行codex login它会打开浏览器完成授权支持 ChatGPT 账号登录模式和 API Key 模式。如果你只是个人使用ChatGPT 登录就行。但如果你的账号属于某个组织登录后 Codex 会尝试加载组织设置这一步网络或权限有问题时会卡住这个问题后面单独讲。这里有一个关键点如果是用第三方模型服务比如 DeepSeek 或 Ollama其实不一定需要走官方登录。你可以直接配置 API Key 到环境变量跳过完整的 ChatGPT 登录流程。我建议新手先按官方默认方式登录一次确认基本链路通了再切换模型这样排查问题时有明确对照。3. config.toml 核心配置与第三方模型接入3.1 配置文件位置与基本结构Codex 的配置集中在~/.codex/config.toml。Windows 下路径是C:\Users\你的用户名\.codex\config.tomlmacOS/Linux 下是~/.codex/config.toml。这个文件的本质是一个 TOML 格式的文本Codex 每次启动都会读取它。也就是说改完配置后不需要重新编译任何东西重启codex命令就生效。最基本的两项配置model gpt-5.6-sol model_provider openai这里model是实际要用的模型名model_provider是服务提供方的标识符。默认情况下Codex 指向 OpenAI 官方服务。当你想要接入第三方时重点是新增一个[model_providers.xxx]配置块。3.2 把 Codex 接到 DeepSeek 的完整配置用 DeepSeek 作为例子配置文件这样写model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY注意env_key表示 API Key 从环境变量读取而不是直接写在配置文件里。这种做法强烈推荐因为config.toml经常会被复制、上传到仓库Key 明文写在里面等于直接泄露。设置环境变量# macOS / Linux export DEEPSEEK_API_KEYsk-你的key # Windows PowerShell $env:DEEPSEEK_API_KEYsk-你的key然后启动codex它发起请求时会用这个 Key 访问 DeepSeek 的接口。DeepSeek 的接口兼容 OpenAI 协议所以 Codex 不需要额外适配这是它能被接入的根本原因。3.3 完全本地部署结合 Ollama 跑模型如果你需要数据不出本机那就在本机装 Ollama。装好后拉一个代码能力强的模型以 Qwen2.5-Coder 为例ollama pull qwen2.5-coder:14b然后给 Codex 添加 Ollama 作为 providermodel qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1Ollama 的本地接口兼容 OpenAI 协议而且默认不需要 API Key所以不需要配api_key或env_key。配置好之后所有请求都发往本机 11434 端口代码片段不会出本机。我实测下来14B 的模型在代码补全和简单逻辑修改上是可用的但复杂项目重构和长上下文任务还是吃力这属于模型能力边界问题不是 Codex 的配置问题。3.4 实用配置项与参数调优除了模型指向几个配置项会直接影响使用体验。sandbox_enabled决定是否开启沙箱模式。沙箱模式下Codex 执行命令前会向你确认避免它自己乱跑危险命令。我建议新手保持开启等熟悉了它的操作风格再决定是否关闭。temperature控制生成内容的随机性调低一点更稳定写代码我习惯设置在 0.2 左右temperature 0.2approval_policy可以设置命令审批策略比如只对写操作或特定目录外的命令进行确认。这个配置项需要仔细读文档不要一次性放得太开否则 Codex 可能在你不知情的情况下改动大量文件。4. 实操过程用 Codex 完成真实任务4.1 场景一从零初始化一个 Python 项目我新建了一个空目录然后执行cd ~/test-codex codex 初始化一个 Python 项目包含 requirements.txt、README.md以及一个可以计算斐波那契数列的模块Codex 会先输出一个执行计划告诉你它准备创建哪些文件、每个文件大致内容。确认后它会逐个创建文件。整个过程中我留意到两个细节一个是怎么让输出可靠。我给的指令里明确了输出物清单它就不会自由发挥多塞一些没用的文件。另一个是当它创建完文件后会问你是否要执行验证命令。这时候说 是 它就会跑python -m pytest之类验证动作当场确认项目能不能跑起来。这是 Codex 区别于其他 AI 补全工具的关键能力把它利用好交付质量会高很多。4.2 场景二让 Codex 修改已有代码并验证我在一个已有一组单元测试的 Python 项目里执行codex 修复 tests/test_api.py 中失败的用例注意不要修改接口签名注意我特意加了不要修改接口签名这个约束。没有约束时AI 为了通过测试往往会顺手改动被测试的代码逻辑最后虽然测试绿了功能却变了。加上约束后它会更倾向只修测试文件本身的问题。Codex 先读取了相关测试文件定位到失败的断言然后提出修改方案。我批准后它改了测试文件并运行测试确认。这次经验说明prompt 里把允许做什么、禁止做什么写清楚比单纯说修复 bug结果稳定得多。4.3 场景三完整跑一遍 Ollama 本地模型链路在这个场景里我不使用任何在线服务全程本地。配置好 Ollama provider 之后执行codex 用 Python 写一个脚本读取当前目录的 access.log统计每个 IP 的出现次数并排序Codex 读取了目录结构创建脚本然后尝试运行。因为是本地模型响应速度取决于你机器的 GPU 或 CPU 性能。我在一台 M 系列芯片的 Mac 上跑 14B 模型整体可用但不快复杂任务的推理时间会明显拉长。这个场景验证了一个重要结论Codex 并不挑模型只要服务地址兼容 OpenAI 协议本机模型一样能跑通。所以本地部署 AI 编程助手的关键不是 Codex 本身而是你选的模型够不够强。5. 常见问题与排查技巧实录5.1 登录不上和组织设置加载失败codex login时浏览器打不开或者登录后提示无法加载组织设置这类问题我遇到过多次。先确认网络能不能正常访问官方认证接口。如果访问不通那就别硬刚官方登录切换 API Key 模式更省事跳过codex login在环境变量里配置好对应服务的 KeyCodex 就会直接采用配置的 provider 发起请求。组织设置加载失败常见于账号权限配置有问题。可以检查账号是否被正确添加到组织或者组织是否有 Codex 使用的模型权限。如果只是个人使用可以在配置里不引用组织相关内容绕过这一层。5.2 提示 unrecognized configuration settingCodex 启动时报ignoring 1 unrecognized configuration setting意思是配置文件里有个它不认识的项。这类问题绝大多数是因为配置项拼写错误或者该配置项在当前版本中已被改名/弃用。排查方法很简单先删除可疑配置项看报错是否消失再逐项加回来确认。也可以执行codex --version对比最新版本如果是版本差异升级后往往就好了。我在网上看到很多教程写的配置项和最新版不一致照抄后基本都会触发这个警告。所以遇到这个提示先怀疑版本差异不要怀疑是自己手滑。5.3 模型不支持的错误启动时若报the gpt-5.6-sol model is not supported when using codex with a ...说明你配置的模型名和实际使用的 provider 不匹配。例如默认配置写的是 OpenAI 的模型名但你同时把model_provider指向了第三方服务而第三方服务根本不提供叫这个名字的模型。解决思路是确认模型名在目标 provider 中真实存在。我一般先在服务商官网查模型列表再填进配置而不是随便猜一个名字。5.4 endpoint 连接失败与响应中断使用第三方 provider 时最常见的报错是请求发不出去或者请求到一半中断类似handling codex endpoint /responses时连接失败。这类问题我从三个方向排查第一base_url是否正确。很多服务的 OpenAI 兼容地址带有/v1后缀漏掉之后请求会 404。第二服务是否真的启动。Ollama 这类本地服务如果没启动连接会被直接拒绝先手动访问http://localhost:11434确认可用。第三Key 或环境变量是否生效。改了环境变量之后要新开终端窗口Codex 才会读到新的值。这几个原因里我踩得最多的是 base_url 的后缀问题建议照着官方文档逐字符核对。5.5 Windows 下提示设置未完成Windows 上安装后可能提示设置未完成。我遇到过的原因有几种Node 和 npm 版本太旧、未重新打开终端导致 PATH 未刷新、权限不足导致全局安装没有真正写入系统目录。处理方法先重新打开一个新的终端再执行codex --version。如果仍然报错用管理员权限重新安装一次 npm 包。还不行的话检查 Windows 的 PATH 环境变量中是否包含 npm 全局目录。这套组合基本能覆盖绝大多数 Windows 安装问题。6. 多项目管理与安全实践6.1 用 profile 管理多套环境实际工作中我不会只有一个模型服务。测试环境用 DeepSeek生产环境用内部的模型服务还有个人电脑上跑 Ollama。如果每次都改config.toml太容易出错。Codex 支持 profile 机制可以按项目或用途拆分配置codex --profile work codex --profile local对应的配置写在config.toml的[profiles.xxx]区块。我一般把公司项目应该用的模型、审批策略放在 work profile 里把个人实验用的本地模型放在 local profile 里。启动时明确指定 profile可以避免拿错环境导致事故。6.2 环境变量管理与 Key 安全API Key 严格通过环境变量注入。不要因为图省事直接写进config.toml这个文件太容易被分享出去。我在配置中还建议给config.toml设置只读权限防止其他进程篡改。如果是在团队内共享配置模板把 Key 位留空让每个人在本地填自己的环境变量。这属于最基本的密钥卫生但我在不少团队里看到过把 Key 提交到仓库的严重事故。6.3 沙箱与审批策略的把握Codex 默认会建议开启沙箱这个别关。尤其是处理不熟悉的开源仓库时AI 可能出于修复问题的目的执行一些你没预料的命令比如清理目录、改全局配置。打开沙箱和审批策略每个关键动作过一道确认能兜住绝大多数风险。等你对 Codex 的行为模式足够了解、并且只在自己完全掌控的仓库里使用时再考虑放宽审批。我的原则是宁可每次多点一下确认也不要为省这几秒付出清空文件的代价。最后分享一个我自己用了很久才总结出来的经验Codex 这类工具不是装完就能发挥全部价值它的使用习惯和 prompt 约束能力才是关键。一开始不要碰大型代码库拿小项目练手看着它每一步在做什么理解它的规划模式之后再一点点放权。记住一个判断标准如果一次任务描述里你没写不要修改什么那就要做好它真的乱改的准备。把限制写在前面Codex 才能从一个会写代码的玩具变成一个稍微靠谱的编程搭子。