1. 为什么直接让 Codex 生成 PPT 总是差点意思
很多人第一次用 Codex 做 PPT，流程大概是这样的：打开对话框，丢一句“帮我根据这篇论文做一份组会汇报 PPT”，然后等它吐出一个 pptx 文件。打开一看，标题字号忽大忽小，配色跟模板完全不搭，公式变成了一堆乱码字符，图片位置飘到页面外面。能用吗？勉强能看，但离“能直接拿去讲”还差得远。
问题不在于模型不够聪明，而在于缺少约束。基模直接生成 PPT 时，它不知道你的模板长什么样、不知道你要求多少页、不知道哪些内容该重点呈现。它只能凭训练数据里的“平均审美”去猜，猜出来的结果自然不稳定。
ppt-master这个 skills 项目解决的正是这个问题。它的思路是：把“怎么做一份合格 PPT”的流程拆解成结构化的指令，写进SKILL.md里；把“这个项目的工作规范”写进AGENTS.md里。Codex 在动手之前先读这两个文件，相当于拿到了一份详细的施工图纸，而不是凭感觉自由发挥。
这套组合适合谁？我梳理了三类：
第一类是学生和科研人员，需要把论文、实验数据快速转成组会汇报或答辩 PPT，页数固定、结构清晰、对模板还原度要求高。第二类是职场里需要频繁做汇报的人，周报、月报、方案评审，格式相对固定，重复劳动多。第三类是想研究 Agent 工作流的人，AGENTS.md+SKILL.md这种“规范文件驱动”的模式，本身就是当前 Agent 工程里很值得琢磨的设计。
但这里有个前置问题：Codex 默认走的是官方 endpoint，国内访问不稳定，而且 Key 的管理比较分散。如果你同时用多个模型或工具，每个都要单独配 Key、单独处理网络，维护成本很高。所以这篇的完整链路是：先把 Codex 的 endpoint 和 auth.json 统一改到 TaoToken 的 API 通道，再配置 AGENTS.md 和 SKILL.md，最后跑一次真实的 PPT 生成任务来验证 skills 有没有被正确加载。
下面按这个顺序一步步来。每一步都给可复制的配置，你跟着改就行。
2. 把 Codex 的 endpoint 与 auth.json 接到 TaoToken 统一通道
这一步是整个链路的地基。地基没打好，后面 skills 配得再对，请求也发不出去。
先解释一下 Codex 的认证机制。Codex CLI 和桌面端在发起请求时，会读取一个auth.json文件来获取 API Key，同时从配置里读取 Base URL（也就是 endpoint）。默认情况下，这两个值指向官方地址。我们要做的，就是把它们改成 TaoToken 的地址。
TaoToken 的 API 入口是https://taotoken.net/api，官网是https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。注意 API 地址后面不加任何参数，保持干净。
2.1 找到 auth.json 的位置
不同系统下，Codex 的配置目录不一样。你可以按下面的路径找：
| 系统 | 配置目录 |
|---|---|
| macOS / Linux | ~/.codex/ |
| Windows | %USERPROFILE%\.codex\ |
在这个目录下，你会看到auth.json和config.toml（或config.json）两个文件。如果auth.json不存在，手动创建一个。
2.2 写入 auth.json
auth.json的结构很简单，核心就是 API Key。把从 TaoToken 控制台拿到的 Key 填进去：
{ "OPENAI_API_KEY": "sk-你的TaoToken密钥" }这里有个坑要注意：Key 不要带多余空格，也不要加引号以外的字符。我见过有人从网页复制时带了个换行，结果请求一直 401，排查了半天。
2.3 配置 endpoint
接下来改 endpoint。在config.toml里加上或修改base_url：
model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" wire_api = "chat"如果你用的是config.json格式，对应写法是：
{ "model_provider": "taotoken", "model_providers": { "taotoken": { "name": "TaoToken", "base_url": "https://taotoken.net/api", "wire_api": "chat" } } }wire_api这个字段决定用哪种协议格式，chat对应的是标准的 Chat Completions 接口。如果你用的是 Responses 接口，改成responses。不确定的话先用chat，兼容性最好。
2.4 指定 Model ID
光有 endpoint 和 Key 还不够，还得告诉 Codex 用哪个模型。在config.toml里补上：
model = "gpt-4o" model_provider = "taotoken"Model ID 要跟你实际在 TaoToken 上开通的模型对应。写错了会报model not found。如果你不确定有哪些可用模型，可以去控制台看一下模型列表，或者直接用模型对话页面测一下。
到这里，三件套就齐了：Base URL + Key + Model ID。这三个值缺一不可，后面排查问题时也优先检查这三项。
2.5 验证配置是否生效
改完之后，别急着上 skills。先用一个最简单的请求验证通道是通的：
codex "用一句话说明什么是机器学习"如果返回了正常的中文回答，说明 endpoint 和 Key 都配对了。如果报错，先看错误类型：401 是 Key 问题，连接超时是 endpoint 问题，model not found 是 Model ID 问题。具体的排查方法放在第 5 节。
通道打通之后，我们再来看 AGENTS.md 和 SKILL.md 怎么配。
3. AGENTS.md 与 SKILL.md 的可复制配置片段
这一节是核心。很多人配了 endpoint 之后，直接把论文丢给 Codex，结果 skills 根本没被加载，生成出来的 PPT 还是老样子。原因通常是：AGENTS.md 和 SKILL.md 的路径不对，或者内容写得太模糊，Codex 读完之后不知道该干什么。
先讲清楚这两个文件的职责划分，这是理解整套机制的关键。
AGENTS.md是项目级的工作规范。它放在项目根目录，Codex 打开这个目录时会自动读取。它回答的是“在这个项目里，你应该怎么工作”——比如输出目录在哪、不要修改哪些文件、遇到不确定的情况怎么处理。
SKILL.md是具体技能的说明书。它放在skills/ppt-master/目录下，回答的是“做 PPT 这件事，具体分几步、每步产出什么、有什么约束”。它更像一份操作手册。
两者配合：AGENTS.md 定规矩，SKILL.md 定流程。
3.1 AGENTS.md 配置片段
在ppt-master项目根目录创建或编辑AGENTS.md，写入以下内容：
# AGENTS.md ## 项目说明 本项目用于根据论文和模板自动生成 PPT。 所有生成产物统一输出到 exports/ 目录。 ## 工作规范 1. 开始任务前，先读取 skills/ppt-master/SKILL.md，严格按其中的流程执行。 2. 输入资料放在 projects/ 目录，不要修改 projects/ 下的原始文件。 3. 不要修改模板文件本身，只读取其样式信息。 4. 中间产物放在 workspace/ 目录，优先复用已生成的中间文件。 5. 最终输出可编辑的 .pptx 文件到 exports/ 目录。 ## 约束 - 不逐句翻译原文，只提炼核心信息。 - 少用大段文字，多用图表、流程图、公式。 - 不需要向用户确认设计方案，直接执行。 - 不要反复尝试多个版本，一次生成到位。这份 AGENTS.md 的关键在于把“不要做什么”写清楚了。模型很容易“过度热情”，比如反复问你“要不要调整配色”“要不要换个版式”，或者把原始论文文件改得面目全非。把这些约束写进去，能省掉很多来回确认的时间。
3.2 SKILL.md 配置片段
在skills/ppt-master/SKILL.md里写入流程说明：
# SKILL: ppt-master ## 目标 根据输入论文和 PPT 模板，生成一份结构完整、风格一致的汇报 PPT。 ## 执行流程 1. 读取 projects/ 下的论文文件，提取研究背景、问题定义、核心方法、实验结果。 2. 读取 PPT 模板，记录其尺寸、字体、配色、标题版式和母版结构。 3. 按以下结构组织内容： - 研究背景与 Motivation - 问题定义 - 核心思想 - 方法框架 - 方法细节 - 实验设置 - 主要实验结果 - Ablation / 分析 - 优点与局限 - 总结 4. 生成页面时，优先复用模板的版式，不新建样式。 5. 公式、模型结构图、实验图重点呈现，单独占页。 6. 输出到 exports/ 目录，文件名格式为 汇报主题_日期.pptx。 ## 质量要求 - 页数控制在 15 页左右。 - 每页文字不超过 6 行，超出则拆页或转图表。 - 标题层级与模板保持一致。 - 不修改原始模板文件。3.3 目录结构对照
配好之后，你的项目目录应该长这样：
ppt-master/ ├── AGENTS.md ├── skills/ │ └── ppt-master/ │ └── SKILL.md ├── projects/ │ ├── 论文.pdf │ └── 组会汇报模板.pptx ├── workspace/ └── exports/workspace/和exports/如果不存在，手动建一下。Codex 在生成过程中会把中间文件写到workspace/，最终 pptx 写到exports/。
3.4 触发 skills 的提示词
配置就绪后，用自然语言告诉 Codex 要做什么。关键是在提示词里显式要求它读取这两个文件：
请读取 AGENTS.md 和 skills/ppt-master/SKILL.md， 使用 PPT Master Quick 模式完成任务。 输入资料：projects/论文.pdf PPT 模板：projects/组会汇报模板.pptx 制作一份 15 页左右的中文论文组会汇报 PPT。 要求： 1. 面向课题组组会。 2. 使用模板原有的尺寸、字体、配色、标题和版式风格。 3. 不修改原始模板文件。 4. 不逐句翻译论文，提炼核心信息。 5. 内容重点包括研究背景、问题定义、核心思想、方法框架、 方法细节、实验设置、主要实验结果、Ablation、优点与局限、总结。 6. 重要公式、模型结构和实验图重点呈现。 7. 少用大段文字，多用示意图、流程图、公式和图表。 8. 不需要向我确认设计方案。 9. 不要反复尝试多个版本。 10. 优先复用已经生成的中间文件。 11. 最终输出新的、可编辑的 pptx 到 exports 目录。这段提示词的作用是双重保险：既让 Codex 主动去读配置文件，又把关键约束在对话里再强调一遍。实测下来，这样 skills 被正确加载的概率明显更高。
4. 跑一次真实 PPT 生成任务验证 skills 加载
配置写完了，但“配了”不等于“生效了”。这一节用一个完整的任务来验证 skills 到底有没有被加载。
4.1 准备输入文件
我用的是一篇论文 PDF 和一个组会汇报模板 pptx。把这两个文件放进projects/目录：
mkdir -p projects workspace exports cp ~/Downloads/论文.pdf projects/ cp ~/Downloads/组会汇报模板.pptx projects/文件放好后，用 Codex 打开整个ppt-master项目目录。注意是打开目录，不是只打开单个文件。因为 AGENTS.md 是在项目根目录被读取的，如果只打开一个文件，Codex 的工作目录不对，就读不到配置。
4.2 发起生成任务
在 Codex 对话框里粘贴 3.4 节的提示词，回车。
接下来观察它的执行过程。如果 skills 被正确加载，你会看到它按顺序做这几件事：
第一步，读取AGENTS.md和SKILL.md。这一步在日志里能看到文件读取记录。
第二步，读取projects/下的论文和模板。它会先分析模板的尺寸、字体、配色，再提取论文的核心内容。
第三步，在workspace/下生成中间文件。可能是内容大纲、页面结构 JSON、或者提取出来的图表。
第四步，组装 pptx 并输出到exports/。
4.3 判断 skills 是否生效
怎么判断 skills 真的被加载了？看三个信号：
信号一：输出目录对不对。如果最终文件出现在exports/下，说明 AGENTS.md 里的输出规范被遵守了。如果文件散落在根目录或者projects/下，说明 AGENTS.md 没被读到。
信号二：页数和结构对不对。打开生成的 pptx，看页数是不是在 15 页左右，章节结构是不是按 SKILL.md 里定义的顺序来的。如果结构混乱、页数失控，说明 SKILL.md 没生效。
信号三：模板还原度。看字体、配色、标题版式是不是跟模板一致。如果生成的是默认白底黑字，说明模板样式没被正确读取。
我实测下来，配置正确的情况下，生成的 PPT 在结构完整度和模板还原度上都能达到“稍作调整就能用”的水平。公式和图表会单独占页，文字密度也控制得比较好。当然，细节上肯定不如人手精修，但效率差距是数量级的。
4.4 中间产物复用
workspace/目录里的中间文件值得留意。如果你对结果不满意，想调整某几页，不需要从头再跑一遍。直接告诉 Codex“复用 workspace 里的中间文件，只重新生成第 5 到第 8 页”，它会基于已有产物做增量修改。这也是 AGENTS.md 里“优先复用中间文件”那条规范的价值所在。
生成完成后，去exports/目录拿最终的 pptx 文件，用 PowerPoint 或 WPS 打开检查一遍。重点看公式有没有乱码、图表有没有错位、字体有没有回退。有问题的话，针对具体页面提修改要求就行。
5. 常见报错排查：401、local proxy failed 与 skills 未加载
配置过程中最容易卡住的几个点，我按报错类型整理一下。遇到问题先对照这里查。
5.1 401 Unauthorized
这是最常见的报错，意思是认证失败。原因通常有三个：
Key 写错了。检查auth.json里的OPENAI_API_KEY值，确认跟 TaoToken 控制台里的一致。注意不要有多余空格或换行。
Key 没生效。改完auth.json后，Codex 可能需要重启才能重新读取。把 Codex 完全退出再打开。
Key 权限不对。确认这个 Key 有调用目标模型的权限。有些 Key 是限定模型范围的。
排查命令：直接用 curl 测一下 Key 是否有效：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}]}'如果这个命令返回正常，说明 Key 和 endpoint 都没问题，问题出在 Codex 的配置读取上。
5.2 local proxy failed
这个报错说明 Codex 尝试走本地代理，但代理没起来或者配置冲突。常见原因是环境变量里残留了代理设置。
检查一下：
echo $HTTP_PROXY echo $HTTPS_PROXY如果有值，而且你不需要代理，清掉：
unset HTTP_PROXY unset HTTPS_PROXYWindows 下用set HTTP_PROXY=清除。清完之后重启 Codex。
还有一种情况是config.toml里同时配了多个 provider，Codex 不知道该用哪个。确认model_provider指向的是你配好的那个。
5.3 reading choices 相关报错
这个报错通常出现在响应格式解析阶段，提示读取choices字段失败。原因一般是wire_api配错了。
如果你用的是 Chat Completions 接口，wire_api应该是chat；如果用的是 Responses 接口，应该是responses。两者返回的 JSON 结构不同，配错了就会解析失败。
改法：在config.toml里把wire_api改成正确的值，重启 Codex。
5.4 OAuth 相关报错
如果你之前用官方账号登录过 Codex，本地可能残留了 OAuth token。切换到 API Key 模式后，这个 token 会跟新的认证方式冲突。
解决办法：找到~/.codex/下的 token 缓存文件（通常叫tokens.json或类似名字），删掉或重命名。然后确保auth.json里只有 API Key，没有 OAuth 相关字段。
5.5 skills 没被加载
这个不算报错，但结果不对。表现是：生成的 PPT 结构混乱、页数失控、模板样式丢失。
排查顺序：
先确认AGENTS.md在项目根目录，SKILL.md在skills/ppt-master/下。路径错了就读不到。
再确认 Codex 打开的是项目目录，不是单个文件。工作目录不对，相对路径就找不到。
最后确认提示词里显式要求了“读取 AGENTS.md 和 SKILL.md”。有些情况下模型不会主动去读，需要你明确要求。
如果以上都对还是不行，在提示词里把 SKILL.md 的关键流程直接贴进去，作为兜底。
5.6 模型返回空内容
偶尔会遇到请求成功但返回内容为空的情况。先检查 Model ID 是否正确，再检查请求参数里max_tokens是不是设得太小。如果都没问题，换个模型试试，排除是单个模型的问题。
排查的时候记住一个原则：先验证通道，再验证配置，最后验证 skills。通道用 curl 测，配置看文件路径和内容，skills 看输出结果。按这个顺序，大部分问题都能定位到。
6. 把这条链路用顺之后的几个实用建议
走到这里，Codex + ppt-master skills + TaoToken 的完整链路应该已经跑通了。最后分享几个我踩过坑之后总结的实用点。
模板文件要选对。模板的母版结构越清晰，生成效果越好。如果模板本身版式混乱，模型读取样式时也会受影响。建议用结构规整的模板，标题、正文、图表占位符都定义清楚。
论文内容别太长。如果论文超过 30 页，模型提取核心信息时容易遗漏重点。可以先把论文的关键章节摘出来，或者分批次喂给 Codex。SKILL.md 里定义的章节结构，本质上就是在帮你做信息压缩。
中间文件是你的朋友。workspace/里的产物不要随手删。想调整某几页的时候，复用中间文件比从头生成快得多，而且风格更统一。
Key 管理要集中。如果你同时用多个工具，建议都统一走 TaoToken 的通道。这样 Key 只需要维护一份，换模型的时候改一个 Model ID 就行，不用每个工具单独配。控制台里可以管理 API Keys，接入文档里有各工具的配置示例。
长期做汇报的话，考虑 Coding Plan。如果你不是偶尔做一次 PPT，而是每周都有汇报任务，频繁调用模型的话，可以了解一下 Coding Plan 的额度方案，比按次调用更划算。
验证模型能力用模型对话。不确定某个模型适不适合做 PPT 生成，先去模型对话页面丢一段论文试试，看它的结构化输出能力怎么样。选对模型，后面的事半功倍。
这套流程的核心价值不在于“全自动”，而在于把重复劳动压缩掉。你依然需要检查内容、调整细节，但从“从零开始做 15 页 PPT”变成“在生成结果上改 3 页”，时间差距是实打实的。配置一次，后面每次做汇报都能省下大量时间。
