最近把主力模型切到 GPT-5.4 之后，我发现很多人的用法还停留在“把文档丢进去，让它概括重点”这个阶段。真正让这个版本拉开差距的，是 1M 上下文和 Codex 环境的组合：前者让模型一次读完整套项目源码，后者让模型联网搜索、执行命令、修改文件、跑测试。当这两个能力再加上多 Agents 配置，你实际拥有的不是一个聊天框，而是一个能读全仓库、会查最新资料、能上手改代码的小团队。
这篇文章把我从零开始配置 GPT-5.4 的全过程写出来，包括 1M 上下文怎么确认生效、Codex 联网搜索怎么开、多 Agents 怎么分工协作、配置过程中踩过哪些坑。如果你也在用 Codex，或者经常需要模型处理几万字以上的代码和文档，这篇文章里的配置可以直接抄，不一定保证最优，但至少能让你少走两三天的弯路。
1. 1M 上下文到底能装下什么，又该怎么理解它
1.1 1M token 是个什么概念：从“聊天”到“读整库”
先说一个最直观的数字：1M token 大约相当于几十万到一百万字的中文内容，具体取决于 token 切分方式，但不管怎么算，这都已经不是“长文档”的级别，而是“整个代码仓库”的级别。以前我们聊 128k 上下文，觉得能塞下几百页 PDF 已经很了不起了；到了 1M，你完全可以把自己的项目源码、依赖说明、数据库表结构、接口文档一次性丢进去，让模型自己在里面找关系。
我实际测试的场景是一个内部工具项目：整个仓库算上注释和配置文件，大约四千多行，分布在二十多个文件里，压缩成纯文本大概二十万字。以前用旧模型的 128k 窗口，必须拆成几段喂，拆完以后模型对代码之间的调用关系理解得很差，经常答非所问。换到 GPT-5.4 的 1M 上下文后，我直接把整个仓库路径交给 Codex，让它先完整扫一遍再回答问题，它能准确说出某个函数在哪个文件里被调用、某个配置项影响了哪条链路。这不是“更聪明”了，而是输入信息完整了，模型的推理才有底气。
那 1M 上下文适合谁来用？我个人的判断是：如果你平时只写几百行的小脚本，开不开 1M 影响不大；但只要你维护中型项目、研究长文档、分析多个模块之间的数据流，1M 是真的能改变工作方式的。它最大的价值不是“能读更多”，而是“不需要你提前裁剪”。
1.2 1M 上下文不是万能保险箱：数学代价与“中间遗忘”
但因为 1M 很大，很多人会产生一个错觉：把所有东西都塞进去就万事大吉。这里必须先泼一盆冷水。上下文窗口和模型的注意力机制是绑在一起的，理论上窗口越大，每一轮请求需要处理的中间计算量也越大，响应时间会变长。我在实际使用里观察过，同一个问题，用 128k 上下文可能几秒就返回，切到 1M 后变成二三十秒，这是正常的，不是配置出了问题。
更大的坑是“中间遗忘”现象。说白了，模型对长文本开头和结尾的内容记忆更清楚，对埋在中间的内容关注度会下降。这听起来反直觉，但如果你把一条关键需求写在二十万字文档的正中间，最后模型可能真的没看到。所以开 1M 不等于可以乱塞材料，你需要做的恰恰是主动控制信息的排布。
我的做法是分级管理：把最重要的约束条件放在会话开头或缩成一个独立的 REQUIREMENTS 文件；把大块参考资料放到中间区域，让模型按需读取；结尾再放一份“产出要求清单”。这样 1M 窗口内信息的“显眼程度”被重新分配，比一股脑全塞进去靠谱得多。
1.3 在 Codex 里确认 1M 上下文是否真的生效
很多人配置完之后不确定自己到底有没有用上 1M，这里我给出两个判断方式。
第一个方式是看配置。如果你走的是 Codex 图形界面，新建会话时会有模型版本和上下文长度的下拉选项，选到 GPT-5.4 之后，再确认上下文长度那一栏显示的是 1M 而不是默认的 128k。有些版本的客户端默认不显示这个选项，需要在设置里打开“高级上下文配置”。
第二个方式是直接做一次长文本复述测试。找一份三十万字以上的文本喂进去，然后问模型“刚才第 46 页第三段的最后一句话是什么”。如果它答得上来，说明上下文完整覆盖了；如果它只是泛泛地编了一句，说明实际生效的上下文长度可能不够，或者模型已经产生了中间遗忘。我用这个方法验证过几次，基本能判断当前环境到底开没开 1M。
提示：CLI 或 API 方式下，有些默认参数会覆盖全局配置。比如某些 Codex 版本会在请求里自动追加 max_tokens 限制，导致上下文虽然支持 1M，但单次回复最多只回几千字。这种情况不算上下文配置失败，但会影响实际体验，需要注意区分。
2. Codex 联网搜索的开启步骤与两种配置路径
2.1 Codex 环境准备：终端与账户前置条件
Codex 不是网页聊天框，它是一个偏工程化的代理环境。它天然能读取文件目录、执行终端命令、修改代码，并支持把模型连接到外部工具。因此，想开联网搜索，第一步不是找“联网”按钮，而是先把 Codex 这个环境跑起来。
我这边的基础准备工作有三项：一是安装 Codex 命令行工具，这一步不同版本有不同安装方式，建议直接看当前工具版本的官方 README；二是确认本地网络出口通畅，因为联网搜索本质上是由模型调用搜索接口，需要能正常访问外部 HTTPS 接口；三是准备好认证配置，也就是把你的访问令牌填进环境变量或配置文件。
这里另说一句很多人忽略的：Codex 终端本身的登录凭据，和模型能力所需的凭据权限，可能是两套体系。我遇到过一次工具能上线但联网搜索一直被禁的情况，排查之后发现是账户角色里没勾选“联网工具”权限。所以配置联网搜索之前，先确认账户权限里真的有这一项，不然界面按钮都找不到。
2.2 界面开启联网搜索：五分钟上手
如果你用的是带界面的 Codex 客户端，开启联网搜索会直观很多。我的操作路径是：新建会话，选择模型 GPT-5.4，然后在会话输入框附近找到工具能力面板，里面会列出代码执行、文件读取、联网搜索等能力项。把“联网搜索”这个开关打开，再开始提问。
开启之后怎么验证它真的联网了？我建议问一个明确需要最新信息的问题，比如“某个框架当前最新的稳定版本号是多少，发布时间是什么时候”。如果模型能返回带引用来源的回答，并且来源指向外部网页，那说明联网已经生效；如果它说“我的知识截止到某日期”，但回答里没有引用链接，那就是搜索工具没有真正被调用。
界面开启的好处是直观，但坏处是每次新建会话都要重新确认开关状态。很多新手就是在这里栽跟头：第一次会话明明开了联网，第二次新建的时候忘记点开，然后抱怨“怎么又不联网了”。如果你也需要长期使用，建议看下面这种 CLI 或 API 的配置方式，一劳永逸。
2.3 API/CLI 方式接入联网搜索：带参数说明
在编程环境里，我更喜欢用 CLI 和 API 方式，因为参数可以写进配置文件，整个团队能共用一套标准。
CLI 方式下，启动 Codex 时可以在启动参数里声明需要启用的工具列表。因为不同版本的工具命名有差异，我这里给的是通用示意写法：
codex --model gpt-5.4 --context-window 1M --tools web_search,file_read,command_exec注意--tools后面列出的内容必须是当前版本支持的合法工具名。如果工具名不对，启动可能不报错，但联网搜索不会生效。建议先跑一句codex --help或查看配置文件模板，确认实际的工具名再填入。
API 方式就更直白了，请求体里通过 tools 字段声明你要允许模型调用哪些外部能力：
{ "model": "gpt-5.4", "context_window": "1M", "tools": [ { "type": "web_search" }, { "type": "file_read" }, { "type": "command_exec" } ] }有一个细节我提过多次：在 API 请求里声明了 tools，只代表“模型可以选择调用”，不代表“每次都会调用”。模型会根据问题自行判断要不要搜索。如果你希望某些任务必须搜索，就把意图写清楚，比如“请先查证最新版本，再开始写代码”。
2.4 联网搜索填入上下文后，如何防止 token 爆掉
把联网搜索和 1M 上下文放在一起，最容易忽略的是：每次搜索返回的内容本身也会占用上下文空间。一次普通的搜索可能返回十条结果，每条结果被改写成摘要后也有几百到上千 token。如果你让模型连续搜索很多轮，搜索片段会迅速把上下文空间吃掉一大截。
我常用的控制办法有三个：第一，在搜索工具参数里限制返回结果条数，比如只取前五条，而不是默认的十条；第二，给搜索片段设置最大长度上限，避免长网页全文被塞进来；第三，把任务拆成阶段性搜索，每完成一个子任务就要求模型把本轮搜索结果做一次压缩摘要，把旧的搜索细节清理出关键上下文。
这个“压缩摘要”的动作很关键。我在配置多 Agents 的时候也用了同样的思路，因为多 Agent 协作时，上下文不是越多越乱，而是要让每个角色都只能看到自己当下需要的信息。这也是下一节要讲的核心问题。
3. 多 Agents 配置实战：从“单线程执行”到“团队协作”
3.1 为什么单 Agent 在超长任务上会力不从心
在只有单 Agent 的情况下，模型要同时扮演多个角色：理解需求、梳理方案、写代码、自查 bug、修 bug。上下文短的时候问题不大，因为所有环节连在一起也消耗不了多少注意力。但到了 1M 上下文这样的规模，单 Agent 会出现明显的“角色错乱”：它可能写代码时突然开始自我怀疑并翻回去改方案，或者审查问题时被大量参考资料带偏。
我做过一个对比测试：同一套图像处理工具的开发任务，用单 Agent 一步到底，和多 Agent 分工协作，产出的代码质量差别很明显。单 Agent 版本在功能上没问题，但是边界条件处理得粗糙；多 Agent 版本里，规划者负责定义输入输出规格，执行者照着规格写代码，审查者专门找反例去测，最后代码的健壮性明显高一档。
为什么会有这种差别？因为每个 Agent 的系统提示词可以完全定制。你可以让规划者只看目标和约束，让执行者只看规格和代码，让审查者只看风险和边界条件。注意力被刻意限制在各自职责范围内，模型反而不容易犯低级错误。
3.2 我的推荐分工：规划者、执行者、审查者
多 Agents 不是“开得越多越好”，配置混乱反而比单 Agent 更慢。我经过几次调整后，固定下来一套三人组分工，目前稳定使用：
- 规划者（Planner）：负责解析总目标、拆解任务清单、定义完成标准，不写代码，不执行命令。
- 执行者（Executor）：负责实际写代码、改文件、运行命令。执行者可以有多个，每个负责一个模块，但同一时间最好只让一个执行者处理同一块代码，避免文件冲突。
- 审查者（Reviewer）：负责读代码、跑测试、挑毛病。审查者不直接改代码，只把问题清单丢回给执行者。
这套分工对应到工程团队里，就是项目经理、程序员、测试员的三角关系。让每个 Agent 只做一件事，管控难度会大大降低。
3.3 关键配置解析：上下文共享策略与工具权限
多 Agents 配置里最容易出错的地方有两个：上下文共享策略和工具权限。
先说上下文共享。很多初学者直觉认为，让所有 Agent 共享同一个上下文，信息不是最全吗？实际恰恰相反，共享上下文会让 Agent 之间互相干扰：规划者的思考过程被执行者看到，执行者可能被带偏；审查者提出的问题被规划者反复分析，规划者反而忘记了最初目标。我实测下来，更稳的做法是主代理统一调度，子代理之间不共享上下文，只通过结构化摘要传递信息。
具体来说，主 Agent 负责从全局视角判断“下一步该让谁干活”，把任务说明和必要背景压缩成一个子任务包，发给对应的子代理；子代理完成之后，把产出写成一个摘要（一般是几百字，包含改动内容、运行结果、遗留问题），返回给主 Agent。主 Agent 再根据摘要决定是继续下一个步骤，还是把产出交给审查者。
再说工具权限。千万不要给所有子代理都开联网搜索和命令执行权限。权限越开放，系统越不稳定。我的配置原则是最小权限：规划者不需要联网，不需要执行命令；执行者可以联网搜文档、可以执行命令；审查者可以读文件、可以执行测试命令，但不能改文件，也不能搜网页。
3.4 一套可直接套用的多 Agent 配置文件
下面是我目前实际使用的配置逻辑，用 JSON 描述，结构上可以适配多数 Codex 版本：
{ "main_agent": { "model": "gpt-5.4", "context_window": "1M", "tools": ["web_search", "file_read", "command_exec"], "system_prompt": "你是总控代理。你的职责是拆解目标、调度子代理、汇总结果。你不直接写业务代码，但你需要维护总任务清单。每次子代理返回摘要后，更新任务状态，并决定下一步交给谁。" }, "subagents": [ { "name": "planner", "model": "gpt-5.4", "context_window": "128k", "tools": [], "system_prompt": "你是规划者。你只负责分析需求、拆解执行步骤、产出任务规格文档。你不执行命令，不写代码。你的输出必须是结构化任务清单，包含输入、输出、验收标准。" }, { "name": "executor", "model": "gpt-5.4", "context_window": "1M", "tools": ["web_search", "file_read", "command_exec", "file_write"], "system_prompt": "你是执行者。你严格按照规划者给出的任务清单编写代码。写代码前如果有不确定的依赖或接口，先搜索官方文档。每次完成后输出摘要，说明改了哪些文件、运行结果、遗留问题。" }, { "name": "reviewer", "model": "gpt-5.4", "context_window": "128k", "tools": ["file_read", "command_exec"], "system_prompt": "你是审查者。你专门挑毛病，不直接修改代码。你会阅读执行者的产出，运行测试命令，重点关注边界条件、异常处理和安全隐患。输出问题清单和修改建议。" } ] }简单说明几个设计点：主代理和核心执行者保留了 1M 上下文，因为它们需要处理完整项目；规划者和审查者只需要看局部信息，用 128k 已经足够，这样能省掉不少响应时间。子代理之间不配置共享上下文，所有信息传递都靠主代理的摘要转发。
实际启动多 Agent 协作时，我一般不会让所有子代理同时并发，而是按“规划 -> 执行 -> 审查 -> 修订”的顺序走。这样虽然看起来没有“并行效率高”，但对结果的控制力强得多，尤其适合代码这种需要前后一致性的任务。
4. 实操案例：1M 上下文 + 联网 + 多 Agent 跑通一个跨平台图像处理 Demo
4.1 任务拆解与准备阶段
说这么多理论，还是用一个完整案例走一遍。这次我选了个常见的模拟任务：做一个跨平台命令行图像处理小工具，要求支持缩放、裁剪、格式转换，并在处理完成后输出统计信息。
第一步，先把整个项目目录交给主代理，让它基于 1M 上下文完整读取仓库状态。因为项目是全新的，主代理很快就发现目录里只有一份 README 和几个空目录。这时候主代理判定：需要先联网搜索当前图像处理库的最新推荐方案，不能凭训练数据的旧知识硬写。
第二步，主代理把“调研图像处理库选型”这个子任务发给执行者，并且明确要求执行者必须使用联网搜索，还附带了一个条件：优先选跨平台、不依赖系统原生库的方案。执行者收到任务后，先做了几轮搜索，对比两三个主流库的维护状态、API 稳定性和跨平台能力，最后选定了一个同时支持三大操作系统的库，并写了一份简短选型报告。
4.2 主代理调度过程还原（含调用顺序与指令模板）
阶段一：规划。主代理把项目目标发给规划者。规划者不需要看任何代码，只根据目标文字输出任务清单：
1. 初始化项目结构 2. 实现图片读取与基础操作库封装 3. 实现缩放功能（含等比缩放和指定尺寸） 4. 实现裁剪功能（含边界校验） 5. 实现格式转换功能（含质量参数） 6. 实现统计信息输出（耗时、文件大小变化、图片尺寸） 7. 编写跨平台运行测试阶段二：执行。主代理把规划者的任务清单发给执行者，附上一份上下文摘要，里面包含选型结论和项目目录结构。执行者开始工作：创建项目文件、安装依赖、编写主要模块。期间执行者发现某个图像库在高分辨率图片处理时可能触发平台差异问题，于是又做了一次联网搜索，确认该问题在当前版本已修复。
阶段三：审查。执行者提交第一批代码后，主代理把代码路径和运行说明转发给审查者。审查者阅读代码后列出了四个问题：一是缩放函数对零值和负值没有做参数校验；二是裁剪区域超出原图边界时直接报错，而不是给出提示；三是格式转换的质量参数没有范围限制；四是测试脚本没有覆盖空文件输入的场景。
阶段四：修订。主代理把问题清单原样交给执行者，要求执行者逐条修复。执行者修复后又跑了一遍测试，确认四个问题都解决后，再次提交摘要。
整个过程中，主代理没有直接动手写过一行业务代码，但它一直在更新任务状态、转发信息、判断下一步动作。最后的项目因为有审查环节把关，代码质量和边界处理明显比一次性生成要好。
4.3 结果验证与回写：如何确认子代理产出的质量
任务结束后，不能只看摘要就收工。我的习惯是让主代理做一次“全量交叉验证”：把最终代码目录重新读入 1M 上下文，从头到尾检查一遍子代理之间是否产生过不一致。
比如这次案例里，执行者最终实现的功能清单和规划者最初定义的验收标准是否一一对应；审查者提出的问题是否真的在代码里修复，而不是口头确认。主代理用 1M 上下文把整个项目重新看了一遍，额外发现了一个问题：有个配置文件里写死了开发环境的路径，换到另一台机器上运行会失败。审查者因为只看局部代码，没有发现这个环境相关的问题，最后还是靠全量复查揪出来的。
所以我的经验是：多 Agent 协作跑完之后，一定要有一次“全仓库视角”的最终检查。这个检查最适合交给拥有 1M 上下文的主代理或单独开一个最终审查会话，因为只有它能看到全局。
5. 常见问题与排查速查表：我在真实使用中踩过的坑
5.1 五个高频问题：现象、原因、解决办法
我用了一个多星期，把周围几个同样折腾 GPT-5.4 配置的人遇到的问题收集起来，加上自己踩的坑，整理成一张速查表。
第一个高频问题是：配置了 1M 上下文，但模型还是经常说“看不到某段内容”。这大概率不是上下文长度不够，而是提示词里没要求它读取。Codex 环境里，模型不会自动把整个目录都读进内存，它会在需要时调用文件读取工具。如果你想让它全量阅读，得显式发出“先完整扫描项目目录”的指令。
第二个高频问题是：联网搜索开启了，但回答里没有任何外部信息。这种情况先查权限，再查工具命名。CLI 方式下工具名不匹配最容易出这种问题，而且工具名大小写敏感，比如 web_search 和 web-search 可能完全不一样。
第三个高频问题是：多个执行者同时改同一个文件，导致代码互相覆盖。解决方式很简单：同一时刻只允许一个子代理拥有文件写入权限，其他执行者只读。主代理调度时要避免“并发改同一文件”这种低级冲突。
第四个高频问题是：子代理的产出风格差异大，比如规划者写的文档和实际代码结构对不上。这是因为规划者和执行者的系统提示词没有提到“必须使用同一套命名规范”。我后续在规划者提示词里加了一句“输出规格必须包含文件路径、函数名、参数名”，问题就消失了。
第五个高频问题是：多 Agent 协作到一半，主代理自己懵了，开始重复执行同一个子任务。这是因为主代理没有维护“已完成任务清单”。建议在主代理的提示词里强制要求：每次收到子代理摘要后，必须先更新任务状态，再决定下一步，绝不允许跳过状态更新。
| 现象 | 常见原因 | 解决办法 |
|---|---|---|
| 模型读不到中间段内容 | 中间遗忘或未显式读取 | 重要约束放开头，单独建要求文件 |
| 联网搜索无效果 | 权限不足或工具名错误 | 检查账户权限，核对工具名 |
| 上下文快速爆满 | 搜索结果和工具输出占用大 | 限制搜索条数，阶段性压缩摘要 |
| 子代理代码互相覆盖 | 多个执行者同时写文件 | 同一文件只允许一个写入者 |
| 主代理重复执行任务 | 缺少任务状态跟踪 | 强制更新状态后再调度 |
| 编译环境不一致 | 配置文件含本机路径 | 最终用 1M 做全仓库复查 |
5.2 成本与响应速度的平衡：什么场景该开 1M
1M 上下文不是所有场景都需要开，也不是所有场景开完都划算。在我自己的使用习惯里，有一条清晰的切换规则：快速迭代期用 128k，全量检查期再切 1M。
写代码的时候，如果处于高频改动阶段，每轮只涉及一两个文件，开 1M 反而是负担。因为上下文越大，每次请求的输入处理和时间成本都更高，频繁请求会让效率大打折扣。这个阶段我用 128k，只把当前文件和相关依赖摘要喂进去，响应速度快很多。
等到功能基本写完，准备做最终审查时，我再切到 1M，把整个项目目录完整读一遍，让模型从全局找问题。这种“快速迭代 + 全量复查”的组合，比全程开 1M 更省钱，也更容易保持注意力集中。
5.3 一条重要的“减法”经验
最后分享一个我反复踩过几次坑才总结出来的经验：多 Agents 配置不是功能堆得越多越好，反而要先做减法。
我第一次配置时给每个子代理都开了联网搜索，最后发现执行者写代码时经常被无关搜索结果干扰，一会儿想换库，一会儿想换方案，反而比单 Agent 更慢。后来我只给需要外部信息的角色开联网搜索，规划者和审查者一律不开，系统一下子就稳定了。
同样的道理也适用于子代理数量。两个子代理能解决的问题，不要开三个；三个能解决，不要开五个。每多一个子代理，主代理需要维护的调度状态就多一层，出错概率也随之上升。先用“一个执行者 + 一个审查者”的组合跑通流程，确认稳定之后，再根据任务复杂度添加规划者或者其他角色。
我现在的习惯是提前写好一套最小配置模板，默认只有三个角色，每接到新任务后根据情况增删角色和权限，而不是先开一堆 Agent 再慢慢调试。这个习惯帮我省掉了大量无效调试时间，也算是我配置 GPT-5.4 这套环境最值得拿出来分享的实操心得。
