最近好几个朋友来问我同一个问题OpenAI 的那个 Codex 到底怎么装、怎么配、怎么才能让它老老实实跑在本地模型上。说实话这工具刚出的时候我也被折腾过一阵子官方文档写得不算难但实际操作里坑不少尤其是想用本地大模型替换官方服务的时候配置文件的细节一个不对就报错。这篇就按我踩过的路把 Codex 下载、安装、登录、本地模型接入、常见报错排查整个流程完整过一遍目标是你照着操作也能搭起一个能用的 AI 编程助手。Codex 是 OpenAI 推出的命令行 AI 编程助手可以直接跑在终端里它能读懂你的代码仓库、执行命令、修改文件还能和你多轮对话。跟网页版 ChatGPT 最大的区别是它工作在你的项目目录下能直接操作真实文件。对我这种习惯在终端里干活的人来说这东西比切到浏览器里复制粘贴代码方便太多。它适合所有写代码的人前端、后端、脚本爱好者、做数据处理的都行哪怕你只会写一点 Python 也能受益因为它能帮你解释报错、写测试、做代码审查。唯一的门槛是你得能接受命令行为主的工作方式如果你纯用 IDE 和鼠标干活那 Codex 的体感会差一些。下文我会从这五个方面展开Codex 的定位和核心能力、安装前的账号与运行环境准备、官方模型和本地模型Ollama DeepSeek两种部署方式、config.toml 配置文件详解与中文使用技巧、以及我实际使用中遇到的高频报错和排查方法。全程基于真实操作所有配置示例都是我自己跑通过的。1. 先搞清楚 Codex 是个什么东西1.1 它不是一个网页对话框而是一个终端里的编程助手Codex 最初出现在 ChatGPT 的界面里是那种能看到你代码库的智能体。但真正让它变成生产力的是 OpenAI 后来放出的 Codex CLI命令行版本。你安装后在终端里输入codex就能进入交互模式Codex 会请求读取你当前目录下的文件并根据你的指令新增、修改、删除文件或者帮你执行命令。很多人的误解是这不就是个终端版的 ChatGPT 吗不是。Codex 最大的特点是agentic意思是你给它一个目标它会自己规划步骤逐步执行中途遇到报错会自己尝试修复而不是每次都要你来交代下一步怎么走。比如我让它给这个项目写一套完整的单元测试它会先看项目结构、读懂代码逻辑、选一个测试框架、创建测试文件然后跑一遍测试把失败的用例修掉最后输出一份汇总。这个流程在网页版里也能做但在终端里做会更自然因为它和目标代码库处在一个环境里。1.2 它能做什么、不能做什么先说能做的实测下来最顺手的几个场景解释代码把一坨不熟悉的老项目代码丢给它让它分模块讲清楚每段逻辑比人肉读代码快很多。写测试让它为现有函数生成边界用例省力但审查还是得自己来。改 bug把报错信息贴给它它能定位到大概位置给出修复方案并直接改掉。批量重构比如把整个目录下的 A 接口调用换成 B 接口这种机械活交给它准确率不错。跑命令它可以直接执行 npm、pip、git 命令你不用反复切换窗口。不能做或者说做得一般的事情也要有预期它不能读你当前屏幕之外的信息比如另一个终端里正在跑的服务日志除非你把日志写到文件里让它读。它不能替你做架构决策。你说帮我重构为微服务它能写代码但你得自己定义好服务的边界。它对超大仓库的处理会慢文件多了上下文容易爆需要你有选择地控制读取范围。1.3 部署形态官方服务、第三方模型、本地模型都能接Codex 的一个关键设计是它支持灵活切换模型提供方model provider。在你的配置文件里指定一个 base URL 和模型名即可。这意味着你完全可以不用 OpenAI 的服务器跑 Codex而是接到自己的本地模型比如 Ollama 里的 DeepSeek、第三方兼容服务只要能提供一个 OpenAI 兼容的 API 接口就行。这个设计对国内用户和注重数据隐私的用户都很重要后面我会详细讲配置。2. 安装前准备账号、订阅与运行环境2.1 账号和付费先搞清楚三种认证方式的区别安装本身不收费但这个工具的使用要分情况。Codex 在终端里运行时的认证有两种主流方式ChatGPT 账号和 API Key。ChatGPT 账号如果你订阅了 ChatGPT Plus20 美元/月或者 Pro200 美元/月登录后可以直接用 Codex 的官方模型使用额度包含在订阅里。Team 和 Enterprise 类似有管理员分配额度。API Key去 platform.openai.com 创建 API Key走按量计费pay-as-you-go这些费用独立于 ChatGPT 订阅。API 方式更灵活但要注意控制成本大模型任务量大的时候账单涨得快。本地模型完全不需要 OpenAI 账号也能跑Codex 只负责发请求给本地模型的服务端点。这里唯一要注意的是Codex CLI 的登录流程默认会尝试去访问 OpenAI 的服务端拿用户信息但如果我们配置好本地模型后可以绕过这一层直接以 API Key 方式甚至可以随便填一个占位 key跑起来。我的建议如果只是尝鲜先用 ChatGPT 账号登录不需要额外掏钱。如果以后要在自己的工具链里做自动化脚本再申请 API Key 也不迟。注意使用第三方或本地模型时别用 ChatGPT 账号登录直接选择 API Key 认证方式并填入对应的 key本地模型可以填占位值否则 Codex 会优先使用官方账号的模型配置你为本地模型写的 provider 配置就不生效了。2.2 运行环境Node.js 版本是第一个坑Codex CLI 是基于 Node.js 的官方要求 Node.js 18 及以上版本。我建议直接装 LTS长期支持版比如 20 或 22。很多安装失败或者运行时报ECONNREFUSED、模块加载失败的情况最后查下来都是 Node 版本太低。检查自己环境的命令node -v npm -v如果没有装 Node推荐用 nvmNode Version Manager来装比直接装系统包好维护得多。macOS 上也可以用 Homebrewbrew install node20Windows 用户建议直接用官方安装包或者 winget。装完之后把 npm 全局 bin 目录加到 PATH 里这一步 Windows 上安装器一般会自动处理但用 nvm 的话得自己确认。2.3 下载与安装npm 和 Homebrew 两条路Codex CLI 的安装其实就是一个 npm 包。两条常用路径npm install -g openai/codex或者 macOS 用户用 Homebrewbrew install codex装完验证一下codex --version这里有个细节Codex CLI 的版本迭代非常快经常一两周就更新一次所以建议养成定期升级的习惯npm update -g openai/codex我在第一次安装时遇到过一个EACCES permission denied的报错是 npm 全局目录权限问题。解决办法要么用 sudo不推荐要么用 nvm 之后把全局目录放到用户目录下。具体可以在 npm 配置里执行npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH2.4 登录ChatGPT 账号与 API Key 的两种方式安装完成后第一次运行codex它会引导你登录。两种方式ChatGPT 登录codex login选择 ChatGPT会弹出一个浏览器窗口授权后回到终端就完事了。这种方式适合订阅了 Plus/Pro 的用户。API Key 登录codex login选择 API Key它会让你粘贴 key。这个 key 会写到本地的认证文件里由 Codex 调用官方模型时使用。我实测下来如果你要用本地模型可以两种都不选而是直接编辑配置文件指定 provider。但codex login这个命令在启动时还是会尝试检查认证状态。聪明的做法是创建一个自定义 provider然后在配置里把默认的 model 指向它这样即使认证无效也能跑。不过对新手来说最省心的还是先登录 API Key 方式用官方模型跑通一遍再切换到本地模型。3. 本地部署让 Codex 跑在本地大模型上3.1 为什么要折腾本地模型省钱、隐私、可控把 Codex 接到本地模型不是为了折腾而折腾实际收益挺明显的。第一是隐私。公司代码往往有保密要求把代码发给远程模型服务总是有心理负担。本地部署之后请求全部在本机或内网服务器上完成代码不会离开你的环境。第二是成本。官方 API 重度使用一个月账单不便宜本地模型一次部署之后电费和显卡折旧几乎可以忽略。虽然效果不如大厂旗舰模型但日常的代码解释、写测试、简单重构完全够用。第三是可玩性。本地模型你可以随便换、随便调参不用受单一代际版本限制。今天想试试 DeepSeek明天想试试 Qwen改个配置就切过去了不用重新学一套工具。当然开销也有你需要一台配置不差的机器尤其是显存。我的建议底线是 16GB 显存跑 7B~14B 参数的量化模型比较流畅。如果只有 CPU小尺寸模型也能跑但速度会比较感人。3.2 用 Ollama 部署本地模型一个命令的事Ollama 是目前跑本地大模型最简单的工具没有之一。它把下载模型、启动服务、提供 OpenAI 兼容接口这些事情全包了。安装好 Ollama 之后拉取一个模型ollama pull deepseek-r1:14b这里我以 DeepSeek 为例实际上你也可以换 qwen2.5-coder、llama3.1 等模型。拉完之后启动服务通常安装后会自动常驻ollama serve默认情况下Ollama 的服务跑在 11434 端口并且提供一个 OpenAI 兼容的端点http://localhost:11434/v1可以直接用 curl 验证curl http://localhost:11434/v1/models看到模型列表就说明服务正常了。这个http://localhost:11434/v1就是我们后面要填给 Codex 的 base_url。实操心得Ollama 的自动启动在某些 Linux 发行版上偶尔失效如果你发现本地模型一直连不上先手动执行ollama serve看看有没有端口占用报错。另外防火墙如果开着记得放行 11434 端口的本地回环访问。3.3 让 Codex 走本地模型model_providers 配置解析打开 Codex 的配置文件。在 macOS/Linux 上路径是~/.codex/config.tomlWindows 上是%USERPROFILE%\.codex\config.toml。如果文件不存在第一次运行codex登录后会自动创建。这个文件的语法是 TOML非常简洁。要让 Codex 使用本地模型只需要定义一个自定义 provider然后把默认模型切换过去。以下是完整的示例model deepseek-r1:14b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api responses解释一下每个字段的含义model告诉 Codex 默认使用哪个模型名称。这个名称必须和 Ollama 里拉取的模型标签一致否则会报model not found。model_provider指定默认 provider 的名字这里叫ollama是你在下方自定义的 key。[model_providers.ollama]定义一个名为 ollama 的 provider。name展示名称随便填。base_url关键字段OpenAI 兼容 API 的地址。因为 Codex 默认走 OpenAI 协议所以本地服务必须兼容/v1路径Ollama 正是如此。env_keyCodex 会从环境变量读取这个 key 作为请求的 Authorization 头。本地 Ollama 不校验 key但你得设一个占位环境变量不然 Codex 可能报认证失败。在 shell 配置里加一行export OLLAMA_API_KEYollama就行。wire_api这里填responses还是chat取决于你接入的服务。Ollama 目前兼容的是/v1/chat/completions而 Codex 默认用responses协议。实测中填chat更稳但新版 Codex 对responses也做了兼容适配。我这里写responses是因为新版 Codex 默认端点会走/responses如果你遇到 404 或者 501 错误改成chat试试。改完配置后重启 Codex输入codex进入交互模式它会走本地模型回答。3.4 升级玩法cc switch 与多模型切换用本地模型只是第一步。实际用下来我发现一个痛点不同任务适合不同模型。日常答疑用小模型够快重活累活得切大模型。手动改配置文件太麻烦所以出现了一堆辅助工具其中热度最高的就是 cc switchCodex Community Switch。cc switch 本质上是一个管理 Codex 模型配置的小工具它能让你在多个配置档位之间快速切换每个档位可以指定不同的 provider、模型名和 base_url。它的安装通常也是 npmnpm install -g codex-community/cc-switch然后cc switch命令会弹出一个终端交互界面列出当前所有配置档位按方向键选择即可切换。切换的原理是重写config.toml里的默认model和model_provider字段。这个工具还有一个比较实用的场景是配合代理调试网络问题后面在报错排查里我会详细讲。注意cc switch 这类工具会对你的 config.toml 做改动使用前最好备份一份cp ~/.codex/config.toml ~/.codex/config.toml.bak。它的版本也在快速更新部分版本和新版 Codex CLI 不兼容遇到奇怪的问题先更新工具本身。4. 配置与使用技巧中文环境、常用命令、工作流4.1 一份完整可用的 config.toml 示例前面讲了本地模型配置的骨架这里给一份更完整的、带系统提示词的配置# Codex 全局配置 # 默认模型与默认 provider model deepseek-r1:14b model_provider ollama # 定义本地 Ollama provider [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat # 另外定义官方 OpenAI provider方便随时切回 [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses # 系统提示词相当于给 Codex 一个前置设定 [system_prompt] role system content 你是 Codex一个运行在终端里的 AI 编程助手。请用简洁清晰的中文回答涉及技术名词时可保留英文原文。当你在改代码前先向用户说明你要做什么然后再动手。注意最后一个[system_prompt]的写法在不同版本可能不一致如果你用的 Codex 版本不支持这个字段可以忽略它或者在交互模式下先手动输入一句请用中文回答Codex 会在本次会话中记住这个偏好。4.2 让 Codex 说中文一个简单但很实用的技巧Codex 的界面、菜单、帮助文档默认都是英文很多人问怎么设置成中文。说实话目前官方没有提供中文 UI 的开关但我们有更直接的办法改变模型输出的语言偏好。第一种方法是加系统提示词像上面那样让模型默认用中文回答。这个方法对本地模型尤其有效因为 DeepSeek 这类中文语料充足的模型你用中文指令引导一下输出就很自然。第二种方法更简单每次进入交互模式时第一句先发请用中文回答我但保留代码术语原文。模型会在这个会话里记住这个风格。实测中 DeepSeek 和 Qwen 对这个指令都很敏感几乎不用重复。第三种是环境变量方式。新版 Codex 支持通过CODEX_LANG环境变量影响界面语言但效果不稳定我试了之后还是回到前两种方法。如果你在 GitHub 上关注 Codex 的更新日志会发现中文 UI 的 issue 一直是 open 状态估计后续版本会有官方方案。4.3 Codex 的常用命令与三种用法Codex CLI 不只是进入交互式聊天这一种用法。它主要提供三个层级的功能交互模式codex直接进入一个 shell 风格的对话界面适合探索性的任务比如解释一下这份代码怎么优化。在这里 Codex 会按对话历史记忆上下文你可以连续追问。单次执行codex exec 给这个项目写一个 README不需要进入交互界面一条命令直接给出结果。适合批量脚本、CI/CD 流水线集成、快速问答。审批模式codex exec --sandbox git statusCodex 在执行命令前先征求你的同意避免它自作主张帮你跑什么危险命令。这个模式最适合新手也最适合跑在自动化脚本里。查看帮助codex --help任何时候不知道能用什么参数先敲这个。我自己常用的命令组合codex exec 分析当前目录下所有 Python 文件的依赖关系输出一个报告 codex --full-auto 修复 src/utils.py 里的所有类型标注错误--full-auto这个标志允许 Codex 自动执行所有命令不需要逐条确认。我建议只在你有版本控制的仓库里使用它防止它改乱了没法还原。4.4 工作流建议什么时候该开沙箱沙箱模式sandbox是 Codex 的一个精髓。它默认在沙箱中执行命令意味着 Codex 对文件系统的更改是受限的需要它主动请求权限才会放开。对第一次使用的人来说强烈建议开启审批codex --dangerously-bypass-approvals-and-sandbox看到这个又长又吓人的参数名你就知道它的危险性了。它完全是放权的Codex 可以自由读取、修改、执行。我只推荐在你完全信任当前项目且已经提交过 Git 的情况下使用否则出了问题你连翻盘的机会都没有。我的工作流是这样的探索和提问阶段用普通的codex交互模式批量改文件的时候先用codex exec跑一次干跑不实际改文件看它给出的 diff 是否合理再放权执行只有在极其信任的自动化管道里才开 full-auto。这个习惯帮我挡住了好几次差点被 Codex 大改代码结构的风险。5. 常见问题与排查实录5.1 登录不上、组织设置加载失败很多人第一次跑codex卡在登录环节浏览器弹出来半天不通过。排查路径如下先确认你的网络能正常访问 OpenAI 的官方认证服务。这一步如果网络环境特殊大概率会失败。怎么确认用终端的 curl 测试curl -I https://auth.openai.com如果请求超时或者 TLS/证书错误说明这个网络环境下走官方认证有困难。一个务实的建议不想折腾网络的话直接用 API Key 方式登录在~/.codex/auth.json里放一个 key认证速度通常会比浏览器授权快。另外经常有人遇到组织设置加载失败或者 organization settings failed to load。这个很常见原因大多是 Codex CLI 需要读取你的组织信息但组织信息在官方服务端无法正常拉取。我的处理方式是忽略它直接进入对话界面。你还可以尝试删除本地旧的认证缓存文件后重新登录rm -rf ~/.codex/auth.json codex login如果问题依旧检查你使用的 Codex 版本是否过旧先执行一次全局更新再看。5.2 cc switch local proxy failed while handling codex endpoint /responses 报错这个报错是实际使用中高频出现的一个报错原文很长大概长这样cc switch local proxy failed while handling codex endpoint /responses. provider: cc-switch-local-proxy, verify configurations in cc-switch先说结论这个报错基本可以锁定是 cc switch 的本地代理没有正常启动或者端口被占用。cc switch 在切换配置时有时会选择通过一个本地代理服务器local proxy来转发请求到目标模型服务。这个代理服务跑在某个本地端口上如果那个端口被别的进程占用了或者代理服务没有随着你的切换操作而启动Codex 发往/responses的请求就会失败。排查步骤依次是打开 cc switch 的面板看当前激活的配置是否带有 local proxy 字样。如果有切到一个不带本地代理的配置再试试。查看端口占用。默认情况下代理端口是 15201。执行lsof -i :15201Linux/macOS或者netstat -ano | findstr 15201Windows看看这个端口有没有进程在监听。没有的话就是代理没起来。如果端口被其他程序占用要么杀掉占用进程要么在 cc switch 的配置里改一个不同的端口。确认config.toml里的base_url是否指向了http://127.0.0.1:15201/v1这是 cc switch 代理的典型地址。如果指向错误请求当然会失败。最后提一句如果你根本没有用 cc switch也出现了包含local proxy的报错那大概率是之前装过 cc switch它的残留配置写进了config.toml把model_provider指到了一个已不存在的本地代理。这时候直接编辑config.toml把model_provider改回你的本地模型 provider 名字即可。5.3 模型不识别、404、端点错误类报错使用本地模型时404 Not Found和model not found是两个最常见的报错。这俩的区别在于model not foundCodex 成功连上了本地服务但你要的模型名比如deepseek-r1:14b在本地服务里不存在。用ollama list查看当前有哪些模型把model字段改成准确的名称即可。404 Not Found请求的路径不对。Ollama 的 OpenAI 兼容端点是/v1/chat/completionsCodex 默认发往/v1/responses。这时候你需要把 provider 配置里的wire_api改成chat而不是responses。还有一种情况是 Codex 能连上服务但服务一直转圈不返回这多半是模型推理太慢或者上下文太长撑爆了显存。本地模型的上下文长度参数context length通常不如官方大模型你让 Codex 一次性读入好几个大文件它很容易把上下文窗口塞满。应对办法是限制它读取的文件数量或者直接换一个更大显存的机器。实操心得本地模型最容易出问题的不是能不能连上而是 上下文窗口太小 和 代码理解能力不够。7B 模型跑常见代码逻辑没问题但如果你丢给它一个复杂的全栈项目它的表现会明显比官方模型差一截。我的经验是本地模型适合做小步快跑的任务解释一个函数、写一段测试、改一个小 bug。大型重构和架构设计这类任务还是用官方旗舰模型更靠谱。5.4 其他值得记下的排查技巧把这类问题整理成一个速查表方便你以后直接对照报错/现象大概率原因处理方法EACCES permission deniednpm 全局目录权限问题设置npm prefix到用户目录或用 nvm 重装 Nodecodex: command not foundnpm 全局 bin 没加到 PATH检查~/.npm-global/bin是否在 PATHconnect ECONNREFUSED 127.0.0.1:11434Ollama 服务没启动或端口错了手动执行ollama serve确认端口登录时浏览器授权转圈网络访问认证服务不稳定改用 API Key 登录或确认网络环境可访问官方服务401 Invalid API keyenv_key 对应的环境变量没设置在 shell 配置里export对应的 key 环境变量message length too long上下文超过模型限制减少读取文件数或换更大上下文模型Codex 执行git commit失败项目目录不是 Git 仓库先git init或让 Codex 不要执行 git 命令还有一个通用的排查思路看日志。Codex CLI 在运行时会输出详细日志通常保存到~/.codex/log/目录。日志文件名包含时间戳打开最新的一个搜索ERROR或stack trace很多时候根因就在里面。别急着满世界搜报错文案日志里通常把真实原因写得很明白。另外一点就是版本管理习惯。Codex 更新频繁cc switch 更新也频繁两边不是总保持兼容。如果你今天发现之前好好的配置突然报错先想想最近是不是升级过其中任何一个工具。回退版本有时候比找问题更省时间。6. 实操总结与扩展建议把本地模型跑到 Codex 里这件事做完后我对这套组合的感受是它能干实事但期待值要放对。官方模型像是配了顶级大厨的餐厅点菜问问题马上给你上桌味道稳定菜品丰富本地模型更像是自己在家做饭前期备菜下模型、调配置花时间但掌握了火候之后简单家常菜完全够用而且隐私安全成本还低。我个人在实际操作中最满意的用法是把 Codex CLI 接入本地 DeepSeek 后让它每天自动给项目跑一遍静态检查并生成摘要相当于一个不要钱的 AI 代码巡检员。启动一个定时任务codex exec --sandbox 检查当前目录下所有 TODO 注释和 FIXME 注释生成一个待办清单输出会直接打到终端配合 cron 每天上午跑一次效率提升非常明显。如果后面还想进一步扩展有两条路可以考虑一是用 cc switch 配置多套本地模型DeepSeek 负责代码Qwen 负责解释概念Llama 跑英文文档按任务切换二是把 Ollama 部署到局域网服务器上让整个团队都通过 Codex 连同一个本地模型实现团队级的代码助手能力。前提是那台服务器的显存和内存要足够建议起步 32GB 内存、16GB 显存。最后再分享一个小技巧Codex 在使用本地模型时sandbox模式反而比官方模型更重要。因为本地模型指令遵循能力偏弱有时候你只是让它看看文件它可能自作主张执行命令。开--sandbox或者默认的审批制能避免它在本地环境里乱动东西。反正多一道确认端口成本很低但能省下很多恢复现场的时间。
