1. 项目概述与部署思路拆解1.1 为什么要把 Codex 部署在本地如果你最近关注 AI 编程助手一定听说了 Codex 这个名字。它是 OpenAI 推出的智能编程代理核心能力是读取你的代码仓库、理解任务目标然后自动完成多文件修改、命令执行、测试运行等一系列操作。简单说它不只是补全代码的插件更像一个能真正动手干活的编程搭档。我最早是在云端环境里体验 Codex 的确实很强但用了一段时间后几个实际痛点越来越明显代码属于敏感资产我不想把所有仓库都推给远端网络请求的延迟和波动会影响交互流畅度还有就是自定义模型接入的需求——团队里已经在用 DeepSeek、Ollama 跑本地大模型如果能把这些模型接到 Codex 上既能省下 API 费用又能把数据留在内网。这让我下定决心研究怎么把 Codex 完整地在本地部署起来。这篇博文要做的就是把我从零开始部署 Codex 的完整过程记录下来包括环境怎么配、CLI 怎么装、API 怎么接、踩过的坑怎么填。无论你是想用 Codex 日常写代码还是想把它接到本地模型上这篇文章都能给你一条可以直接照着走的路。1.2 本地部署的核心架构与工作流程动手之前先把整体架构理清楚。Codex 本地部署后的工作流程大致是这样的你在终端里输入任务描述Codex CLI 接收指令后会把任务拆解成具体操作步骤通过配置好的模型接口可以是 OpenAI 官方 API也可以是本地模型的 API 服务调用大模型来生成决策和代码然后在你指定的工作目录里执行文件修改、运行命令等操作。这里的核心组件有三个Codex CLI 本体、后端模型服务、以及配置层。Codex CLI 负责交互和任务执行后端模型服务负责提供智能决策能力配置层则负责把两者连接起来。这中间最关键的就是配置层——你要让 Codex 知道我去哪里调模型用什么鉴权方式默认在工作目录下执行什么权限级别的操作。我见过不少朋友部署失败都是因为只盯着 CLI 的安装忽略了模型接口配置。实际上Codex 本身的安装并不复杂真正的分水岭就在 API 集成这一步。所以后面我会花大篇幅讲 API 的配置细节。2. 环境准备与基础依赖安装2.1 Node.js 环境的版本选择与安装Codex CLI 是构建在 Node.js 之上的所以第一步就是把 Node.js 环境准备好。这里我给一个明确的版本建议Node.js 18 LTS 或 20 LTS 都可以20 LTS 我更推荐因为它在稳定性和对现代 JavaScript 特性的支持上都更均衡。安装方式有两种。如果你在自己电脑上直接去 Node.js 官网下载对应操作系统的安装包即可如果你在服务器上部署我推荐用 nvmNode Version Manager来管理版本好处是后续切换版本、回滚都很方便。以 Linux 为例安装命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node -v安装完成后务必确认 node 和 npm 都能正常输出版本号。我在 Windows 上遇到过一种情况node 装完了但 npm 的全局路径没有加到 PATH 里导致后面安装 Codex 提示command not found。如果你也遇到类似问题可以手动把%APPDATA%\npm添加到系统环境变量。关于 Node.js 版本我想多说一句。有朋友为了追求新特性装了 Node.js 22 或更高版本结果某些依赖包编译时报错。在部署 Codex 这种工具链时我倾向于选择成熟的 LTS 版本少折腾稳定优先。2.2 Codex CLI 的安装与权限配置Node.js 就绪后安装 Codex CLI 本身非常简单一行命令npm install -g openai/codex安装完成后执行codex --version验证是否成功。如果提示找不到命令多半是 npm 全局 bin 目录未加入 PATH解决思路和上面 Node.js 的一样。这里有一个关键点Codex CLI 在首次使用时需要登录认证。执行codex login后它会引导你完成 ChatGPT 账号的授权流程。如果你的网络环境需要代理才能访问相关服务这一步可能会报代理错误我在后面的问题排查章节里专门讲这个问题。权限配置方面Codex CLI 提供了三种操作权限级别ReadOnly只读、WorkspaceWrite工作区写入、FullAccess完全访问。我的建议是日常开发用WorkspaceWrite就够了这样 Codex 可以在你指定的工作目录内创建和修改文件但不会去动工作目录之外的系统文件。只有在你明确信任 Codex 能处理全盘任务时才考虑FullAccess。在配置文件中设置示例{ permissions: WorkspaceWrite, model: gpt-5.6-sol }说到model参数我特别提醒一句如果你用的是 Codex 新版的某些模型别名需要确认该模型在当前环境中是否可用。后面排查章节我会讲到model is not supported 这个报错很多人都遇到过原因就在配置里的模型名与后端服务支持列表不匹配。3. API 集成与模型接入实战3.1 清晰理解 Codex 的 API 配置机制Codex 本身并不是一个独立的大模型它必须有模型服务在背后支撑。默认情况下Codex 配置为使用 OpenAI 的模型服务但真正有价值的是它支持自定义模型端点。这意味着你可以把 Codex 的推理能力切换到任意兼容 OpenAI API 协议的服务上包括 DeepSeek、Ollama 本地模型等。在 Codex 的配置体系中你需要关注这些字段{ model: your-model-name, model_provider: openai, base_url: https://api.example.com/v1, api_key: your-api-key }model告诉 Codex 用哪个模型名称发起请求model_provider指定 provider 类型常见的有openai、ollama、custom等base_url模型服务的基础地址Codex 会在此基础上拼接/responses端点发起推理请求api_key模型服务的认证密钥我实测下来的体会是大部分接入失败的问题都出在base_url和模型名对齐上。你要确保 Codex 发出的请求路径和你的模型服务实际监听的路径一致。3.2 一步步完成 DeepSeek 接入先看一个完整的 DeepSeek 接入示例这是目前社区里用得最多的方案因为 DeepSeek 在代码生成能力上表现非常抢眼性价比也高。第一步拿到 DeepSeek 的 API Key。登录 DeepSeek 开放平台创建 API Key这个 Key 要妥善保存因为它只会显示一次。第二步在 Codex 的配置文件一般在~/.codex/config.toml里做如下配置model deepseek-chat model_provider openai [model_providers.openai] name deepseek base_url https://api.deepseek.com/v1 api_key your-deepseek-api-key注意这里我用的model_provider值还是openai但base_url已经指向了 DeepSeek 的地址。这是因为 DeepSeek 的 API 接口兼容 OpenAI 协议Codex 只需要知道往哪里发请求、用什么格式发请求而不关心后面到底是什么模型在回答。第三步启动 Codex 测试codex 请帮我写一个快速排序算法如果一切正常Codex 会调用 DeepSeek 生成回答。这里有个细节DeepSeek 返回的格式与 OpenAI 原生的响应格式在某些字段上会有细微差异但 Codex 的兼容层做得不错大部分情况下可以无缝对接。3.3 使用 Ollama 接入本地模型如果你不想依赖任何云端 API想让 Codex 完全跑在本地Ollama 是目前最成熟的方案之一。Ollama 是一个本地大模型运行工具你可以把它理解成一个模型服务容器在本地运行 Llama、Qwen、DeepSeek 等开源模型并对外提供 API 接口。先安装 Ollama然后拉取一个代码能力强的模型比如ollama pull deepseek-coder:6.7b ollama serveollama serve启动后Ollama 默认会在http://localhost:11434监听 API 请求。接下来配置 Codexmodel deepseek-coder:6.7b model_provider ollama [model_providers.ollama] name ollama base_url http://localhost:11434/v1 api_key ollama这里有个容易踩的坑Ollama 的 API 路径有两种。原生路径是http://localhost:11434/api/chat而 Codex 期望的是 OpenAI 兼容路径http://localhost:11434/v1/chat/completions所以你在配置里必须写/v1那个地址。另一个需要注意的选择是模型本身的参数量。如果你电脑没有独立显卡或者显存不足 8GB拉 7B 参数的模型基本够用但要接受它的推理速度会明显偏慢。我在一台 32GB 内存、只有核显的笔记本上测试7B 模型跑简单代码任务还能接受复杂任务就要等一会儿了。如果你有 24GB 显存的显卡可以考虑 13B 或更大的模型生成质量会有明显提升。4. 实操过程与关键环节记录4.1 从零开始的一次完整部署实录为了让这篇博文更有参考价值我把一次实际的部署过程完整记录下来包括每一阶段的命令和输出。我先准备了一个测试项目目录/home/user/codex-demo并在里面放了一个简单的 Python 文件用于测试。然后按步骤操作# 1. 检查 Node.js 版本 node -v # 输出 v20.11.1 # 2. 全局安装 Codex CLI npm install -g openai/codex # 3. 验证安装 codex --version # 输出 0.x.x # 4. 在配置目录创建配置文件 mkdir -p ~/.codex vim ~/.codex/config.toml配置文件写入的内容我选择了接入本地 Ollamamodel qwen2.5-coder:7b model_provider ollama [model_providers.ollama] name ollama base_url http://localhost:11434/v1 api_key ollama [permissions] default_mode workspace-write这里有一个细节值得展开。default_mode设置为workspace-write后Codex 默认只允许修改当前工作目录内的文件。我在测试时故意让 Codex 去修改工作目录之外的一个文件它直接拒绝了并在终端里提示需要提升权限。这个安全机制让我比较放心日常写代码完全够用。配置完成后我在项目目录里执行cd /home/user/codex-demo codex 给这个目录下的 hello.py 添加一个功能从环境变量读取用户名如果没设置就用默认值Codex 先读取了hello.py的内容然后调用本地模型分析任务几秒钟后返回了修改方案并询问是否执行。我确认后它完成了文件修改。整个过程体验下来和云端版本在交互逻辑上几乎一致区别只在于响应速度受限于本机 GPU 算力。4.2 关键参数调试与性能优化记录在实际使用中有几个参数值得你反复调试它们直接影响 Codex 的工作质量。第一个是temperature参数它控制模型输出的随机性。代码生成任务我建议设置得低一些比如0.2这样生成结果更确定、更稳定。如果你发现 Codex 给的代码风格比较飘先检查这个值。第二个是上下文长度。Codex 会把仓库里的相关文件内容都发送给模型所以上下文窗口越大它能看见的代码就越多。像qwen2.5-coder:7b支持 32K 上下文比起早期的 4K 模型在处理大文件时优势明显。但要注意上下文越大占用的显存也越多推理速度也会下降。建议根据你的显存容量选择合适的上下文长度。第三个是请求超时时间。本地模型推理速度慢如果 Codex 的请求超时时间太短就会频繁报错。我在配置里加了[api] timeout_ms 300000把超时时间拉长到 5 分钟有效避免了长任务中断的问题。如果你用的是云端 API这个值可以设小一些因为云端响应速度快设太长反而会拖慢错误反馈。4.3 沙箱模式与安全边界的重要性Codex 有一个非常重要的特性就是沙箱模式。它会为每次任务创建一个隔离的执行环境在这个环境里Codex 运行命令、修改文件但不会直接影响你的真实系统。初次使用 Codex 时我建议选择沙箱模式尤其是在不熟悉它的行为习惯之前。沙箱模式的好处在于即使 Codex 生成了有问题的命令也不会对你的系统造成实质性影响。等你觉得足够有信心了再切换到工作区写入模式也不迟。我个人的体验是沙箱模式 工作区写入权限的组合是目前最均衡的方案既能让 Codex 实际操作代码文件又限制了系统级风险。等到你真正理解 Codex 的每个操作逻辑再考虑完全访问权限。5. 常见问题与排查技巧实录5.1 让人头疼的代理错误这样解决最省心很多人在codex login或者首次发起请求时会遇到类似这样的报错Cc switch local proxy failed while handling codex endpoint /responses. Provide a valid ...这个问题的本质是 Codex 尝试通过本地代理访问模型服务但代理配置不正确或代理本身没有正常工作。我最初遇到时也懵了还以为是 Codex 本身的 bug后来排查发现是系统环境变量里设置了HTTPS_PROXY或HTTP_PROXYCodex 会读取这些变量作为代理而我的代理服务当时没启动。解决办法分几步检查环境变量。执行env | grep -i proxy看看有没有设置代理变量。如果你确实需要代理访问外网 API确认代理服务地址和端口号正确。如果你用的是本地模型如 Ollama完全不需要代理可以清掉代理变量再启动 Codexunset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY codex如果临时清理环境变量对你影响较大也可以在 Codex 配置里增加[api] proxy none这样 Codex 就不会走代理直连本地模型服务了。这条经验我在两个不同环境里验证过都有效。5.2 模型不支持报错的三种应对手段另一种高频报错是类似这样的{detail: the gpt-5.6-sol model is not supported when using codex with a ...}这个报错的意思是你的配置里指定的模型名和后端模型服务支持列表不匹配。常见的原因有三种。第一种你用的是 OpenAI 官方 API但某些新模型在特定配置下不支持 Codex 调用方式。应对方法是在配置里换一个官方支持的模型名或者在 OpenAI 平台上确认该模型对 Codex 开放。第二种你接的是第三方兼容服务但它只支持部分模型名。例如某些中转服务允许你填任意模型名某些却必须精确匹配。这种情况下去你用的服务的文档里查一下可用的模型列表把配置里的模型名改掉。第三种本地模型用 Ollama 部署模型名确实是存在的但你在 Codex 配置里写错了。比如 Ollama 拉取的是qwen2.5-coder:7b你却在 Codex 里写了qwen2.5-coder少了个:7b的 tag就会导致匹配失败。我的习惯是配置 Ollama 模型的场景下先执行ollama list查看准确的模型名再复制到 Codex 配置里基本能避免这类问题。5.3 一个本地部署大模型场景下的经典问题最后分享一个我在本地部署大模型场景下踩过的经典问题你极有可能也会遇到。我把 Codex 配置到本地 Ollama 之后第一次测试的时候Codex 确实能给出回答但回答质量明显比云端模型差了一大截。我一开始以为是模型能力不行后来仔细排查才发现是 Codex 把系统提示词、仓库文件内容统统发给模型后本地小模型7B的上下文窗口被大量无关内容占满真正用于理解任务的空间不够了。解决思路有两个。第一个是精简发送给模型的上下文。Codex 读取文件时我可以提前把不需要的文件排除掉在项目根目录配置.codexignore文件把node_modules、build、dist等目录排除在外减少上下文占用。第二个是换更大参数的模型或者用量化格式更高精度的版本。我在同一台机器上测试了 7B 和 13B 模型13B 对复杂任务的理解能力明显更好但推理速度会慢一些。这是一个权衡没有一个统一答案取决于你的硬件条件和任务类型。我的建议是如果日常任务以简单脚本为主7B 足够如果涉及复杂业务逻辑的多文件修改上更大的模型更划算。6. 扩展方向与最后的几个实用建议6.1 从单机部署到团队共享的进阶思路在打通了本地部署之后有一个自然的进阶方向把 Codex 的能力共享给团队。我的做法是在一台 GPU 服务器上部署 Ollama然后通过内网把base_url指向这台服务器的地址团队成员各自在本地跑 Codex但推理请求统一打到这台 GPU 服务器上。这样一来团队里每个人都能用上 Codex而且模型统一、成本集中在服务器端、代码数据不离开公司内网。配置上只需要改一个base_url的 IP 地址其余基本一致。当然这里要注意并发问题。Ollama 默认会排队处理多个请求如果团队成员同时发起大任务后面的请求会明显变慢。我的建议是GPU 服务器按团队规模配置显存或者用 Ollama 的并发参数做限制避免单任务拖垮整台服务器。6.2 遇到安装卡住、窗口打不开等界面问题的处理方法还有一个让我印象深刻的问题就是 Codex Windows 安装完成但启动不了或者 Codex 窗口反复显示正在重新连接。这类问题大多不是 Codex 本身的问题而是安装过程中权限不足或系统环境变量未刷新。Windows 环境下我建议安装完 Codex 后重启终端窗口而不是直接在当前窗口里跑。Windows 的终端不会自动加载新加入 PATH 的环境变量你需要在新的终端窗口里执行codex命令。如果依然不行确认安装路径是否包含空格或中文如果是重置 npm 全局路径到无特殊字符的目录。至于正在重新连接基本上指向网络或认证问题。检查你的网络是否能正常访问模型服务再确认 API Key 是否过期、配置是否被改动。有一次我发现是自己的配置文件中base_url末尾多了一个空格导致请求地址拼接错误光排查就花了半小时。这种低级错误配置的时候多看一眼就能避免。6.3 部署踩坑后的真实感悟这次完整的 Codex 本地部署做下来我最大的感触是这类工具的部署难点根本不在安装某个软件而在于你能不能把配置文件的每一个字段都理解透彻。Codex 的安装就是一行 npm 命令的事真正花时间的是搞清楚model_provider和base_url之间的关系搞清楚沙箱权限和安全边界的权衡搞清楚不同模型在不同硬件条件下的表现。如果你照着这篇博客的顺序来做大概率一次就能跑通。如果中间卡住了不要慌先看报错信息里提到的是哪个环节——是代理的问题、是模型名的问题还是请求超时的问题。把问题精确定位到某个字段解决起来就快多了。最后再分享一个小技巧在 Codex 配置改动后记得先跑一个最简单的任务测试连通性比如codex 请回答11等于几。如果这个任务能正常返回说明整体通路是通的再去测试复杂任务就能排除掉很多干扰因素。别一上来就跑大任务出了问题你会很难分清到底是模型问题还是配置问题。