codex 代码生成调优实战：参数、提示词与流水线设计

1. 从一次深夜调试说起：codex 到底卡在哪

第一次把 codex 接进日常开发流程，是在一个需要批量生成接口文档注释的晚上。当时我的想法很简单：把一段业务代码丢进去，让它按既定格式吐出注释，再人工过一遍就完事。结果第一轮跑下来，输出格式忽好忽坏，同样的输入两次结果不一样，偶尔还会把函数签名改掉。那一刻我意识到，codex 这类代码生成工具不是“输入即所得”的黑盒，它有一套自己的脾气，摸不清脾气就会一直踩坑。

这篇内容想聊的就是这些“脾气”。codex 在这里指的是以代码为核心对象的智能生成与补全能力，它可以是一个命令行工具、一个编辑器插件，也可以是一套接入 API 的自动化脚本。它能做的事很实在：根据上下文补全函数、按注释生成实现、把一段旧代码改写成新风格、批量生成测试用例、解释报错信息。适合谁来读？如果你刚开始把 codex 往项目里塞，或者已经用了一阵但总觉得“不太听话”，那这篇基本能对上你的痛点；如果你只是偶尔用它写两行小脚本，也能从里面的参数调优和排查思路里捞到东西。

我踩过的坑大致分几类：输出不稳定、上下文被截断、生成结果跑不通、和现有代码风格打架、批量任务跑到一半崩掉。下面按“为什么这样设计—关键细节怎么抠—完整流程怎么跑—出问题怎么查”的顺序展开，每一块都尽量给到能直接抄的参数和步骤。需要说明的是，文中涉及的具体参数值、目录结构、脚本写法，是基于常见工程实践做的合理补全，不同工具版本的默认值可能有差异，落地时以你手头工具的文档为准。

2. 整体设计与思路拆解：为什么不能“一把梭”

2.1 把 codex 当成“有状态的协作者”而不是“无状态的函数”

很多人第一次用 codex 失败，根源在于心态：把它当成一个f(input) = output的纯函数，输入一段代码就该得到确定结果。实际用下来，它更像一个有状态的协作者——你给它的上下文、提示词的措辞、甚至前几轮对话的历史，都会影响这一轮的输出。我做过一个对比实验：同一段待补全的函数，第一次直接丢进去，第二次先给一句“这是一个 Python 3.10 项目，使用类型注解，不要引入新依赖”，两次输出的风格差异非常明显，后者几乎不用改就能合并。

这个特性决定了整体设计思路：不要指望一次调用解决所有问题，而要设计一条“生成—校验—修正”的流水线。流水线里每个环节职责单一，出问题容易定位。比如生成环节只负责产出候选代码，校验环节用静态检查工具跑一遍，修正环节把报错信息回喂给 codex 让它改。这样即使某一步输出跑偏，也不会污染整条链路。

为什么不用“一把梭”的单次调用？因为单次调用把生成、格式化、纠错全压在一次推理里，任何一环出偏差都没有回退余地，而且失败后你拿不到中间态，排查全靠猜。流水线虽然多写几十行胶水代码，但换来的是可观测性和可复现性，长期看这笔账很划算。

2.2 上下文窗口是稀缺资源，要像管理内存一样管理它

codex 类工具普遍有上下文长度限制，超出部分会被截断。截断本身不可怕，可怕的是截断位置不可控——你可能把函数定义截掉了，只留下函数体，模型看到一堆没有来源的变量名，自然生成得乱七八糟。我的做法是显式构造上下文，而不是把整个文件甚至整个目录一股脑塞进去。

具体策略是分层：第一层是“必须给”的，包括目标函数的签名、紧邻的几行代码、相关的类型定义；第二层是“锦上添花”的，比如同文件里其他函数的命名风格、项目里通用的工具函数；第三层是“尽量别给”的，比如无关的业务逻辑、大段的配置文件。实测下来，把上下文控制在窗口容量的六到七成，留出余量给模型输出，效果比塞满要好。塞满的坏处是模型容易“分心”，生成时混入不相关的命名和逻辑。

这里有个容易被忽略的点：上下文的顺序也有讲究。把最相关的代码放在靠近输入末尾的位置，模型对尾部内容的注意力通常更强。我习惯把目标函数放在最后，前面依次是类型定义、工具函数、风格示例。这个顺序不是玄学，而是基于“近因效应”的合理利用，换过几次顺序对比，尾部放置确实让生成的相关性更稳。

2.3 提示词要写成“验收标准”，而不是“愿望清单”

“帮我优化这段代码”是典型的愿望清单，模型不知道你要优化性能、可读性还是体积，只能猜。我后来改成写验收标准：明确输入输出、明确约束条件、明确禁止事项。比如“保持函数签名不变；不引入第三方库；异常处理沿用项目现有的AppError；返回值的类型注解必须补全”。这几条一写，输出的可用率肉眼可见地上升。

验收标准的写法有个小技巧：把“不要什么”写具体。模型对否定指令的遵循度，取决于否定对象是否明确。“不要写得太复杂”是模糊的，“单个函数不超过 30 行、圈复杂度不超过 10”是可执行的。我一般会准备一个提示词模板，把项目级的约束（语言版本、依赖策略、命名规范、错误处理约定）固化进去，每次调用只替换任务相关的部分，这样既省事又保证一致性。

3. 核心细节解析与实操要点：那些决定成败的小参数

3.1 温度与采样：稳定性和多样性的取舍

生成不稳定，十有八九是采样参数没调好。温度（temperature）控制随机性，值越高输出越发散，越低越保守。做代码补全这类任务，我一般把温度压到 0.2 以下，追求“同样的输入尽量给同样的输出”。但温度调到 0 也不是万能药，有些实现里温度 0 仍会有微小随机性，这时候要配合固定随机种子（如果工具支持）来保证可复现。

除了温度，还有 top-p（核采样）这个参数。它的作用是只在概率累计达到 p 的候选词里采样，p 设成 0.9 到 0.95 比较常见。温度和 top-p 一般不要同时大幅调整，否则两个参数的效果会互相干扰，调起来像在雾里开车。我的经验是：先固定 top-p 在 0.95，只调温度；温度定下来后再微调 top-p。每次只动一个变量，才能知道是哪个参数起了作用。

下面这张表是我在不同任务类型下的参数起点，可以直接拿去试，再根据实际输出微调：

注意：不同工具对温度的取值范围定义可能不同，有的用 0–1，有的用 0–2，调参前先确认量纲，别把 0.2 当成 2.0 用。

3.2 最大输出长度：设小了截断，设大了跑偏

最大输出长度（max tokens）这个参数，新手容易设得太小，结果生成到一半被硬生生切断，函数少个右括号，后面全得手工补。设得太大也有问题：模型在写完该写的内容后，可能继续“自由发挥”，补出一堆没人要的辅助函数。我的做法是按任务预估：一个普通函数体大概 100 到 300 个 token，加上注释和类型注解，留 500 到 800 的余量比较稳妥；批量生成时按单条上限乘以条数再留 20% 缓冲。

判断是否被截断有个简单办法：看输出的结尾是不是完整的语法结构。如果结尾停在一个表达式中间、或者括号没闭合，基本就是撞上限了。这时候不要急着重跑，先把上限调大，同时检查上下文是不是太长挤占了输出空间——上下文和输出共享窗口，这是很多人忽略的耦合关系。

3.3 停止序列：给生成画一条明确的终点线

停止序列（stop sequences）是控制输出边界最直接的手段。比如你只想让它生成函数体、不要生成调用示例，可以把\n\ndef或者\n\nif __name__设为停止序列，一旦生成到下一个顶层定义就自动停。这个技巧在批量处理时特别有用，能避免一条输出把下一条的“地盘”也占了。

设置停止序列的坑在于：停止串不能太短，也不能出现在正常内容里。我曾经把\n\n设成停止序列，结果模型在函数内部空行处就停了，输出全是半截货。后来改成更具体的模式，比如\n\nclass、\n\n# ---，才稳定下来。经验是：停止串至少包含一个结构性标记（如def、class、特定的注释分隔符），并且这个标记在目标内容里不会自然出现。

3.4 系统提示与角色设定：把项目规范“焊”进去

系统提示（system prompt）是每次调用都会生效的“底层设定”，适合放那些全局不变的约束。我把项目规范浓缩成几条写进去：语言与版本、依赖策略、命名风格、错误处理约定、注释语言。这样每次用户提示只需要描述具体任务，不用重复啰嗦项目背景。

这里有个细节值得说：系统提示里的约束要可验证。“代码要优雅”没法验证，“函数名用 snake_case、类名用 PascalCase”可以验证。可验证的约束才能在下游用静态检查工具自动核对，形成闭环。我一般会把系统提示和校验脚本的规则对齐，提示里说什么，校验就查什么，两边不一致的地方就是 bug 的高发区。

4. 实操过程与核心环节实现：一条能跑通的流水线

4.1 环境与目录准备：先把“料”备齐

动手之前先把目录结构定下来，后面排查问题时能省很多事。我的习惯是每个生成任务一个独立目录，里面放四样东西：输入代码、提示词模板、生成结果、校验日志。目录名带上时间戳和任务标识，避免多次运行互相覆盖。

mkdir -p codex_work/20250115_docgen/{input,prompts,output,logs}

输入代码不要直接放整个仓库，而是把相关文件复制进来，手动裁剪到只保留必要部分。这一步看似麻烦，实则是控制上下文最有效的手段——你在复制的时候就已经在做相关性筛选了。提示词模板单独存成文件，方便版本管理和复用。生成结果按序号命名，和输入一一对应，出问题时能快速定位是哪条输入导致的。

依赖方面，除了 codex 工具本身，我一般还会装一个格式化工具和一个静态检查工具。格式化负责统一输出风格，静态检查负责抓语法错误和明显的逻辑问题。这两个工具是流水线的“质检员”，没有它们，生成结果的质量全靠肉眼，效率上不去。

4.2 构造请求：把上下文、提示词、参数组装起来

组装请求的核心是“分层拼接”。我写了一个小函数来做这件事，逻辑是：系统提示打底，然后是风格示例，再是相关类型定义，最后是目标代码和任务描述。每层之间用明确的分隔符隔开，方便模型区分，也方便自己调试时看清边界。

def build_prompt(system_rules, style_samples, type_defs, target_code, task_desc): parts = [ "### 项目规范\n" + system_rules, "### 风格示例\n" + style_samples, "### 相关类型\n" + type_defs, "### 目标代码\n" + target_code, "### 任务\n" + task_desc, ] return "\n\n".join(parts)

任务描述部分我坚持写“输入—输出—约束”三段式。输入说清楚给的是什么，输出说清楚要什么格式，约束说清楚不能碰什么。举个例子：输入是“一个接收用户列表、返回按注册时间排序结果的函数”，输出是“补全函数体并添加 docstring”，约束是“不改变签名、不引入新依赖、异常沿用现有错误类型”。这三段写清楚，生成结果的返工率能降一大截。

参数组装时把温度、最大输出长度、停止序列一起带上，并且把这次用的参数记进日志。很多人排查问题时只记得看输出，忘了当时用的什么参数，导致无法复现。日志里记下参数，复现就是分分钟的事。

4.3 生成与校验：让机器先过一遍

生成结果拿到手，先别急着看内容，先跑格式化。格式化工具能自动修掉缩进、空格、换行这类低级问题，省下大量肉眼检查的时间。格式化之后再跑静态检查，重点看三类问题：语法错误、未定义变量、类型不匹配。这三类占了生成结果问题的绝大多数。

校验脚本我一般写成“检查—记录—分类”三步。检查用现成工具，记录把报错原文写进日志，分类则按错误类型打标签，方便统计哪类问题最高发。跑过十几轮之后你会发现，问题分布很有规律，比如某类任务总是缺类型注解，某类任务总是异常处理不全，针对性地改提示词就能压下去。

# 格式化 black output/gen_001.py # 静态检查，输出到日志 python -m pyflakes output/gen_001.py > logs/check_001.log 2>&1

校验不通过的条目，不要直接扔掉重生成，而是把报错信息连同原代码一起回喂给 codex，让它“看着报错改”。这个修正环节的成功率比重新生成高得多，因为模型有了明确的修改目标，不用再猜哪里不对。修正一般跑一到两轮就能收敛，超过三轮还改不好的，多半是上下文本身有问题，得回头检查输入。

4.4 人工复核与合并：最后一道关不能省

机器校验过了，不代表能直接合并。我坚持人工过一遍，重点看三样：逻辑是否符合业务预期、命名是否和项目一致、边界条件是否处理了。静态检查抓不到业务逻辑错误，这块只能靠人。复核时我会对照输入逐条核对，确认没有“生成时偷偷改了需求”的情况。

合并前还有个小步骤：把生成代码和原有代码放在一起跑一遍现有测试。测试通过是最硬的验收标准，比任何肉眼检查都可靠。如果项目测试覆盖不足，至少手动构造几个典型输入跑一下，确认行为符合预期再合并。这一步花的时间不多，但能挡住大部分“看着对、跑起来错”的问题。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 输出格式忽好忽坏：先查采样，再查上下文

同样的输入两次结果不一样，第一反应应该是采样参数。温度高于 0.3 时，输出波动是正常现象，做代码任务时把温度压到 0.2 以下基本能稳住。如果温度已经很低还是不稳，就要怀疑上下文里有没有“歧义源”——比如同时给了两种风格的示例，模型在两种风格之间摇摆。解决办法是只保留一种风格示例，把另一种删掉。

还有一种隐蔽情况：上下文里包含了互相矛盾的约束。比如系统提示说“用类型注解”，风格示例里却全是无注解的代码，模型就会犯迷糊。排查时把系统提示和示例逐条对照，确保两者不打架。我遇到过最离谱的一次，是示例代码里有个拼写错误的变量名，模型“有样学样”把这个错误也复制到了生成结果里，查了半天才发现源头在示例。

5.2 生成结果跑不通：按“语法—依赖—逻辑”三层排查

跑不通的代码，排查顺序很重要。先看语法，格式化工具和静态检查能抓掉大部分；再看依赖，生成时有没有引入项目里没有的库、有没有调用不存在的函数；最后看逻辑，前两层都过了还跑不通，多半是业务逻辑理解偏差。

依赖问题有个高频场景：模型“记得”某个库的旧版 API，生成了已经废弃的写法。这时候不要改生成结果，而是把项目实际使用的版本号写进系统提示，明确告诉它“用这个版本的 API”。版本信息是很多人漏给的关键上下文，补上之后这类问题会少很多。

逻辑偏差则要看任务描述是不是有歧义。比如“按时间排序”，是升序还是降序？是创建时间还是更新时间？这些不写清楚，模型只能猜，猜错很正常。我的习惯是把所有可能歧义的词都展开成明确表述，宁可啰嗦一点，也别留模糊空间。

5.3 批量任务跑到一半崩掉：做好断点与限流

批量跑几十上百条时，中途崩掉是常事。原因无非几种：某条输入触发了工具的异常、请求频率超限、单条输出过长导致超时。应对办法是给批处理脚本加断点续跑能力——每条任务完成后记录状态，崩了之后从断点继续，不用从头再来。

限流方面，如果工具走的是远程调用，一定要控制并发数。我一般把并发压到个位数，并且在每次请求之间加一点间隔。跑得快不如跑得稳，批量任务崩一次重跑的时间成本，远高于稍微放慢一点。另外给单条任务设超时，超时就跳过并记录，别让一条卡死的任务拖垮整批。

下面这张速查表是我整理的常见问题与对应处理，遇到时可以直接对照：

5.4 几个容易被忽略的实操心得

第一个心得：给 codex 的代码要“干净”。输入里如果带着大段注释掉的死代码、调试用的打印语句，模型容易被带偏，生成结果里也可能混进类似的东西。输入前花两分钟清理，比生成后花二十分钟修改划算。

第二个心得：善用“反例”。与其只说“要写成什么样”，不如再给一个“不要写成什么样”的反例，并说明为什么不要。模型对反例的理解往往比对正例更到位，尤其是风格类约束，一个反例顶三句描述。

第三个心得：把高频任务模板化。注释生成、测试生成、报错解释这几类任务，提示词结构基本固定，做成模板后每次只填变量，既快又稳。模板要定期回顾，把踩过的新坑补进去，模板本身就是经验的沉淀。

第四个心得：别迷信“一次生成到位”。再好的提示词也有失手的时候，把生成当成“初稿”，把校验和修正当成“编辑”，心态上就顺了。我现在的流程里，生成只占三成时间，校验和修正占七成，但整体效率比手工写高得多，因为校验和修正可以半自动化，而手工写是从零开始。

6. 把 codex 用顺手的几个长期习惯

用了一段时间之后，我慢慢形成几个习惯，谈不上多高深，但确实让日常使用顺畅了不少。一个是维护一份“提示词片段库”，把验证过好用的约束语句、风格描述、任务模板存起来，新任务来了先翻库，能复用就复用，减少重复造轮子。另一个是定期回看校验日志，统计哪类错误最高发，针对性地改提示词或调参数，让系统越用越稳。

还有一个习惯是给每次生成留“可追溯的痕迹”。输入、提示词、参数、输出、校验结果，五样东西成套保存，出问题时能完整复现当时的场景。这个习惯在团队协作里尤其重要，别人接手你的任务时，看痕迹就能明白当时怎么想的、为什么这么调，省去大量沟通成本。

最后说一个我自己的体会：codex 这类工具的价值，不在于它能替你把代码写完，而在于它能把“从零到初稿”这段最耗神的过程压缩掉，让你把精力集中在判断和打磨上。把它当成一个需要调教的协作者，而不是一个许愿池，心态对了，用起来就顺了。至于参数怎么调、提示词怎么写，上面这些都可以直接拿去试，试的过程中记得每次只改一个变量，把结果记下来，慢慢就能摸出适合自己项目的那套配置。