Codex Agent 实战：从安装配置到 GPT-6 Astra 的智能体化演进

上周我参加了一场技术面试，面试官第一个问题就把我问住了：“你平时用 Codex 做 code review 吗？还是只拿它写点单文件脚本？”我愣了一下。在那之前，我对 Codex 的理解确实停留在“能用自然语言生成代码的智能助手”这个层面。真正让我意识到差距的，是他紧接着抛出的第二个问题：“那 GPT-6 Astra 发布之后，你觉得 Codex 会往哪个方向走？”我当时的表情大概就是“还有这种事”。面试结束后，我花了整整一个周末重新折腾 Codex，从安装、配置、接入第三方模型到排查各种报错，顺便把 GPT-6 Astra 的发布说明和社区讨论也过了一遍。这篇文章就是那次“被面试官教育”之后，我沉淀下来的完整笔记。

先说结论：Codex 早已不是那个帮你补全函数的小插件了，它是一个能自己打开终端、读代码、改文件、跑测试、提交 MR 的 agent 工具。而 GPT-6 Astra 发布透露出的信号，恰恰是把这种 agent 能力做成了模型的底层默认能力。下面我从面试那天的三个问题开始，把整个认知重构的过程拆开讲。

1. 面试里的三个问题，让我重新认识 Codex

1.1 Codex 不是“会写代码的聊天机器人”，是 agent

面试官当时问的是：“如果你的 Codex 在跑一个多文件重构任务，改到一半发现编译报错，它会怎么做？”我下意识回答：“它会停下来等我给下一步指令。”他笑了笑说：“那你就把它用成了高级补全工具。真正到位的用法是，它把编译报错贴进上下文，自己分析出错文件，回滚有问题的改动，换一种实现方式重新跑一遍，直到测试全部通过。”

这段对话让我意识到，我此前对 Codex 的定位完全错了。ChatGPT 网页版里的聊天式写代码，只是 Codex 最外层的形态。完整的 Codex 是一个运行在本地的 agent 程序：它通过 CLI 或桌面版启动后，拥有读取项目文件、执行命令、编辑代码、调用测试框架的权限。你丢给它一个 issue 描述，它会像一名初级工程师一样，先列出工作计划，再逐步执行，每完成一步就检查结果是否偏离目标。

这也是为什么面试官会专门问“code review”这个场景。Codex 现在能在你提交 MR 之前，自动把 diff 拉下来，对照项目规范检查问题，甚至直接给出可执行的修改建议。它承担的不是“码字”工作，而是“代码维护和工程决策”里那些重复但费神的环节。

1.2 Codex 的三种形态：CLI、桌面版、网页版

重新上手 Codex 时，我先把它的形态梳理了一遍。现在 Codex 其实有三种使用入口：

第一种是网页版，也就是 ChatGPT 里的 Agent 模式。这种模式下 Codex 运行在云端沙箱里，适合快速验证想法，不需要本地环境。但它有个明显的局限——你无法把它直接接到你本地未提交的代码上，也不能访问公司内网服务。

第二种是 CLI，也就是codex命令行工具。它通过 OpenAI 账号或 API Key 登录，在你指定的项目目录里运行。这种形态最灵活，适合和编辑器、脚本、CI 流程集成。我后来接入 DeepSeek，用的就是 CLI 的配置方式。

第三种是桌面版，目前提供 Windows 和 macOS 客户端，本质上是给 CLI 包了一层图形界面。桌面版最大的优点是能可视化展示 agent 的思考过程，比如它看了哪些文件、执行了哪些命令、为什么回退改动。对新手来说，桌面版是理解 Codex 工作方式的最佳入口。

简单说，网页版给不了权限，CLI 给不了可视化，桌面版是两者之间的平衡点。我现在的工作流是：日常开发用 VS Code 里的 Codex 插件接 CLI，跑完整任务时切到桌面版观察执行过程。

1.3 面试官真正想考察的，是我有没有跟上 agent 工具的使用范式

后来复盘我才想明白，那场面试里技术题占的比重反而没那么大，面试官更在意的是我对“AI 编码工具到底应该怎么用”有没有成体系的认知。他说了一句让我印象很深的话：“现在招人，不能只看你会不会写 prompt，还得看你会不会给 agent 立规矩。”

这句话点醒了我。像 Codex 这种 agent 工具，默认行为是“给你完成”，而不是“问你怎么办”。如果项目里没有清晰的规范和约束，它就会按自己理解来写代码。所以真正用好 Codex 的人，会花大量时间维护两份文件：一份是项目级 AGENTS.md，告诉 agent 这个项目的背景、技术栈、编码规范、禁区；另一份是 skills 集合，把高频任务拆成可复用的标准操作流程。这个思路，恰好也是 GPT-6 Astra 发布说明里反复强调的东西，我在第 4 节细说。

2. 从安装到接入模型：Codex 上手路线还原

2.1 安装两条路：npm 安装和桌面版安装包

被面试官刺激完之后，我第一步是把 Codex 干净地装一遍。目前官方推荐的方式还是通过 npm 安装 CLI：

npm install -g @openai/codex

装完之后确认版本：

codex --version

如果 npm 装不上，常见原因是本机 Node 版本太老。Codex 要求 Node.js 18 以上，建议直接上 20 LTS。这里有一个我踩过的坑：如果你之前装过旧版本，直接覆盖安装可能残留旧配置，最好先把全局包卸干净再装：

npm uninstall -g @openai/codex npm cache clean --force npm install -g @openai/codex

桌面版就简单多了，去 OpenAI 官网下载对应系统的安装包，双击安装就行。Windows 用户注意，安装路径不要带中文或空格，否则后续跑 agent 时可能出现文件路径解析问题。这个坑我在一台工作电脑上遇到过，折腾了半天才发现是路径问题。

2.2 用 cc-switch 管理多个模型服务商

装完 Codex 之后，很多人会遇到一个问题：Codex 默认只走 OpenAI 自己的模型，但国内开发者的实际情况是，手头可能有 OpenAI 的 Key，也可能有 DeepSeek、通义之类的第三方模型 API。每个平台的 Key、Base URL、模型名都不一样，手动改配置非常痛苦。

这时候社区里流行的做法是用 cc-switch 这个 GUI 工具。它本质上是一个配置切换器，可以把不同模型服务商的接入信息统一管理，一键切换，切换时会自动重写 Codex 的配置文件，并重启 Codex 运行时依赖的本地服务。很多群友反馈“cc switch local proxy failed while handling codex endpoint /responses”这类报错，大多发生在切换服务商的过程中，也就是本地网关服务没能在配置重写后正常重启。

cc-switch 的用法很直接：

1. 下载安装 cc-switch 客户端；
2. 添加一个服务商，名称随意，关键是填对 Base URL、API Key 和模型名；
3. 保存后点击切换，让它生效；
4. 切换完成开一个新会话，用codex --version或直接codex启动验证。

需要注意的是，cc-switch 只是帮你管理配置，它不会安装 Codex。所以顺序一定是先装好 Codex CLI 或桌面版，再装 cc-switch 做配置管理。

2.3 把 Codex 接到 DeepSeek 的具体配置

现在很流行把 Codex 接到 DeepSeek 上跑，因为 DeepSeek 的 API 价格便宜，而且它提供的模型在代码能力上表现不错。我面试后实践的第一步就是打通这条链路。

Codex 的配置文件在~/.codex/config.toml。默认情况下，它长这样：

model = "gpt-5.6-sol" model_provider = "openai"

要接入 DeepSeek，我增加了一个自定义 provider：

model = "deepseek/deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY"

然后设置环境变量：

export DEEPSEEK_API_KEY=sk-你的Key

启动 Codex 时指定 provider：

codex --provider deepseek

如果你想在会话里临时切换，也可以直接：

codex --model deepseek/deepseek-reasoner

这里我必须提醒一句：Codex 的很多 agent 特性，比如自动 compact、远程任务执行、skill 调用，底层依赖 OpenAI 模型特有的工具调用格式。换成第三方模型之后，基础对话和简单代码生成没问题，但涉及到多步工具调用时表现会打折扣。所以我的建议是，跑重要项目用官方模型，日常头脑风暴和轻量任务可以切到 DeepSeek 省钱。

2.4 登录、中文设置与第一次真正跑通

配置好模型之后，首次启动 Codex 需要登录。执行codex，它会提示你打开浏览器完成授权。这里有一个高频问题：输入手机号验证时收不到验证码。我遇到的场景是，验证码短信延迟很严重，有时候等了好几分钟才到。解决办法是耐心等待，不要反复点击发送，否则会触发频率限制。

中文设置这块没有官方开关。Codex 的界面虽然是英文，但它完全能理解中文指令，还能用中文回复。我更推荐的做法，是在项目根目录写一个 AGENTS.md，用中文描述项目规范和沟通偏好。比如：

# 项目背景 这是一个面向企业客户的订单管理系统，后端使用 Python FastAPI。 # 语言要求 和用户交流时使用中文，代码注释使用中文，但变量名和函数名必须保持英文。 # 编码规范 - 所有接口都要有统一响应格式 - 不允许在服务层直接操作数据库 # 禁区 - 不要修改数据库表结构 - 不要引入重量级第三方框架

第一次跑通时，我建议从一个极小的任务开始，比如“帮我在项目根目录创建一个 README.md，概括项目用途”。这样能最快验证链路是否通，而不是一上来就丢一个复杂重构，结果排查半天不知道问题出在模型还是配置上。

3. 高频报错排查实录：面试后我把这些坑都踩了一遍

3.1 常见报错速查表

重新折腾 Codex 的这几天，我把社区里讨论最集中的几个报错都亲身体验了一遍，整理成一张速查表，先给大家一个全局：

下面挑几个重点展开说。

3.2 “模型不支持”与账号权限的关系

有一个报错是几乎所有 ChatGPT 账号用户都会遇到的：

the 'gpt-5.6-sol' model is not supported when using codex with a chatgpt acc

我第一次看到这个报错时，第一反应是模型名打错了。但仔细看，问题不是模型名，而是“using codex with a chatgpt acc”。Codex 在通过 ChatGPT 账号授权时，会默认路由到一款内部推理模型，代号就是gpt-5.6-sol。如果你的订阅套餐不包含对这款模型的调用权限，或者账号所在的网络出口不支持对应的模型路由，就会报这个“not supported”。

排查思路分三步走：先到 ChatGPT 设置页确认当前订阅是否有 Codex 使用权限；再确认登录 Codex 用的是不是被授权的账号；最后如果还不行，直接改用 API Key 方式登录，因为 API Key 走的是另一套权限模型，通常能绕开会话账号的这些限制。我这个报错最终就是通过切到 API Key 解决的。

3.3 Codex 一直重新连接 / 连接失败怎么办

这个报错在桌面版上非常常见。表现就是任务跑到一半，界面提示“正在重新连接”，然后卡住不动。第一天晚上我遇到这个情况时，第一反应是网络问题，但检查后发现网络完全正常。

后来排查下来，问题出在 Codex 本地服务的持久连接上。桌面版启动时会在本机拉起一个后台服务，当登录态过期、系统休眠恢复、或者本地端口被占用时，这个连接就会断掉。解决办法分两种场景：

如果只是偶尔断连，重新登录一次就能恢复。如果频繁断连，需要把 Codex 的缓存登录文件清掉再重新授权。在 macOS 上是~/Library/Application Support/codex/，Windows 上是%USERPROFILE%\.codex\。删除里面和 auth、session 相关的文件，然后重启 Codex 重新登录。注意不要删config.toml，否则你辛苦配的模型服务商信息就没了。

如果连登录都提示connection failed: error sending request，那就不是 Codex 本身的问题了，而是“发请求”这一步就没有成功。重点检查本地防火墙是否拦截了 Codex 的进程，以及系统代理设置是否影响了 CLI 工具出网。把 Codex 加进允许列表，通常就能解决。

3.4 上下文塞满：remote compact task 失败

Codex 跑长任务时，上下文会被逐渐消耗。当你给它塞了太多文件内容和历史对话，它会自动执行一次“压缩”，把旧信息总结成摘要，腾出空间继续。这个机制在本地会话里表现还好，但如果你用的是远程任务模式，就可能遇到：

error running remote compact task: codex ran out of room in the model's cont...

这个报错的字面意思是，为了压缩而发起的远程任务，在模型上下文里没有足够的空间来存放压缩指令。有点像一个集装箱已经装满了，你想再往里放一台“内窥镜”去检查怎么整理，结果内窥镜本身没地方放。

解决办法其实不复杂。第一，新开会话，把当前任务的历史对话重置；第二，检查是不是在对话里贴进了太多大文件，尽量用文件路径引用代替直接粘贴；第三，在配置里调低自动压缩的触发阈值，让它更早执行压缩，不要等到快满了才动手。

3.5 cc-switch 切换后本地网关报错

最后说下 cc-switch 相关的那个报错。很多人在用 cc-switch 切换模型服务商时，会遇到：

cc switch local proxy failed while handling codex endpoint /responses

我用了一个下午复现这个问题，原因是：cc-switch 在切换配置时，会尝试重启 Codex 的本地网关服务，也就是那个把请求转发到模型服务商的本地端口。如果这个端口被其他进程占用，或者配置里的 Base URL 写错，网关服务就会启动失败，Codex 把请求发给本地端口时自然收不到响应。

排查步骤我总结为三连：

1. 检查 cc-switch 里填写的 Base URL 是否以/v1结尾，且没有多余空格；
2. 检查本地端口是否有其他程序占用，比如你先启动了一个本地服务，占用了同一个端口；
3. 切换完成后，手动查看 Codex 的配置文件，确认 provider 信息真的被重写成功了。

如果端口被占用，换一个端口，然后在配置里同步修改 BASE_URL 的端口即可。

4. 顺便搞懂 GPT-6 Astra：从 Codex 延伸出去的那层模型逻辑

4.1 为什么 Codex 要挂在 gpt-5.6-sol 这种模型上

排查完这些报错之后，我把注意力转回到面试官提到的 GPT-6 Astra 上。想要理解 Astra 的定位，得先从 Codex 底层的模型路由说起。

不知道你有没有注意到，Codex 在 ChatGPT 账号下默认使用的模型是gpt-5.6-sol，而不是我们熟悉的 GPT-5 或 GPT-4o。这说明 OpenAI 在 Codex 这条产品线上并没有走“通用模型一把梭”的路，而是专门训练了面向 agent 任务的中继模型，代号里带sol，我猜测是“solver”的缩写，强调的是任务解决能力。这类模型在普通聊天里你可能感觉不到它有多强，但一旦进入多步工具调用场景，它的规划能力和错误自愈能力会明显优于通用模型。

面试官当时给我打了个比方：通用模型像是一个知识量很大的顾问，你问什么它都能答；而sol系列模型像是那个真正坐在工位上写代码的工程师，它不追求“什么都知道”，但追求“你说的事情我能闭环执行完”。Codex 作为 agent 工具，底层必须要配这种执行型模型。

4.2 从 GPT-6 Astra 的发布看出 Agent 成了第一公民

这次面试里最大的信息增量，是 GPT-6 Astra 的发布。我赛后找了一晚上官方资料和社区讨论，才把它的定位搞清楚。OpenAI 发布 GPT-6 Astra，不仅仅是一次常规的模型版本升级，更像是把 agent 能力从“附加功能”提升到“底层架构”的宣言。

Astra 这个命名本身就很有指向性，它源自拉丁语，意为“星辰”。从发布说明和演示来看，Astra 的核心卖点不再是简单的“写得更长、答得更准”，而是把任务规划、工具调用、环境交互、错误修正这些 agent 能力做成了模型原生的默认行为。这意味着，像 Codex 这样的上层工具，以后不需要再靠外部工程手段去调度模型思考步骤，模型本身在生成 token 时就已经带有“下一步该做什么”的判断逻辑。

听上去很玄，但落到工程师日常里其实很具体。以前我用 Codex 跑一个重构任务，需要在 AGENTS.md 里用大量规则约束它“先做什么后做什么”；而 Astra 的思路是，模型自己懂得先列影响面、再改代码、再跑测试、最后收敛结果。当然这不是说项目规范文件就不需要了，而是说规范文件从“教你做事”变成了“告诉你本项目的特殊约定”，通用工程步序不再需要你操心。

4.3 “rethinking skills and prompts”到底在 re 什么

和 GPT-6 Astra 一起被热议的，还有一个话题叫“rethinking skills and prompts for GPT-6 Astra”。我最初不明白这几个词为什么要专门拿出来说。后来读了一些技术分析才恍然，传统意义上的 prompt 是“对模型的一次性指令”，它的生命周期就是一次对话。而 Astra 引入的 skill，是一套可以复用的“执行预案”。

打个比方，以前你让模型“帮我重构一个函数”，你得把重构的步骤写清楚：先定位函数、再看调用方、设计新签名、修改实现、更新调用点、跑测试。现在你把这一整套步骤封装成一个 skill，命名为safe-refactor，下次在任何项目里只要说“对 handleUserLogin 执行 safe-refactor”，Codex 就会自动加载这个 skill 里的全部步骤和约束，不需要再重复描述。

我在面试后被安利的最有价值的一件事，就是在 Codex 里使用 skills 机制。具体做法是：

1. 在~/.codex/skills/下为每个可复用技能建一个目录；
2. 在每个目录里创建一个SKILL.md，用 YAML front matter 描述技能的 name、description、when_to_use；
3. 正文部分写清楚执行步骤、质检标准、常见误区。

我自己写了一个api-migration技能，专门用来处理“把项目里的旧 REST 接口调用迁移到内部 RPC 客户端”这类重复任务。写完后，每次遇到接口迁移，只需跟 Codex 说一句“用 api-migration 处理 xxx 接口”，它就会按技能里的流程走，不再需要我反复布置任务。

4.4 面试之后，我重写的项目级 AGENTS.md

受这个思路影响，我把手上一个主力项目的 AGENTS.md 重新写了一遍。老版本写得很笼统，只是列了技术栈和一些编码规范。新版我按照“给 agent 当交接文档”的标准来设计，结构是：

# 项目概览 一句话说清楚这个系统是什么 # 技术栈 后端、前端、数据库、中间件 # 常用命令 如何启动、如何跑测试、如何构建 # 架构约定 模块分层规则、目录命名规则 # 任务处理流程 接到需求后的标准执行顺序 # 明确禁区 不允许 agent 做的事务

写完这个文件之后，Codex 的行为质量提升非常明显。以前它经常改完一处代码就停下来等指令，现在它会自动跟着任务处理流程往下走，测试挂了会自己先看日志找原因，而不是直接把报错甩给我。用行内话说，就是“把 agent 该干的活还给了 agent”。

4.5 从 prompt 到 skill 的迁移清单

最后分享一个我给自己列的迁移清单，如果你也想顺着 GPT-6 Astra 的思路整理自己的编码工具，可以参考：

1. 把高频 prompt 升级为 skill，先从一个你每个月至少做三次的任务开始；
2. 每个 skill 都要有明确的触发条件，写在 description 里，方便模型自动命中；
3. AGENTS.md 里只留项目特有信息和强约束，通用步序全部收敛进 skill；
4. 定期复盘 Codex 的执行日志，看哪些步骤它总是犯错，把这些步骤写进 skill 的“常见误区”一节；
5. 不要追求 skill 数量，先追求单个 skill 的完成度。

5. 面试之后，我工作流里的几个实际改变

5.1 从“工具思维”切换到“成员思维”

面试之后的这几周，我最大的改变是：不再把 Codex 当成一个需要我逐行指挥的工具，而是当成一个刚入职的初级工程师。我会给它写完整的项目背景文档，会在任务描述里写清楚验收标准，会告诉它哪些事绝对不能碰。它做得不对时，我不会只丢一句“这里不对”，而是会指出它漏掉了什么信息、应该优先看哪个文件。这种交互方式的调整，带来的效率提升比我换什么模型都明显。

5.2 我现在跑 Codex 的固定套路

这里总结一下我目前的固定工作流，大家可以参考：早上到工位先看一眼项目里有没有积压的 issue，把重复性的任务挑出来分配给 Codex；分配时严格遵守“背景 + 目标 + 约束 + 验收标准”四要素；Codex 执行期间自己不闲着，去干需要人类判断力的设计或联调工作；每完成一个任务，让 Codex 自己写一段改动说明，附带测试结果；每周回顾一次它的执行日志，把反复出现的错误整理进 skill。

5.3 给第一次用 Codex 的人几条实在建议

文章最后，我用踩坑换来的经验给还没上手的读者几句实在话。第一，别一上来就配第三方模型，先用官方模型跑通最小链路，理解 agent 的工作方式和上下文消耗规律；第二，项目里的 AGENTS.md 一定要认真写，这个文件的质量直接决定 Codex 干活的上限；第三，遇到报错先看配置再看网络最后才怀疑是软件坏了，我遇到过的问题，九成都是配置没写对或者端口被占用；第四，有条件的话，同时装着 CLI 和桌面版，CLI 用来跑批处理，桌面版用来观察思考过程和学习排错。把这几点做完再谈效率提升，不然你很可能只是在用一个昂贵的自动补全工具。