前几天接了个有点折腾的活儿把一篇单细胞测序论文的完整分析流程从头到尾复现出来。以前干这种事我得先配环境、下数据、翻 Methods 段落逐个对参数再手写几百行胶水脚本中间任何一步的包版本对不上就得回头查半天。这次我换了路子直接用 OpenAI Codex CLI模型选 gpt-5.6-sol推理强度拉到 high让它在终端里一边读论文、一边写代码、一边真跑数据我全程只负责盯结果和下指令。实测下来这个组合比我想象中能打但也确实踩了一串坑模型兼容性报错、CLI 二进制找不到、连接中断无限重连、接第三方模型时 reasoning_content 回传导致 400……这些报错信息零散网上能搜到的大多是提问帖没人把完整链路讲清楚。这篇文章就把我从装好 Codex 到跑出论文级图表的全过程写出来重点放在任务拆解、模型鉴权、报错排查和结果验证上。适合两类人看一类是做单细胞生信分析、想用 agent 类工具加速复现的研究生和从业者另一类是对 Codex CLI 感兴趣、想拿真实科研场景练手的人。1. 为什么让 Codex 来复现单细胞论文一次不想再手搓脚本的尝试1.1 单细胞复现的痛点脚本量不大但琐碎到劝退单细胞 RNA-seq 的标准分析链路其实很固定质控、标准化、高变基因、PCA、批次整合、聚类、找 marker、注释细胞类型、出图。难点从来不是某个步骤有多深的算法原理而是整个链条上有太多细节陷阱。比如从 GEO 下载的数据可能是三种不同格式10x 的 h5、mtx 稀疏矩阵、或者已经预处理过的 h5ad基因注释有的是 Ensembl ID 有的是 gene symbol质控阈值论文里写的是 200 和 20%但那是人家数据集上的结论换一个数据集直接套用往往不合适。这些活儿单独看都不难但串联起来非常消耗耐心而且每一步都可能因为版本差异报错。以前我复现一篇论文光是在 Scanpy 和 Seurat 之间切换、处理格式不一致的问题就能耗掉大半天。这种场景恰好是 Codex 这类终端 agent 的主场。它不是简单地在对话框里给你生成一段代码让你自己复制去跑而是能直接在你的机器上执行命令、读写文件、看到报错之后自己改代码重试。我只需要把论文 PDF 和原始数据放在指定目录告诉它目标是复现 Figure 2 到 Figure 5剩下的链路它可以反复迭代直到跑通。1.2 gpt-5.6-sol high 在复现场景下的定位这次我用的模型是 gpt-5.6-sol并在启动时把推理强度指定为 high。sol 这个后缀在 OpenAI 的模型命名里代表 solver 定位简单理解就是专门为多步推理和 agent 任务优化的版本比通用对话模型更擅长拆解长任务、按计划执行、遇到错误自我修正这类行为。推理强度 high 意味着模型在每一步回答前会做更长的内部推理代价是 token 消耗明显增加、响应变慢。为什么复现任务值得上 high因为生信分析链路长一个环节理解错后面所有步骤都会被带偏。用 low 或 medium 可能省 token但模型容易在某个参数上想当然比如默认用了错误的归一化方式等你跑到聚类阶段才发现不对劲回头返工的成本远高于那点 token 费。实测下来high 模式在前几步规划阶段的价值最大它会把先看数据分布再定阈值这类意识内化到代码里而不是机械照搬论文参数。1.3 这篇实测适合谁参考如果你只是想看 Codex 怎么安装、怎么配模型可以直接跳到第 2 节如果你关心的是复现思路和任务拆解重点看第 3、4 节要是你已经在用 Codex 但被各种报错卡住第 5 节我把这次实际遇到的报错和排查过程都列出来了。我不会只给结论会把判断逻辑一起写出来这样你遇到类似问题能自己顺着排查。2. 从装好 Codex 到跑通第一句指令模型兼容性是第一道坎2.1 安装方式对比与我的选择Codex CLI 的安装路径主要有三条npm 全局安装、Homebrew 安装、Windows 桌面版。我把差异整理成了表格方便你按自己的环境选。安装方式适用平台优点注意点npm install -g openai/codexmacOS / Linux / Windows(WSL)最灵活升级方便需要 Node.js 18依赖 npm 全局 bin 路径brew install codexmacOS和系统包管理统一版本可能比 npm 滞后一点Windows 桌面版Windows 原生有图形界面适合不爱敲命令的人终端内嵌部分高级参数要切到 CLI 模式才有我主力机器是 macOS所以直接走了 npm 全局安装。装完先跑codex --version确认版本号能正常输出。这里插一句如果你在 VS Code 的 Codex 插件里遇到unable to locate the codex cli binary这种报错八成是插件找不到 CLI 可执行文件先确认npm root -g的路径有没有加进 PATH然后重启 VS Code 让插件重新扫描一遍环境变量问题基本就解决了。这个问题我在第 5 节还会展开讲。2.2 登录鉴权ChatGPT 订阅账号和 API Key 不是一回事Codex 支持两种登录方式一种是直接登录 ChatGPT 账号走订阅额度另一种是用 API Key按 API 平台的计费走。这两种方式的差异比很多人想象的要大——它俩背后是不同的鉴权通道能用的模型列表也不一样。ChatGPT 账号方式的好处是如果订阅包含了 Codex 额度用起来方便codex login弹浏览器授权就行。但代价是模型白名单由消费级 ChatGPT 后端决定不是 API 平台上有什么模型它就能用什么模型。API Key 方式则是codex login --api-key然后粘贴密钥或者直接设置OPENAI_API_KEY环境变量它能用的模型取决于你的 API 账号被授予了哪些模型的访问权限。这次实测我一开始图省事用 ChatGPT 账号登录结果就撞上了模型兼容性报错。2.3 the gpt-5.6-sol model is not supported 报错的前因后果我在终端里启动时指定了模型和推理强度codex --model gpt-5.6-sol --reasoning-effort high第一次运行直接给我弹了这么一句the gpt-5.6-sol model is not supported when using codex with a chatgpt account这个报错信息其实已经把原因说得很直白了当前用的是 ChatGPT 账号鉴权而 gpt-5.6-sol 不在 ChatGPT 订阅通道支持的模型列表里。这类 sol 后缀的推理模型通常属于 API 平台上的特定产品线消费级 ChatGPT 后端并没有给它开放调用入口。解决办法不是换模型硬凑而是切换鉴权通道。我重新用 API Key 登录codex login --api-key然后再次启动同一条命令模型就能正常加载了。前提是你的 API 账号确实被授予了 gpt-5.6-sol 的访问权限如果没权限会报 403 或者模型未找到之类的错误那就只能先用官方文档里列出的当前可用模型顶上等权限开通再切回来。这个坑给所有想用 Codex 的人提了个醒遇到model is not supported when using codex with a chatgpt account这种报错先别急着怀疑模型名写错先确认自己当前走的是哪条鉴权通道。很多人在这一步卡住是因为根本没意识到 ChatGPT 账号和 API 账号是两个不同的授权体系。2.4 先用一个小任务验证工具链模型能加载之后我没有直接上完整论文而是先让它跑了一个两分钟的冒烟测试生成一段 Scanpy 质控代码跑一个 200 个细胞的小型模拟数据集。这个测试的目的不是看代码质量而是确认整条工具链是通的——CLI 能启动、模型能响应、执行环境里的 Python 包齐全。冒烟测试通过后我把工作目录结构确定下来repro/ ├── paper/ # 论文 PDF 与补充材料 ├── data/ # 原始数据存放处 ├── scripts/ # Codex 生成的脚本 ├── figures/ # 输出的图表 └── REPO.md # 复现日志记录每一步决策这个目录结构后面被证明非常关键尤其是 REPO.md它就是整个复现过程的外置大脑。3. 把论文翻译成机器能执行的步骤任务拆解与上下文管理3.1 让 Codex 先读论文再出复现计划拿到一篇论文就让它直接开始复现这是最容易翻车的用法。模型再强也得先知道你要复现哪些图、用的什么数据、什么工具链。所以我的第一步是让 Codex 先读论文输出一份结构化的复现计划。我用的是非交互式执行模式一条命令把任务丢给它codex exec -m gpt-5.6-sol --reasoning-effort high \ 读取 paper/ 目录下的 PDF 和补充材料提取以下信息并写入 REPO.md 1. 数据来源GEO 编号、样本列表、物种 2. 分析工具与版本Scanpy/Seurat、Cell Ranger、参考基因组 3. 关键参数质控阈值、归一化方式、聚类分辨率 4. 需要复现的图图号、图类型、预期内容Codex 处理 PDF 的方式是直接调文本提取然后把内容拆到对应的字段里。这一步跑完REPO.md 里就有了一份带引用的参数清单。我对照原文检查了一遍提取结果基本准确个别参数它理解有偏差的地方我直接在 REPO.md 里改了并标注了修改原因。3.2 我拆出的 12 个子任务清单读完全文后我没有让它一口气做完而是要求它把整个复现拆成 12 个可独立执行、可独立验证的子任务编号子任务输入输出T01下载原始数据并校验完整性GEO 编号原始矩阵文件T02数据加载与格式统一原始文件AnnData 对象T03质控指标可视化表达矩阵分布图T04质控过滤分布图过滤后矩阵T05标准化与对数化过滤后矩阵标准化矩阵T06高变基因筛选标准化矩阵HVG 列表T07数据缩放与 PCAHVG 矩阵PCA 降维结果T08批次整合PCA 结果校正后嵌入T09邻域图构建与 UMAP校正后嵌入UMAP 坐标T10Leiden 聚类与分辨率扫描邻域图聚类标签T11marker 基因鉴定聚类标签marker 表格T12细胞类型注释与出图marker 表格论文级图表拆成子任务的核心价值在于每个任务都能单独验证失败了只需要回滚到上一个成功节点而不是整条链路推倒重来。这跟在项目管理里拆里程碑是一个道理只不过这次执行者是模型。3.3 用项目日志和会话恢复管理长任务Codex 有个容易被人忽略的功能每个会话会自动 checkpoint你可以随时用codex resume恢复。我在跑完整复现的将近两个小时里中途断过一次连接恢复会话后上下文还完整保留着这点非常实用。但光靠自动 checkpoint 还不够我要求 Codex 在每个子任务完成后把关键决策写进 REPO.md格式是固定的## T04 质控过滤 - 时间xx:xx - 决策min_genes300, pct_counts_mt15 - 依据小提琴图显示第二个峰在 300 附近线粒体比例在 15% 后平台期 - 结果保留 8921 个细胞占原始 78%这样做的原因是万一后面跑出来的结果和论文对不上我能回溯到具体是哪一步的什么决策出了问题而不是对着终端滚动日志干瞪眼。对于长链路任务来说这种过程留痕比最终结果更重要。4. 实测主链路从原始矩阵到论文级图表的完整过程4.1 数据落地与格式确认我这次处理的是 10x Genomics 平台的标准输出从 GEO 下载后是 h5 文件。下载完第一件事不是急着读而是先校验文件完整性我用md5sum对照 GEO 页面给出的校验值确认没下错。加载数据这一步Codex 生成的代码非常标准import scanpy as sc adata sc.read_10x_h5(data/raw_counts.h5) adata.var_names_make_unique() adata.obs_names_make_unique() adata.var[mt] adata.var_names.str.startswith(MT-)有一个细节值得强调读取之后一定要确认基因注释是 symbol 还是 Ensembl ID。如果 var_names 里是 ENSG 开头的一串编码后面所有 marker 判断逻辑都要跟着调整。这次数据直接是 gene symbol省了一步转换但我在 REPO.md 里特意记了一笔防止后续被误导。4.2 质控阈值不能照抄让 Codex 先看分布论文里写的质控标准通常是min_genes200线粒体比例低于 20%这是他们在自己数据集上调出来的。但我手上这份数据测序深度、样本质量都可能不一样直接套用大概率会误杀或漏掉细胞。所以 T03 这个子任务我专门要求 Codex 先出图再定阈值。它生成了三个分布图每个细胞的基因数分布、UMI 总数分布、线粒体基因比例分布。看到图之后它给出的建议是sc.pp.filter_cells(adata, min_genes300) sc.pp.filter_cells(adata, max_genes6000) adata adata[adata.obs.pct_counts_mt 15, :].copy()理由是基因数分布的低峰在 300 附近线粒体比例在 15% 之后出现平台期。这个判断过程完全符合我人工处理时的思路而且它把每个阈值的依据都写进了 REPO.md这一步的体验是我觉得整次实测里最接近靠谱实习生的表现。4.3 标准化、高变基因与批次整合质控通过后是标准的处理链normalize_total归一化到每细胞一万 counts然后log1p对数化接着highly_variable_genes选高变基因scale标准化到零均值单位方差最后跑 PCA。sc.pp.normalize_total(adata, target_sum1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes2000, flavorseurat) sc.pp.scale(adata, max_value10) sc.tl.pca(adata, n_comps50, svd_solverarpack)批次整合是这组数据里绕不开的一步因为样本来自不同建库批次。Codex 在这里做了一个我认为很正确的决定先用 PCA 结果的肘图确认主成分数量再跑 Harmony 做批次校正而不是直接对原始表达矩阵校正。sc.external.pp.harmony_integrate(adata, keybatch)校正前后它各出了一张 UMAP 对比图能明显看到校正前不同批次细胞各自抱团、校正后细胞按生物学类型而非批次聚集。这一步的价值在于它证明了批次效应确实存在也证明了处理有效而不是稀里糊涂地把数据丢进 Harmony 就完事。4.4 聚类、marker 与细胞类型注释聚类我用的是 Leiden 算法。Codex 在分辨率上做了一个小范围扫描分别跑了 0.3、0.5、0.8 三组对比稳定性和 marker 特异性之后选了 0.5 作为最终参数。这种参数不再是拍脑袋决定的工作方式是 agent 类工具带来的最大改变。marker 鉴定用的是 Wilcoxon 秩和检验每个 cluster 对比其余所有细胞sc.tl.rank_genes_groups(adata, groupbyleiden, methodwilcoxon)cluster 注释阶段我让 Codex 基于 marker 表格推断细胞类型并给出置信依据。它给出的注释涵盖了 T 细胞CD3D、CD3E、B 细胞MS4A1、CD79A、髓系细胞LYZ、CST3、NK 细胞NKG7、KLRD1这些经典 marker和论文里的注释基本对应。4.5 出图参数与论文图对比出图阶段我要求所有图按论文出版标准输出300 dpi、统一配色、坐标轴标签完整。Codex 生成的代码里有一个细节我很满意——它在sc.pl.umap里传了frameonFalse这个参数对最终观感影响很大说明它对论文级图表的理解不只是分辨率还包括了排版风格。最终产出的图包括UMAP 按 cluster 着色、UMAP 按细胞类型着色、marker 基因点图、关键 marker 的特征图。和论文原图对比细胞群体的整体拓扑结构高度相似主要细胞类型都能对上。细微差异集中在两个交界处的细胞群划分上这个我在第 6 节会专门说怎么排查。5. 复现过程中的真实报错与排查思路5.1 codex cli binary 缺失与 PATH 问题这个报错出现在我配置 VS Code 插件的时候。插件启动后提示unable to locate the codex cli binary意思很明确插件在系统 PATH 里找不到 codex 可执行文件。排查思路是先确认 CLI 本身装没装好。在终端里跑codex --version正常输出说明 CLI 没问题问题出在插件进程的环境变量上。VS Code 从图形界面启动时不一定继承 shell 配置文件里的 PATH 设置。解决办法是把 npm 全局 bin 目录加进系统级 PATH然后彻底重启 VS Code不是 reload window是退出重开。如果你记不清 npm 全局目录在哪用npm prefix -g查一下再把$(npm prefix -g)/bin加进 PATH 就行。5.2 connection failed 与无限重连的处理复现到一半的时候Codex 突然开始转圈然后提示连接失败进入反复重连状态。错误信息是codex connection failed: error sending request。这个问题的直接原因是 API 请求在传输层就失败了服务端根本没收到完整请求。我的排查顺序是固定的先确认 API 服务能从当前环境正常访问用curl手动打一个最小的接口请求看返回确认服务端没问题之后再看本地是否有第三方转发或网关进程在中间转发如果配置了类似 CC Switch 这种本地 API 网关工具检查它的进程是否还活着、转发的目标配置是否正确。实测下来那次断连就是本地转发进程挂掉了重启之后 Codex 恢复正常。有一点经验值得分享长任务跑到一半断连不要慌Codex 有会话 checkpoint重新启动后用codex resume就能从断点继续不用从头再来。5.3 接第三方模型时 reasoning_content 回传导致的 400 报错我还试过把 Codex 接到第三方模型服务上跑结果踩了一个非常典型的坑。当时配置的 provider 是 DeepSeek模型是 deepseek-v4-flash请求发出去之后报错关键信息是cc switch ... failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.这类报错的核心在reasoning_content。DeepSeek 的思考型模型在返回结果时除了常规的content还会带一段reasoning_content也就是模型的内部推理过程。这种模型有个硬性要求多轮对话中上一轮返回的reasoning_content必须在下一轮请求时原样带回否则 API 直接拒绝返回 400。这个要求很容易被本地网关工具破坏因为很多网关在设计时只透传常规的 content 字段把 reasoning_content 丢掉了下一轮请求自然就报错。解决办法按优先级排序先升级网关工具到支持 DeepSeek 思考模式的版本如果版本已经是最新还报错就在配置里关掉模型的思考模式改用非思考型模型或对应参数最后才考虑在适配层手动补全 reasoning_content 字段的回传逻辑。这个报错给所有接第三方模型的人提了个醒不是能通过网关转发请求就万事大吉了每种模型特有的字段约束网关不一定替你处理。5.4 token 与时间成本实测账单和经验值最后说说大家最关心的成本。整篇论文复现跑下来从读论文、拆任务、执行到最终出图gpt-5.6-sol 配合 high 推理强度总耗时大约两小时token 消耗比我自己预估的多不少主要花在推理 token 上。我的经验是分阶段控制成本任务拆解和代码规划阶段用 high 强度这部分 token 花得值代码执行和报错修复合阶段可以临时降到 medium因为这类任务的正确性反馈来自运行结果本身模型不需要做太深的前瞻推理出图和最终验证阶段再切回 high。这种按阶段切换推理强度的做法能省下大概三成 token同时不影响最终质量。6. 复现结果怎么验证别被跑通骗了6.1 用生物学先验做锚点脚本跑通、图能出只代表流程通畅不代表结果正确。我验证结果的第一层标准是生物学先验这个组织/样本里应该有哪些细胞类型各自的比例大概是多少关键 marker 的表达模式是否符合认知。比如 T 细胞的 CD3D 应该只在 T 细胞 cluster 里高表达如果在好几个 cluster 里都出现高表达要么是注释错了要么是聚类分辨率有问题。我用 Codex 生成了一张 marker 点图逐个人工核对关键 marker 的表达特异性这一步不能省机器跑得再顺也不能替代人的判断。6.2 版本、随机种子与数值不一致的排查顺序复现结果和论文不可能做到完全一致这一点要有预期。我这次遇到的差异集中在两个 cluster 边界上论文把它们分成两类我这边合并在了一起。排查顺序我是这样定的先查软件版本Scanpy 1.9 和 1.10 在部分算法实现上有差异pip freeze看看是不是版本漂移再查随机种子Leiden 聚类和 UMAP 都依赖随机初始化代码里没有固定 seed 的话每次运行结果都会有细微差别最后查参数论文 Methods 里如果写了具体的 resolution 或者 n_neighbors确认自己有没有对齐。这次差异的根源最终定位在批次整合这一步——论文用的是另一种校正方式参数细节补充材料里没写全我用 Harmony 得到的结果在边界区域划分上略有不同属于可接受的合理差异。6.3 我最后的收尾动作复现验收通过之后我把整个环境固定了下来pip freeze requirements.txt所有脚本提交到 gitREPO.md 里的过程日志作为附录保留。这样做的目的很简单——这篇论文以后如果要更新数据或者被人问起复现细节我可以直接翻出这套记录重新跑一遍而不是靠记忆。最后分享一个这次踩了两次才记住的技巧跑长任务的时候不要让 Codex 一次性执行太多子任务再汇报。我试过让它一口气跑 T05 到 T08结果中间标准化参数理解偏了等到 T08 出图才发现回滚浪费了二十多分钟。正确的做法是每个子任务跑完就让它汇报结果和关键数值你扫一眼没问题再放行下一个。看起来多花了几次交互的时间实际上省掉的是整段返工的成本。这种每步确认的节奏才是用 agent 复现科研流程最省心的方式。