这次我们来看 Codex CLI 怎么用来手搓自动化脚本。很多人对 Codex 的印象还停留在聊天界面里写代码实际上它的核心价值在命令行 Agent 模式你把需求用自然语言写清楚它自己规划任务、写脚本、执行命令、读终端报错、改代码循环迭代直到跑通。这篇文章会围绕 Codex 的安装配置、模型接入以 DeepSeek 这类兼容接口为例、自动化脚本实操以及最常见的本地代理报错和鉴权报错排查展开。适合想用 Codex 做文件处理、批量任务、网页自动化、测试脚本但又不想被卡在环境配置上的人。先说几个和 Codex 相关的判断方便你快速决定要不要继续往下看。第一Codex CLI 是一个本地运行的命令行工具需要先安装 npm 包再配置模型接口不是开箱即用的 Web 页面。第二它可以接 OpenAI 官方模型也可以通过配置 base_url 接 DeepSeek、通义千问等兼容接口这解决了很多人的模型选择问题。第三Codex 的强项是能够直接在本机终端执行命令这意味着它可以真的“动手”跑脚本、看结果、改 bug而不是只给一段建议代码。第四如果你使用 ccswitch 这类本地代理工具做请求转发可能会遇到local proxy failed while handling codex endpoint /responses之类的报错这篇文章会给出一套排查思路。1. Codex 核心能力速览能力项说明项目类型命令行 AI 编程助手 / Agent 工具安装方式npm 全局安装或桌面客户端安装核心功能自然语言生成代码、执行终端命令、多轮调试脚本、批量任务编排模型支持OpenAI 官方模型以及兼容接口的自定义模型如 DeepSeek启动方式命令行交互模式、codex exec非交互模式是否支持 API支持命令行方式批量执行适合场景自动化脚本生成、批量文件处理、网页自动化、测试脚本、数据处理硬件要求不需要本地 GPU主要依赖模型接口和本机 CPU/内存常见问题鉴权失败、429 限流、本地代理转发报错、模型型号不支持从硬件门槛来看Codex 本质上是一个“本地 Agent 云端模型接口”的组合不需要特别高的显卡配置。普通笔记本、台式机都能跑关键是网络环境和模型接口的可用性。这和本地大模型部署是完全不同的思路Codex 不负责推理模型计算都在远端完成本地只负责代码生成、命令执行和文件操作。如果你是第一次接触这类工具可以先建立这样一个认知Codex CLI 不是“聊天框”而是一个能够直接操作你电脑文件系统的编程代理。它读取你的文件内容理解项目结构执行 Shell 命令然后把输出结果当作下一步决策的依据。这在自动化脚本场景下非常实用因为它能自己处理“脚本报错后修改代码再重试”这个循环而你只需要描述清楚想要什么结果。2. 适用场景与使用边界Codex 适合谁来用我认为有四种人收益最大。第一种是经常处理批量文件的人比如把上百个文本文件整理成结构化表格把图片目录批量重命名或者把日志文件按规则切分归档。第二种是做接口联调的人需要快速生成轮询脚本、失败重试脚本、数据校验脚本但又不想手写全套异常处理。第三种是测试人员可以用自然语言描述测试步骤让 Codex 生成 UI 自动化测试脚本或接口测试用例。第四种是个人开发者想把重复的日常操作脚本化比如自动备份、自动发布、自动生成周报数据。Codex 不太适合什么场景首先是需要严格保密的数据处理因为请求会发送到模型服务端代码内容、文件名、目录结构都可能成为接口请求的一部分。其次是不能接受“随机失败”的生产环境核心任务AI 生成代码即使通过了多轮调试仍然可能在边界输入上出错。最后是高度依赖领域知识的任务比如复杂的网络协议解析、底层驱动开发Codex 的上下文理解能力有限可能会生成表面正确、实际有缺陷的代码。使用边界上必须强调一点任何自动化脚本都可能作用于真实系统。批量删除文件、批量修改配置、调用第三方接口、访问内部系统都需要先确认操作范围和权限。涉及网页自动化时要遵守目标网站的访问规则和频率限制涉及测试数据时不要使用真实用户个人信息涉及版权素材时必须确认授权。用 Codex 生成的脚本第一次运行前建议先走一遍 dry-run或者在小范围样本上验证避免误操作造成不可逆的后果。3. 环境准备与前置条件在安装 Codex 之前先检查环境。Codex CLI 是基于 Node.js 的命令行工具所以首先需要确认 Node.js 版本。常见做法是安装 Node.js 18 或更高版本具体版本要求以官方文档为准。如果本机还没有 Node.js可以从官方网站下载 LTS 版本安装完成后命令行执行node -v和npm -v确认可用。操作系统方面Codex CLI 支持 Windows、macOS、Linux。这里有两个需要注意的点第一Windows 下建议在 PowerShell 或 Windows Terminal 中使用某些旧版 CMD 可能出现命令解析问题第二Codex 在执行命令时依赖终端环境如果你使用 Git Bash 或 WSL要考虑 Shell 环境差异部分脚本可能在 Linux Shell 下运行正常但在 Windows 下表现不同。还需要准备一个模型接口。你可以使用 OpenAI 官方 API Key也可以使用兼容 OpenAI 接口的第三方服务比如 DeepSeek。这里以 DeepSeek 为例说明注册 DeepSeek 开放平台创建 API Key记下接口地址。接着在系统环境变量中配置export OPENAI_API_KEYsk-你的key export OPENAI_BASE_URLhttps://api.deepseek.com注意DeepSeek 接口的模型名称通常是deepseek-chat后面配置 Codex 时需要保持一致。如果你用的是其他兼容服务base_url 和模型名称都要按实际服务商提供的参数调整。最后检查磁盘空间和网络连接。Codex 本身是一个 npm 包体积不大几百 MB 的磁盘空间足够。但这不包含模型推理资源推理在远端完成所以网络连接质量直接影响响应速度。如果你所在的网络环境需要通过本地代理访问模型接口建议先确认代理服务本身能正常工作再配置 Codex 使用。如果代理配置不正确就会出现后面要讲的local proxy failed报错。4. 安装部署与启动方式4.1 通过 npm 安装 CodexCodex CLI 的安装命令比较直接npm install -g openai/codex安装完成后执行codex --version确认版本号输出正常。如果你的 npm 镜像源比较慢可以临时切换镜像源再安装npm install -g openai/codex --registryhttps://registry.npmmirror.com安装完成后先登录或配置 API Key。如果你使用官方 OpenAI 账号codex login如果使用自定义接口更稳妥的方式是直接配置环境变量跳过登录流程。在 Windows PowerShell 下可以这样设置$env:OPENAI_API_KEY sk-你的key $env:OPENAI_BASE_URL https://api.deepseek.com这里要提醒一句环境变量配置完成后需要重启终端窗口才会生效。如果你在配置过程中遇到codex auth token is unavailable大概率就是 API Key 没有正确传入可以先用echo $env:OPENAI_API_KEY或printenv OPENAI_API_KEY检查环境变量是否存在。4.2 配置文件形式除了环境变量Codex 也支持通过配置文件指定模型。不同版本使用的配置文件名不同常见的有config.toml或codex.json具体要看安装版本的文档说明。一个大致的参考配置结构如下{ model: deepseek-chat, baseUrl: https://api.deepseek.com, apiKeyEnvVar: OPENAI_API_KEY }不同版本对配置字段的支持程度不同这里的关键是确认model字段和模型服务端实际提供的模型名一致。如果配置了服务端不存在的模型名调用时会出现类似the gpt-5.6-sol model is not supported的报错解释得很直接你指定的模型名不受支持。4.3 桌面版与 CLI 的选择材料中提到了 Codex 桌面版安装这确实是另一个入口。桌面版更适合不熟悉命令行的用户但自动化脚本场景下CLI 的优势更明显你可以直接在同一终端里操作 Codex让它执行命令观察输出反复调试。桌面版适合日常问答和代码片段生成CLI 适合真实的任务执行和脚本编排。从“手搓自动化脚本”这个目标出发本文后面的内容都基于 CLI 演示。4.4 启动交互模式配置完成后在终端输入codex进入交互模式。在这个界面里你可以用自然语言描述任务。Codex 会先展示它的计划然后开始执行命令。首次使用建议从简单任务开始比如“读取当前目录下的文件列表并写入到 files.txt 中”。这样可以在低风险场景下验证安装、鉴权和基础命令执行全部正常。5. 网络代理配置与 ccswitch 报错排查这一节是很多人实际踩坑最多的地方。搜索热词里出现了cc switch local proxy failed while handling codex endpoint /responses这个报错含义是Codex 在访问/responses端点时本地代理服务处理请求失败。出现这个问题的常见场景是你使用 ccswitch 这类本地工具做 API 转发或者通过本地代理拼接了模型接口地址但代理配置没有跟上 Codex 的请求方式。先说排查思路不建议一上来就重装 Codex。按这个顺序走第一步确定有没有使用本地代理。如果你开启了 ccswitch 或类似的请求转发工具先看它的日志输出。local proxy failed的字面意思就是代理这一层没有成功转发请求需要先确认代理工具本身能正常访问目标接口单独的 curl 测试可以通过。第二步检查代理工具的鉴权配置。Codex 请求时会携带环境变量中的 API Key如果代理工具要求单独的鉴权头或者代理配置里写死的 Key 已经失效就会导致请求失败。这个情况在材料里表现为provi截断信息实际排查时就是看代理日志中返回的 401 或 403 状态码。第三步检查 Codex 的 base_url 配置。如果你接了 DeepSeek但 base_url 写成了 OpenAI 官方地址而 DeepSeek 服务又不支持某些端点也会出现类似问题。正确做法是先直连测试一下curl https://api.deepseek.com/models \ -H Authorization: Bearer sk-你的key如果你不使用任何本地代理但仍然遇到local proxy failed报错有一种可能性是安装环境中残留了旧的代理配置比如全局环境变量中的 HTTPS_PROXY 指向了一个不存在的服务。可以检查echo $env:HTTPS_PROXY echo $env:HTTP_PROXY如果这两个变量指向了无效地址先清理它们再重试 Codex。清理后重启终端然后执行codex exec 回复ok验证连通性。最后如果以上都没有问题可以试试把 Codex 的请求路径从默认接口切到兼容的 chat completions 端点。部分第三方服务不完全兼容/responses端点但兼容 OpenAI 传统的/v1/chat/completions。Codex 的配置文件里如果有endpoint或apiStyle相关选项可以尝试切换。具体字段名以你安装的版本文档为准。6. 用 Codex 手搓自动化脚本的完整流程接下来进入正题怎么用 Codex 写一个能真实跑起来的自动化脚本。我们不只让它“写出代码”而是让它“把脚本跑通”。这个过程包含四个阶段任务描述、生成脚本、执行与报错反馈、结果验证。6.1 任务描述Codex 能不能写好脚本很大程度取决于你把任务描述得多清楚。举一个例子让 Codex 写一个批量处理 CSV 的 Python 脚本。在 Codex 交互模式中输入写一个 Python 脚本读取当前目录下 data 文件夹中所有 CSV 文件。 每个 CSV 文件包含两列name 和 value。 要求 1. 按 value 列排序。 2. 过滤掉 value 小于 10 的行。 3. 输出为一个合并后的 merged.csv要求第一行为表头。 4. 脚本要兼容 windows 和 macos路径使用相对路径。 5. 运行前先列出文件列表确认后再执行。这里的关键不是“让它生成代码”而是明确输入、处理规则、输出格式、兼容性要求和执行策略。Codex 会根据这些约束生成一个完整的脚本你不需要做到每一步都描述精确但必须给出判断标准否则它生成的脚本可能只实现了部分逻辑。6.2 生成与执行Codex 会先写代码然后询问是否执行。在非交互模式codex exec中它会自动执行命令。在交互模式中你可以选择确认执行。示范命令codex exec --full-auto 用 python 写一个脚本把当前目录下所有 .txt 文件中的空行删除输出到 cleaned 目录要求保留文件名不变--full-auto意味着 Codex 可以自行执行命令而不需要逐条确认。这个参数适合明确、低风险的批量操作。首次使用建议不要加这个参数让它每一步都征求你的同意避免它执行意外的命令。生成代码后Codex 会在终端直接运行。如果脚本报错Codex 会读取错误输出然后修改代码重新运行。这个自迭代过程是“手搓自动化脚本”的核心体验。它不像编辑器里给你一段代码那么“静态”而是像有一个初级开发者在你的电脑上做事你只需在关键节点确认方向。6.3 观察执行过程执行过程中要重点看几个地方Codex 是否创建了不相关的文件、是否有超出任务范围的命令、输出结果是否符合预期。如果你发现 Codex 偏离方向可以立即输入 “stop” 或按 CtrlC 中断然后在对话中纠正。这点很重要AI Agent 并不是每次都能准确理解你的意图尤其是任务描述存在歧义时。仍以上面的 CSV 任务为例Codex 可能的执行流程是打印当前目录结构。检查 data 文件夹是否存在。写一个 Python 文件比如merge_csv.py。运行该脚本。查看输出确认 merged.csv 生成。读取 merged.csv 的前几行验证排序和过滤逻辑。你可以看到一套完整的工程化闭环读取上下文 - 生成文件 - 执行 - 验证结果。这就是 Codex 比普通代码生成工具强的地方。6.4 非交互批量场景一旦你的脚本写好了后续的重复操作就可以脱离 Codex 交互界面直接用命令行执行 Python 脚本或 Shell 脚本。Codex 生成的脚本本质上就是普通脚本不依赖 Codex 运行时。例如生成一个 Python 脚本后你可以直接运行python merge_csv.py这意味着 Codex 的价值不只是“帮你写脚本”还在于“帮你把脚本调到能跑的状态”。最后留下的是一个标准化的、可重复执行的产物。7. 接口调用与自动化业务流转自动化脚本如果只停留在“本地跑一次”价值有限。更实用的方式是把它接到业务流转中变成可重复的批量任务。这里分三个层次讲。7.1 脚本本身提供接口如果你用 Codex 写的是数据处理脚本可以通过简单的 HTTP 接口暴露给其他系统调用。一个最小 Python 示例from flask import Flask, request, jsonify import subprocess app Flask(__name__) app.route(/run_batch, methods[POST]) def run_batch(): task request.json.get(task) result subprocess.run([python, process.py, task], capture_outputTrue, textTrue) return jsonify({stdout: result.stdout, stderr: result.stderr}) if __name__ __main__: app.run(host127.0.0.1, port8000)这种模式适合把 Codex 生成的脚本包装成内部工具供多个团队调用。部署时要注意限制访问范围不要随意绑定 0.0.0.0避免未授权调用。7.2 命令行批量调度更轻量的方式是用 Shell 脚本或任务计划程序调度。比如在 Windows 下有任务计划程序在 Linux/macOS 下有 cron。Codex 生成的脚本放在固定目录每次任务计划触发时执行输出日志写到一个统一的文件中python batch_task.py logs/batch_$(date \%Y\%m\%d).log 21这种模式下自动化脚本变成了一个可以长期运行的“批处理服务”。关键是要加入日志和错误捕获不然脚本静默失败时你完全不知道。7.3 把 Codex 嵌入更大的自动化流程Codex 本身也可以作为批量任务生成器使用。举例来说你需要为 20 个不同的目录编写处理脚本可以循环调用codex exec为每个目录生成对应脚本这就是接口层面的“批量任务”。for dir in data_01 data_02 data_03; do codex exec --full-auto 为目录 $dir 写一个 Python 脚本读取其中的 .json 文件并汇总为 summary.csv脚本保存到 scripts/process_$dir.py done这种用法的优势在于每个脚本针对具体目录定制化生成比手写模板效率高很多。但需要注意的是批量调用时要注意限流。Codex 接口在高峰期可能出现 429 限流表现为exceeded retry limit, last status: 429 too many requests。解决办法是增加请求间隔控制并发度不建议几十个任务同时跑。8. 资源占用与性能观察Codex 是远端推理模型本地不做大规模计算所以资源占用主要体现在三个方面终端进程内存、脚本执行时的 CPU 消耗、以及长时间运行时产生的日志文件。安装完成后codex进程的内存占用通常在几百 MB 范围内这个数值会因为终端版本和 Node.js 版本有所变化不必过于敏感。真正吃资源的是你让它执行的脚本本身。如果脚本涉及大量文件读取或网络请求本机 CPU 和网络带宽会成为瓶颈。性能观察上有几个建议。第一监控 API 响应时间如果感觉到 Codex 回复明显变慢先检查网络再检查是否触发了限流。第二批量任务建议先试跑一个样本确认逻辑正确后再全量执行避免错误逻辑被放大到全部数据。第三长时间循环运行时注意系统临时目录里的中间文件Codex 生成的脚本如果用了临时文件但没有清理几十个任务跑完可能会浪费数 GB 磁盘空间。还有一个容易被忽略的点Codex 的上下文长度是有限的。如果项目文件特别多或者日志文件有几万行Codex 可能无法完整读取。这时要主动缩小任务范围比如先让 Codex 只处理单个文件验证通过后再扩展到批量。9. 常见问题与排查方法这一节整理从搜索热词中提炼的高频问题统一做成排查表格。这些问题不一定每一种你都会遇到但出现时按表格里的方向排查基本能定位到原因。问题现象可能原因排查方式解决方案codex auth token is unavailable未配置 API Key或环境变量未生效执行printenv OPENAI_API_KEY检查变量设置 OPENAI_API_KEY 后重启终端ccswitch local proxy failed while handling codex endpoint /responses本地代理转发异常目标接口不兼容 /responses 端点查看 ccswitch 日志离线 curl 测试目标接口检查代理鉴权配置切换兼容的请求端点exceeded retry limit, last status: 429 too many requests请求频率过高触发限流查看调用时间间隔降低并发增加 sleep 等待时间the gpt-5.6-sol model is not supported配置文件中模型名不正确/服务端不支持对比模型服务商文档中的模型名修改 model 字段为实际支持的模型名codex 打不开 / 页面无响应安装不完整、登录态失效检查codex --version重新安装 npm 包或重新登录codex 安装后找不到命令npm 全局 bin 目录不在 PATH 中执行npm bin -g检查 PATH将 npm 全局目录加入 PATH中国网络环境下无法访问官方接口网络连接受限检查接口连通性确认 base_url 配置使用兼容接口服务如 DeepSeek配置 base_urlCodex 生成的脚本跑到一半停止脚本命令等待输入、磁盘不足、权限不足查看脚本输出日志给足参数、清理磁盘、调整执行权限有一点值得说明429 too many requests问题在网络环境中经常被误判为“账号被封”或“代理失效”实际上就是频率限制。遇到这个错误最直接的解决方式是停掉当前批量任务等几十秒后再继续。如果需要频繁调用可以在脚本里加入指数退避逻辑让每次失败后等待时间递增。关于“codex 手机号验证”的问题这在官方账号登录流程中可能出现属于账号开通流程的一部分使用过程中如果遇到按官方提示完成验证即可。如果你通过环境变量配置 API Key 而不是codex login一般不会进入手机号验证环节。10. 最佳实践与使用建议用 Codex 手搓自动化脚本最重要的工程化习惯可以总结为下面几点。10.1 从小样本开始不要一开始就让 Codex 处理整个数据集。先说“只处理前 5 个文件”验证脚本逻辑正确再手动修改命令扩大到全量。小样本测试能快速暴露问题避免浪费接口请求次数和时间。10.2 规范化目录管理建议按照scripts/、inputs/、outputs/、logs/的规范管理目录。Codex 生成的脚本统一放在 scripts 目录输入数据放在 inputs 目录所有输出写入 outputs 目录日志写入 logs 目录。这样即使脚本出现问题也能快速定位影响范围。project/ ├── scripts/ ├── inputs/ ├── outputs/ └── logs/10.3 验证输出正确性Codex 跑通不等于结果正确。每个自动化脚本都应该有一个“验证步骤”。比如 CSV 处理脚本执行完后单独写一条命令统计输出行数、检查关键字段非空、抽样查看几个记录。只有验证通过的脚本才能进入正式批量任务。10.4 关注合规与安全自动化和脚本化意味着你的本机操作可以被程序化执行权限和范围控制比手动操作要求更高不要在脚本中硬编码密钥优先从环境变量读取。涉网页自动化时控制请求频率遵守目标站点的 robots 和服务条款。处理真实数据或个人信息时先在脱敏样本上测试。脚本运行前做一次查看确认没有删除、覆盖之外的意外操作。涉及人脸、声音、版权素材时确保已获得授权。10.5 批量任务要具备可观测性批量任务不是把命令跑完就结束而是要能看到每一条任务的状态。建议统一输出日志记录任务开始时间、结束时间、成功失败状态、错误信息。后续排查时能直接从日志定位是哪一条数据处理失败而不是重新跑一遍全量任务。11. 总结与下一步Codex 最值得尝试的点是它的 Agent 闭环能力生成脚本、执行命令、读取报错、修改代码、重试验证。这套流程让自动化脚本的开发方式从“手写-调试-再手写”变成了“描述-验证-修正”。先说结论如果你是做数据处理、批量任务、测试脚本或日常自动化的人Codex CLI 值得投入一两个小时安装配置然后用一个小任务验证效果。最先应该验证的功能是用codex exec --full-auto跑一个最简单的文件处理任务比如把当前目录下的文件名列表输出到一个文本文件。这一步能同时验证安装、鉴权、命令执行三个核心环节。最容易踩的坑是 API Key 配置后没有重启终端导致鉴权失败以及本地代理配置和 Codex 请求端点不兼容造成的local proxy failed。先绕过这两个坑后面的体验会顺畅很多。后续可以继续扩展的方向有三个一是把 Codex 生成的脚本包装成内部 HTTP 接口提供给团队其他人使用二是把多个脚本组合成完整的数据流水线用任务计划程序定时触发三是将 Codex 作为批量脚本生成器对多个目录、多个项目分别定制化产出代码再配合人工 review。每一步都可以在本地小成本验证建议收藏备用下次需要写批量处理脚本时直接照这篇文章的流程走一遍。
