Codex CLI 在 Linux 上跑起来后代码修改不再只是网页对话里的代码片段。实际使用中它更像一个住在终端里的编程助手先看项目结构定位需要改的文件生成 diff在你确认后把修改写回工作区。这种工作方式让“让模型改我的代码”从一个演示场景变成了可以纳入 Git 流程的日常操作。不过真正落到 Linux 环境下安装和使用时很多人会先碰到两类问题一类是安装后找不到codex命令另一类是模型配置或config.toml写错导致启动失败。前者通常和 PATH 有关后者通常和模型名、账号权限有关。下面从 Codex 的定位开始再用一个最小 Python 项目跑通完整修改流程最后把高频报错和配置问题单独拆开讲。1. Codex 在 Linux 上解决的是什么问题1.1 它是编程代理不是自动补全工具很多人把 Codex 和 ChatGPT 网页版当成同一件事但实际使用中两者差别很大。ChatGPT 网页版擅长回答问题而 Codex CLI 是围绕“修改代码”设计的工作流它能查看当前目录里的文件读取项目结构运行 bash 命令执行测试看到报错后继续迭代修改。换句话说它不是在终端里聊天而是把“发现问题、形成方案、修改代码、验证结果”这个循环交给模型驱动完成。用更准确的说法Codex 是一个 agent 形态的编程工具。常见的补全工具是在你写代码时给出下一段内容Codex 则能根据一个完整任务去项目里找答案做多文件改动。前者是即时联想后者是任务执行。在 Linux 上使用 Codex最大的优势是它可以直接作用于真实工作区。不需要把报错信息复制粘贴到网页端也不需要手动把模型建议的代码粘贴回文件。只要在项目根目录运行它它就能把修改结果落到磁盘上并通过 Git diff 让你清楚地看到改了什么。1.2 一次代码修改的底层工作链路从用户角度看Codex 改代码一般会经历这样几条链路理解任务它先解析 prompt确认用户要修 bug、加功能还是做重构。收集上下文它会查找相关文件读取函数定义、调用关系、代码注释和测试用例。规划修改在当前文件或多个文件之间形成改动方案。执行验证如果需要它会尝试运行命令、跑测试再根据结果调整代码。展示结果最终返回 diff由用户决定是否接受、继续调整或回滚。这里要注意Codex 不是没有约束地在系统里任意执行命令。多数 CLI 版本会提供权限控制和沙箱机制。模型可以建议执行命令但真正运行前通常需要用户确认。这样做的目的是保护文件系统避免一次错误 prompt 把项目弄坏。1.3 准备工作需要哪些基础在开始之前建议你已经掌握这些 Linux 基础能力能在终端里使用cd、ls、cat、git等基础命令。理解 Git 工作区、暂存区、提交和 diff 的概念。能读懂简单 Python 或 JavaScript 代码便于检查 Codex 的修改结果。遇到权限问题时知道 Node 的全局安装路径和 PATH 环境变量如何配置。如果这些还不熟悉建议先拿一个无风险项目练习。Codex 越能“看清楚改动”你的人工检查成本就越低。2. 在 Linux 上安装 Codex先把运行环境对齐2.1 最小环境清单不同 Codex 版本对系统要求不完全一致。实际安装前最好先在终端里确认三样东西node -v npm -v git --version如果node或npm不存在就需要先安装 Node.js。多数 npm 分发的 Codex CLI 对 Node 版本有要求老版本 Node 容易出现语法解析错误或运行时崩溃。稳妥做法是安装当前 Node.js LTS 版本而不是追求最新版。git不是运行 Codex 本身必需的吗从实践看强烈建议在 Git 项目里使用它。Codex 生成修改后Git diff 是最直观的检查手段如果修改方向不对也可以直接回滚。没有 Git 的项目Codex 也能工作但风险会明显增加。安装 npm 包时需要能正常访问 npm registry。如果你的 Linux 服务器使用内网 npm 镜像请先配置好 registry否则安装阶段会直接超时。2.2 安装并验证 codex 命令在确认 Node、npm、git 都可用后安装 Codex CLInpm install -g openai/codex安装完成后先验证版本codex --version如果输出正常说明 npm 安装成功且 PATH 已经能识别codex。如果提示codex: command not found通常是 npm 全局安装目录不在 PATH 中。可以先查看 npm 全局目录npm config get prefix比如输出是/home/youruser/.npm-global那么 bin 目录就是/home/youruser/.npm-global/bin。把该目录加入 PATHexport PATH$(npm config get prefix)/bin:$PATH为了让新终端自动生效可以把这行写入 shell 配置文件。使用 Bash 时echo export PATH$(npm config get prefix)/bin:$PATH ~/.bashrc source ~/.bashrc注意安装命令中的包名和路径细节会随 Codex 版本变化。如果npm install后没有找到可执行文件优先到对应项目 README 或发行说明里确认当前支持的安装方式。2.3 登录 Codex 并确认凭证状态Codex 执行代码修改能力依赖后端模型服务因此安装之后还需要登录或配置 API Key。常用方式是codex login执行后通常会打开浏览器页面授权完成后 CLI 会提示登录成功。退出当前会话后再重新执行codex --version和一个小任务能确认凭证是否已经持久化保存。如果你使用 API Key也可以在环境变量中配置export OPENAI_API_KEY你的-api-key这里有一个非常容易踩的坑不要把 API Key 写进config.toml、代码文件或 Git 提交历史。Key 一旦泄露别人就可以消耗你的配额。生产环境应当使用系统密钥管理服务至少也要放在 shell 的环境变量文件里并确保文件权限只有当前用户可读。3. 最小项目实操让 Codex 修复一个累计金额 Bug3.1 先准备一个带 Bug 的 Python 项目为了验证 Codex 是否真的能改代码我们创建一个很小的项目故意在calculate_total函数里写错一个累加逻辑。mkdir -p ~/projects/codex-demo cd ~/projects/codex-demo git init创建cart.pycat cart.py PY def calculate_total(items): total 0 for item in items: total item[price] * item[quantity] return total if __name__ __main__: cart [ {name: keyboard, price: 99, quantity: 2}, {name: mouse, price: 45, quantity: 3}, ] print(expected:, 99 * 2 45 * 3) print(actual: , calculate_total(cart)) PY先运行一次确认 bug 存在python3 cart.py输出应该是expected: 333 actual: 135问题非常典型循环内应该是累加但代码写成了每次重新赋值导致最后只剩最后一件商品的总价。把这个初始状态提交到 Gitgit add cart.py git commit -m init: add cart totalGit 提交很重要。后续 Codex 修改后我们可以通过git diff看到精确差异也能随时回退到当前状态。3.2 给 Codex 下达明确的修复任务在项目根目录执行 Codex。不同版本支持的命令形态不同常见有非交互式execcodex exec 修复 cart.py 中 calculate_total 的总金额计算错误。要求保留 calculate_total 函数签名修改后运行 python3 cart.py并确认 expected 和 actual 都等于 333。如果你的版本没有exec子命令直接运行codex进入交互界面后输入同样的话然后等待它完成修改。这里要解释 prompt 为什么这样写。不要只写“修 bug”而是告诉模型文件是哪个cart.py函数是哪个calculate_total验收标准是什么运行python3 cart.pyexpected和actual都等于 333。Codex 得到明确的验收标准后能自己判断修改是否成功。如果 prompt 写得太泛比如“帮我看看价格计算”它可能会进行多余重构反而增加检查成本。3.3 查看 diff、运行结果并提交Codex 返回后先用 Git 检查它改了什么git diff如果修复正确diff 里应该出现类似内容- total item[price] * item[quantity] total item[price] * item[quantity]也可以看统计信息git diff --stat预期看到只有一个文件变化改动了 1 行。如果 Codex 还创建了测试文件你会在git status里看到新文件这时要逐个确认测试文件是否合理。再运行一次验证python3 cart.py输出应该是expected: 333 actual: 333确认无误后提交git add cart.py git commit -m fix: accumulate cart total注意不要只验证程序能启动还要验证输出是否符合预期。Codex 即使没有真正改对代码也可能给出“我已经修复”的陈述因此人工运行验收命令是不可省略的。4. 配置 config.toml启动失败大多从这一层开始4.1 config.toml 到底放在哪里在典型安装方式中Codex CLI 会读取用户目录下的~/.codex/config.toml。如果这个文件不存在很多情况下它可以使用默认配置一旦你手动创建了文件启动时就会严格解析这个 TOML 文件。检查配置是否存在ls -la ~/.codex cat ~/.codex/config.toml如果文件已经存在但内容不完整建议先备份再决定是否删除cp ~/.codex/config.toml ~/.codex/config.toml.bak在你排查“Codex 启动失败”的问题时config.toml是最常见的源头。它决定了两类关键信息当前会话使用哪个模型以及 Codex 被允许做什么。4.2 一个最小可用的示例结构下面是一个用于说明结构的示例。模型名不要直接照抄因为 Codex 账号、OpenAI API Key、第三方兼容服务可用的模型集合完全不同。# ~/.codex/config.toml 示例仅展示结构和注释方式 # model 值必须替换为你当前账号实际可用的模型 model your-account-supported-model这个文件虽然只有一行但能解释很多报错。如果你在网页端或旧教程里看到某个模型名直接写入配置结果往往是登录的账号不支持该模型。更完整的配置还可能包含模型提供商、请求地址、审批策略和沙箱模式等内容。不同 Codex 版本对这些字段的支持程度不一样因此最保险的方式是先用默认配置跑通一个最小任务再逐步增加自定义项。4.3 常见参数的影响下面这些字段和 Codex 的实际行为强相关配置时建议逐个验证配置方向作用配置错误的典型表现模型名决定用哪个模型处理代码任务启动报模型不支持或新会话无法继续模型提供商或接口地址决定请求发往哪个服务请求失败、鉴权失败、模型不可用执行权限或审批策略控制 Codex 是否可以运行命令总是请求运行命令或未经确认就越权修改沙箱模式控制它能访问哪些目录读不到项目文件或修改范围过大写config.toml时要注意 TOML 语法字符串要用双引号不能有中文字符引号不要出现重复的键。如果只有一行配置写错Codex 可能直接拒绝启动因为它无法确定当前会话应该使用什么模型。5. 高频错误Codex 在 Linux 上跑不起来怎么办5.1 安装后提示codex: command not found现象命令行执行codex --version报错找不到命令或者安装过程没有报错但 shell 无法识别。检查顺序which codex npm config get prefix ls -l $(npm config get prefix)/bin/codex如果ls显示文件存在说明只是 PATH 没配对。执行export PATH$(npm config get prefix)/bin:$PATH codex --version如果文件本身不存在说明 npm 全局安装失败。常见原因是 npm 使用的全局目录没有写入权限。推荐使用用户级全局目录避免用sudo强装mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH npm install -g openai/codex codex --version5.2 编辑器插件报Unable to locate the codex CLI binary在实际使用中很多开发者不是在纯终端里运行 Codex而是通过 ChatGPT 桌面端、JetBrains 插件、VS Code 插件调用。此时可能看到类似错误ChatGPT failed to start. Unable to locate the codex CLI binary. Set codex_cli_path or ensure the Electron app has access to codex in PATH.这个错误不是模型问题也不是配置问题而是外部应用找不到codex可执行文件。原因是图形应用的环境变量通常与 shell 不同shell 里配置的 PATH 不一定会传给应用。先找到绝对路径which codex假设输出是/home/youruser/.npm-global/bin/codex再在启动应用的终端里导出一个可识别的环境变量或在插件设置里填入绝对路径。变量名以错误提示的写法为准常见是export codex_cli_path/home/youruser/.npm-global/bin/codex然后重启应用。如果应用仍然找不到检查是否给应用授予了读取该路径的能力。不要把codex放到被系统限制的隐藏目录里否则应用扫描不到。5.3 提示无法加载 config.toml或model is not supported现象Codex 启动时提示无法加载 config.toml因此此对话串无法继续。 请修复 config.toml: model或者The gpt-5.6-sol model is not supported when using Codex with a ChatGPT account.这类错误的核心原因是Codex 在新会话开始前需要确定模型而config.toml里的模型名不可用或语法本身有问题。处理顺序备份当前配置cp ~/.codex/config.toml ~/.codex/config.toml.bak先让 Codex 使用默认配置启动mv ~/.codex/config.toml ~/.codex/config.toml.bak codex --version如果移走配置后能正常执行说明问题就在原配置内容里。把配置中的模型名改成账号实际支持的模型或删除自定义模型项重新启动。不要在对话中途修改模型名后继续旧会话最好新建会话。这类报错最容易出现在两种情况一种是从网络复制了某个“最新模型名”但账号并没有对应权限另一种是会话历史里记录了旧的模型上下文配置修改后模型不匹配Codex 无法继续。5.4 Codex 说改好了但工作区没有任何变化现象Codex 给出了修改建议但git diff为空或者文件内容没有变化。先确认是否在正确的项目目录pwd git status git diff不在 Git 仓库里运行时Codex 仍然可以读取文件但修改可能