这次我们来看 Codex 的安装、模型接入和实际跑任务。Codex 是 OpenAI 推出的 AI 编程代理不是普通聊天助手你给它一个任务它会自己读项目文件、改代码、执行命令、提交 Git 记录。如果你经常在终端里写脚本、改仓库、做批量代码处理这个工具比反复复制粘贴到网页聊天框要直接得多。这篇文章按下面这条链路展开先给规格速览说清楚它能做什么、不能做什么然后讲 Codex CLI 在 Windows / macOS / Linux 上的安装与登录接着把大家最关心的“接入 GPT-5.6”单独拆开讲模型配置、错误处理和第三方兼容接口再实际跑第一组功能测试最后补接口化批量调用、资源占用观察和常见问题排查。先说结论Codex 是云端模型服务本地不推理所以没有显存要求常规办公本就能跑。瓶颈通常在网络、API Key 和模型配置。如果你只想解决“安装 - 登录 - 第一次跑通”这三件事直接看第 4 节和第 5 节。1. 核心能力速览能力项说明项目类型AI 编程代理CLI / 桌面端是否本地推理否依赖云端模型服务安装方式npm 安装 Codex CLI、桌面版 App支持平台Windows / macOS / Linux模型接入OpenAI 官方模型 OpenAI 兼容服务核心功能代码生成、仓库阅读、命令执行、Git 操作、Skills 扩展本地资源占用主要是 CPU、内存和网络带宽无显存要求批量任务支持codex exec非交互式调用可脚本化审批控制支持命令执行前人工确认或自动批准策略项目规则支持读取项目根目录AGENTS.md作为任务规则适合场景单人写脚本、仓库重构、自动化 PR、批量代码任务编排这里要处理一下标题里“白嫖 100 美刀”的说法。OpenAI 新账号是否有试用额度、活动赠送多少、有效期多长都要以官方页面和个人账户后台为准本文不讨论绕过计费、刷额度、共享账号、转售额度这类操作。这些做法既违反服务条款也可能导致账号封禁。把注意力放在“安装、配置、跑通任务”上才是真正能沉淀下来的技术能力。2. 适用场景与使用边界Codex 适合下面几类人日常要写大量一次性脚本的开发者比如数据清洗、文件整理、格式转换。需要在已有仓库里做小范围改动的开发者比如补测试、修 TODO、统一日志格式。想把“代码生成”接进自动化流程的人比如用非交互模式批量生成文件、批量重构。团队想统一 Agent 工作规则的场景比如通过AGENTS.md告诉 Codex 代码风格、提交规范、目录组织方式。Codex 不适合这些场景需要完全离线、私有化部署的团队Codex 默认不是本地推理模型。需要严格隔离机密代码且不允许代码片段离开本机的场景需要先做合规评估。对单次执行成本非常敏感的团队长时间大仓库任务会消耗较多 token。使用边界要明确Codex 会自动读取工作目录里的文件并可能执行命令、修改文件、创建提交。所以启动前要确认它只在你授权的目录里工作。涉及第三方源码、公司内部代码、个人隐私数据时要确认你有权处理这些内容。不要用它处理没有授权的人脸、声音、隐私文档也不要让它执行高风险命令行操作。3. 环境准备与前置条件Codex 的本地环境要求不算高核心是 Node.js 和 Git。准备清单如下。检查项要求操作系统Windows 10/11、macOS、常见 Linux 发行版Node.js建议 18 及以上版本低版本可能导致安装失败Git需要 Git 命令行可用Codex 会调用 Git 做仓库操作终端Windows 用 PowerShell 或 Windows TerminalmacOS/Linux 用默认终端账号OpenAI 账号或 API Key用于模型服务鉴权网络能正常访问 OpenAI 服务或你配置的兼容 API需保持稳定先检查本机环境。在终端执行node -v npm -v git --version如果node或npm不存在先去 Node.js 官网安装 LTS 版本装完重新打开终端再检查一遍。Windows 用户如果安装过 Node.js 但命令找不到通常需要手动把 npm 全局目录加入系统 PATH这一步可以在安装 Node.js 时勾选自动配置。磁盘空间不需要专门准备Codex CLI 本身很小主要消耗的是后续仓库操作时产生的日志、缓存和中间文件。建议单独建一个codex-work目录把测试项目放在里面避免 Codex 在系统目录或用户主目录里乱跑。4. Codex 安装与启动方式4.1 npm 安装 Codex CLI最直接的安装方式是通过 npm 全局安装npm install -g openai/codex安装完成后验证版本codex --version如果提示codex命令找不到先检查 npm 全局目录npm root -g然后把npm root -g对应的父目录bin 目录加入 PATH 环境变量。Windows 下通常在%APPDATA%\npmmacOS/Linux 下通常在/usr/local/bin或~/.npm-global/bin具体以npm prefix -g输出为准。4.2 安装桌面版Codex 也有桌面版 App面向不需要处理终端命令的用户。桌面版的安装包从 OpenAI 官方渠道下载Windows 和 macOS 都有对应的安装程序。安装完成后直接用账号登录打开项目文件夹在图形界面里输入任务即可。桌面版适合交互式任务命令行版适合脚本化调用和批量任务。如果你后面要接 API、做自动化优先用 CLI。4.3 登录认证安装完成后需要认证。Codex 支持两种方式交互式登录和环境变量 API Key。交互式登录codex login终端会打开浏览器授权页面登录账号后回到终端确认即可。这种方式适合个人日常使用。使用 API Key 的方式export OPENAI_API_KEY你的APIKeyWindows PowerShell 用户用$env:OPENAI_API_KEY你的APIKey不建议在命令行里直接输入 API Key容易进入 shell 历史记录。更稳妥的方式是把 Key 放在环境变量配置里或者在.codex配置目录下按官方文档设置。4.4 验证安装登录完成后先跑一个最简单的任务确认链路通了codex 用一句话介绍你自己正常情况下会返回一段说明文字。如果这一步能出结果说明安装、登录、网络链路都是通的。接下来可以配置模型。5. 接入 GPT-5.6 与自定义模型服务5.1 先理解模型 IDCodex 是一个客户端它能使用什么模型取决于你登录的账号、API Key 对应的服务商、以及服务商接口返回的模型列表。网络上讨论“Codex 接入 GPT-5.6”时通常有两种情况账号或服务商已经开放了名为gpt-5.6的模型并且这个模型在服务列表里。只是把模型 ID 填成了gpt-5.6但服务端实际没有这个模型返回the gpt-5.6-sol model is not supported这类错误。如果你的目标是接入 GPT-5.6第一步不是改配置而是确认你使用的服务商在模型列表里有没有对应 ID。打开服务商文档或调用模型列表接口查询能查到的模型才能用。模型 ID 不存在时Codex 本身没有做错任何事问题在模型名和服务端能力不匹配。5.2 修改 Codex 模型配置Codex 的配置文件在用户目录下的.codex文件夹里文件名一般是config.toml。Windows 路径是%USERPROFILE%\.codex\config.tomlmacOS / Linux 路径是~/.codex/config.toml一个基础配置示例# ~/.codex/config.toml model 你的模型ID [model_providers.自定义服务商名] name 自定义服务商名 base_url https://你的接口地址/v1 env_key 你的环境变量名 wire_api responses注意修改前先确认几件事model必须填写服务商实际支持的模型 ID不能凭空填。base_url是你服务商提供的接口地址需要以服务商文档为准。env_key是一个环境变量名Codex 会从这个环境变量里读密钥。wire_api是协议格式常用值是responses或chat取决于服务商兼容哪一种。如果接口报格式错误优先检查这一项。配置完成后在终端用-m参数指定模型跑一次codex -m 你的模型ID 写一个Python脚本读取当前目录下的所有txt文件并统计行数如果返回正常结果说明模型接入成功。5.3 报错model is not supported如果你填写的模型 ID 不被服务端支持会看到类似这样的报错the gpt-5.6-sol model is not supported when using codex with a ...排查顺序去服务商文档、API 控制台或模型列表接口确认模型 ID 的大小写和全名。如果你当前账号没有该模型的访问权限需要先确认权限或额度。如果服务商确实不支持这个模型把config.toml里的model改成服务商支持的另一个模型。如果错误信息里还有后半段提示通常和wire_api协议不匹配有关改成服务商要求的协议格式。5.4 接入 OpenAI 兼容服务很多团队会把 Codex 接在 OpenAI 兼容的模型服务上用来控制成本或满足不同项目的合规要求。配置思路和上面一样只是把base_url和model换成目标服务商的值。以常见的兼容服务为例配置模板如下model deepseek-chat [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat再次强调不同服务商对wire_api支持不一样有的支持responses有的只支持chat有的需要自定义路径。接不通时不要急着改模型先确认协议格式对不对。如果配置了多个服务商建议用环境变量区分不要把密钥直接写进config.toml。否则文件一旦泄露密钥就跟着暴露了。6. 功能测试与效果验证6.1 测试一简单代码生成先建一个测试目录进入目录后执行mkdir codex-test cd codex-test然后给 Codex 一个明确的代码生成任务codex 创建一个Python脚本接收一个包含数字的列表返回去重后的升序列表并输出为json文件预期结果Codex 会创建一个.py文件文件里包含函数定义和主逻辑可以执行。验证方式python 生成的脚本名.py如果脚本正常输出 JSON 文件说明基础生成能力没问题。如果 Codex 只返回了代码文本但没有写文件检查当前目录权限或直接用codex exec指定写文件。6.2 测试二仓库级修改Codex 的优势是能读仓库内容。在测试目录里放一个简单的README.md内容随意。然后执行codex 给README.md补充项目简介和安装说明并保持原来的标题结构预期结果Codex 会打开 README.md新增内容再调用 Git diff 或直接写文件。判断是否成功的标准文件内容确实被修改。原来的标题层级没有被破坏。新增内容贴合项目上下文而不是通用套话。这个测试能看出 Codex 是否真的在“理解仓库”而不只是根据提示词输出文本。6.3 测试三Codex Skill 扩展Codex 支持 Skills 机制把重复性操作固化成技能之后按名字调用。先在用户目录下建 skill~/.codex/skills/csv-report/ └── SKILL.mdSKILL.md内容示例--- name: csv-report description: 读取指定目录下的CSV文件按第一列合并行输出汇总报告。 --- 当用户要求生成CSV报告时 1. 扫描目标目录下的所有CSV文件。 2. 按第一列合并相同行。 3. 将结果写入 report.csv。然后在任意项目目录执行codex 用csv-report技能处理当前目录的data文件夹预期结果Codex 先识别csv-report技能再按技能步骤执行而不是即兴发挥。Skills 适合团队固化流程。如果你们团队有固定的代码风格或代码审查清单可以做成 skill每次执行时让 Codex 自动遵守。6.4 测试四非交互式执行Codex 支持非交互模式可以在脚本里调用codex exec 把src/utils.py里的TODO注释整理成issues.md非交互模式返回结果后自动退出适合批量任务和 CI 集成。如果任务涉及修改文件具体是否追加写文件的参数以你本机codex exec --help显示的选项为准。7. 接口调用与批量任务先说清楚一个容易混淆的点Codex CLI 本身不是 HTTP API 服务。它是个终端客户端适合在脚本里通过命令行调用。如果你想对外提供 REST API让网页或 App 调用 Codex 能力需要自己做一层服务封装底层调用 OpenAI 官方 API或者调用你服务商提供的 OpenAI 兼容接口。对于批量任务更常见的方式是写一个 Python 或 shell 脚本循环调用codex exec。下面是一个 Python 调度示例import subprocess import time tasks [ 将src/utils.py中的TODO注释整理成issues.md, 给tests/test_auth.py补充三个边界测试用例, 检查docker-compose.yml并补充healthcheck配置, ] for i, task in enumerate(tasks, 1): print(f[{i}/{len(tasks)}] start: {task}) result subprocess.run( [codex, exec, task], capture_outputTrue, textTrue, timeout300, ) print(returncode:, result.returncode) print(stdout tail:, result.stdout[-500:]) if result.returncode ! 0: with open(fcodex_error_{i}.log, w) as f: f.write(result.stderr) time.sleep(2)批量任务要注意几点每个任务尽量聚焦别让一个任务里塞十几个要求。加超时避免某个任务卡死在模型生成上。记录 returncode 和 stderr失败任务单独落日志。连续调用之间加间隔避免触发服务端频率限制。如果你需要更细粒度的接口调用控制比如自定义温度、限制输出 token、控制上下文窗口建议直接用目标服务商的 API SDK而不是通过codex exec包一层。Codex CLI 适合“完成任务”API 适合“精细控制”。8. 资源占用与性能观察Codex 是云端模型本地没有显存压力所以不用像本地大模型那样纠结显卡。部署 Codex 之后本地主要观察三个指标CPUCodex 在解析仓库、调用 Git 命令、处理输出时会短暂占用 CPU但不会长期满载。内存小项目通常占用很低如果打开大型仓库、一次性读入多个文件内存会上升。网络任务过程中会持续与服务端通信网络抖动会表现为长时间无响应。观察方式Windows 打开任务管理器找codex或node进程。macOS 打开活动监视器按 CPU 和内存排序。Linux 用top或htop查看。“推理速度”主要体现在返回首段结果的时间上这个时间取决于网络状态和服务端负载不是本地 CPU 决定的。所以 Codex 不是“跑在你自己显卡上的模型”不要用本地模型的显存标准来评价它。成本方面Codex 按 token 消耗计费模型越强、任务越长消耗越高。控制成本的方法是一次只处理一个小任务避免在超大上下文里来回分析。先让 Codex 输出执行计划确认无误后再让它继续执行。给非交互任务加明确的输出范围别让它没完没了地“优化”。在账号后台或服务商控制台定期看 token 消耗趋势。9. 常见问题与排查方法问题现象可能原因排查方式解决方案codex命令找不到npm 全局目录不在 PATH 中或安装失败执行npm root -g、npm prefix -g查看路径把 bin 目录加入 PATH重新打开终端npm 安装报权限错误全局安装目录无写权限查看错误日志确认是否 EACCES用管理员终端安装或配置 npm 全局前缀到用户目录codex login无法完成账号未注册、授权窗口未打开、网络策略限制查看终端输出换浏览器重新授权改用OPENAI_API_KEY环境变量方式cc switch local proxy failed while handling codex endpoint /responses本地代理或 API 转发工具未启动、端口配置不匹配、代理端点不支持响应流式处理检查本地代理进程和端口确认 Codex 使用的基础地址和端点修正代理配置或关闭相关本地代理后重试检查代理服务日志the gpt-5.6-sol model is not supported填写的模型 ID 不在服务商支持列表中查服务商文档或模型列表接口把model改成服务商支持的 ID或升级服务权限执行任务时长时间无响应网络波动、模型生成过长、仓库上下文过大查看终端日志观察网络连接拆分子任务设置timeout小仓库先测试命令执行被拒绝沙箱审批策略限制查看审批提示和codex帮助里的审批参数按需调整审批策略默认保持限制更安全输出内容不完整上下文过长、任务描述含糊精简任务描述拆成多个步骤分步执行先让 Codex 给计划再执行修改文件后内容不符合预期项目规则未配置Codex 缺少上下文在项目根目录写AGENTS.md明确规则完善项目说明重新执行任务批量任务中途失败单个任务耗时过长触发频率限制查看codex_error_*.log增加调用间隔任务粒度改小失败任务单独重试本地代理或 API 转发类工具报错时重点检查“代理进程是否在运行”“Codex 请求的基础地址是否指向代理”“代理日志里目标端点是否报错”。这里说的代理是正常的调试工具、公司网络代理或 API 网关目的是排查流量转发和端点可达性问题不要用来绕过网络限制也不要在生产环境随意开全局代理。一个额外的常见坑是改了config.toml后 Codex 不生效。这是因为 Codex 不会每次自动热加载配置可能需要在终端重新打开会话或重启桌面端。改完配置后最好重启一次进程再测试。10. 最佳实践与使用建议Codex 这类 Agent 工具用得好不好不取决于模型参数而取决于任务拆分和项目边界。下面几条建议可以直接照做。第一每个项目单独建目录。Codex 会自动读取工作目录下的文件生成上下文如果它在整个用户主目录下运行很容易抓到一堆无关文件导致上下文混乱还增加 token 消耗。第二给项目根目录写一个AGENTS.md把团队规则说清楚。示例# AGENTS.md - 所有回复默认使用中文代码注释使用英文。 - 提交信息使用英文格式为type(scope): subject。 - 不要修改 tests 目录之外的外部依赖文件。 - 修改代码前先列出影响文件再执行修改。这样每次任务开始时Codex 会自动读取并遵守这些规则。第三第一次跑任务时不要直接开全自动审批。先观察它生成的命令是否合理确认没有危险操作后再放开。尤其是npm install、pip install、git push这类命令手动确认更安全。第四API Key 不要写进代码仓库和明文配置。用环境变量管理并在账户后台设置额度上限。一旦 Key 泄露及时吊销重建。第五批量任务一定要加日志和失败重试。Codex 可以帮你生成一堆代码但它自己不会报告“我失败了多少次”需要你在外层脚本里统计 returncode、记录 stderr、对失败任务单独重试。第六涉及版权素材、公司内部代码、个人隐私信息时先确认授权再让 Codex 处理。工具本身不会判断你有没有权限责任在使用者。11. 总结与下一步Codex 最值得尝试的点是它能把“改代码”这件事从网页聊天框转移到真实项目目录里让模型直接读文件、写文件、跑命令。对开发者来说这是比“生成一段代码”实用得多的能力。第一步建议先验证三件事能否正常安装并登录。能否通过config.toml接入希望使用的模型。能否在一个小仓库里完成“读文件 - 改文件 - 生成提交”的完整流程。最容易踩的坑是模型 ID 写错、密钥配错、本地代理或转发工具没启动。这些问题都不难排查按第 9 节的表格逐项对照即可。后续扩展方向可以考虑把 Codex 接进 CI 做自动化代码审查用 Skills 固化团队开发规范或者用codex exec做批量文件整理。首次动手时建议先在一个几 MB 的小仓库里跑通再决定要不要把 Codex 接进日常开发流程。