1. 为什么 codex 明明配好了 config.tomlskills 还是加载不出来如果你最近在 Windows 上折腾 codex并且接入了 DeepSeek 这类兼容 OpenAI 协议的模型服务大概率会碰到一个很迷惑的现象config.toml 看起来完全没问题模型也能正常对话但一进管理平台skills 列表里除了自带的 research-paper-writing其他自己下载的 skills 一个都不显示。我一开始也以为是 config.toml 写错了反复检查了 model、base_url、api_key 这些字段甚至把配置发给别的模型帮忙看反馈都是配置没问题。但 skills 就是识别不到。后来才定位到真正的原因codex 加载 skills 不是靠 config.toml 里声明路径而是靠一个固定的目录约定——它只认 config.toml 同级目录下的skills文件夹而且每个 skill 子目录里必须直接包含SKILL.md。这个场景其实很典型。codex 作为 Codex 的增强工具skills 机制是它扩展能力的关键但官方文档对目录结构讲得比较含糊很多人 git clone 下来一个 skills 仓库后直接把整个仓库文件夹丢进去结果多套了一层目录codex 扫描时找不到 SKILL.md就静默跳过了既不报错也不提示非常容易让人误判成配置问题。这篇就按从 config.toml 到 SKILL.md的顺序把排查路径和修复动作完整走一遍。适合已经装好 codex、接入了 DeepSeek 或其他兼容 API、但 skills 导入失败的人。核心结论先放这里config.toml 决定模型怎么连skills 目录结构决定 skill 能不能被加载两者是分开的。搞混这两件事就会一直在错误的方向上改配置。2. 前置准备TaoToken 接入与 codex 的 skills 目录约定在动手修 skills 之前先把模型接入这条链路确认清楚因为如果 API 本身不通skills 即使加载成功调用时也会失败容易把两个问题混在一起。codex 需要一个兼容 OpenAI Chat Completions 协议的服务端点。如果你用的是 DeepSeek 官方 APIbase_url 填https://api.deepseek.com如果你希望通过统一网关管理多个模型、方便切换可以用 TaoToken 的 API 端点https://taotoken.net/api它同样兼容 OpenAI 协议key 在控制台生成。TaoToken 在这里的作用是提供一个统一的 API 入口让你在 config.toml 里只维护一份 base_url 和 key就能切换不同模型。它的 API Key 在控制台的 API Keys 页面创建创建后复制出来填进配置即可。模型对话能力可以在模型对话页面直接验证确认 key 有效、模型可调用再去配 codex能省掉很多来回排查。关于 skills 的目录约定这是本篇的重点先讲清楚规则codex 启动时会去读 config.toml拿到模型配置同时它会扫描 config.toml所在目录下的skills子目录。注意是同级不是 config.toml 里写的某个路径。假设你的 config.toml 在D:\codex\config.toml那么 skills 根目录就是D:\codex\skills\。在这个skills目录下每一个 skill 必须是一个独立的子文件夹并且该子文件夹的第一层就要有SKILL.md。也就是说结构必须是D:\codex\ ├── config.toml └── skills\ ├── my-skill-a\ │ └── SKILL.md └── my-skill-b\ └── SKILL.md而不能是D:\codex\skills\ └── nature-skills\ - 多了一层仓库目录 └── skills\ - 又多了一层 └── my-skill-a\ └── SKILL.md后面这种就是最常见的失败原因。git clone 下来的仓库往往自带一层skills目录你如果整个复制进去codex 扫描D:\codex\skills\的第一层时看到的是nature-skills这个文件夹里面没有 SKILL.md于是判定无效跳过。research-paper-writing 之所以能用是因为它可能是内置的或者恰好被放在了正确层级。3. 可复制的 config.toml 骨架与 SKILL.md 最小示例先把 config.toml 的骨架给出来。下面这份是接入兼容 OpenAI 协议服务的最小可用配置字段名以 codex 实际读取为准你可以对照自己的改# D:\codex\config.toml model deepseek-chat base_url https://taotoken.net/api api_key sk-你的key # 对话参数 temperature 0.7 max_tokens 4096 # 部分版本支持显式声明 skills 根目录但即使不写 # codex 仍会默认扫描 config.toml 同级的 skills 文件夹 # skills_dir D:\\codex\\skills几个要点说明一下。base_url结尾不要带/v1还是带/v1取决于你用的服务TaoToken 的端点直接用https://taotoken.net/api即可具体以接入文档为准。api_key一定要用控制台生成的那串别把网页登录态当成 key。model字段填你要用的模型名DeepSeek 系列填deepseek-chat或对应版本名。如果你在 config.toml 里写了skills_dir但路径写错反而可能覆盖默认扫描逻辑导致连默认目录都不扫。所以排查阶段建议先注释掉 skills_dir让 codex 走默认的同级 skills 目录减少变量。接下来是 SKILL.md 的最小示例。一个能被识别的 skillSKILL.md 至少要有 frontmatter 和正文描述。最小可用版本--- name: my-skill-a description: 一个用于演示的最小 skill用于验证 codex 能否正确加载 --- # my-skill-a ## 用途 这个 skill 用于演示 codex 的 skills 加载机制。 ## 触发场景 当用户请求演示 skill 加载时使用。 ## 执行步骤 1. 读取用户输入 2. 返回确认信息frontmatter 里的name建议和文件夹名保持一致description写清楚用途codex 在列出 skills 时会读这两个字段。正文部分写清楚这个 skill 干什么、什么时候触发、怎么执行。内容可以简单但结构要完整否则有些版本会因为解析不到必要字段而跳过。把上面两个文件放好后目录应该是D:\codex\ ├── config.toml └── skills\ └── my-skill-a\ └── SKILL.md这是最小验证单元。先用这一个 skill 确认机制通了再去批量导入其他 skills出问题也好定位。4. 逐步验证从重启 codex 到确认 skills 被识别配置和文件都就位后按下面步骤验证每一步都有明确的预期结果哪一步不符合就停在那里排查。第一步确认文件层级。打开资源管理器进到D:\codex\skills\确认你看到的直接子项是各个 skill 文件夹而不是一个仓库文件夹。点进任意一个 skill 文件夹确认第一层就有 SKILL.md。这一步用眼睛看别靠记忆。很多人以为自己复制对了实际多套了一层。第二步完全退出 codex。注意是退出进程不是关窗口。Windows 下可以在任务管理器里确认 codex 相关进程都没了再重新启动。因为 skills 是在启动时扫描的不重启不会重新加载。第三步重启后进入 codex 管理平台查看 skills 列表。预期结果是除了 research-paper-writing你新放的 my-skill-a 也出现了。如果出现了说明目录结构和 SKILL.md 都对了。第四步用自然语言触发确认。在对话里输入请问我现在有哪些 skills 可以使用预期结果是 codex 列出当前加载的 skills包含你新加的。如果列表里还是没有回到第一步重新核对层级。第五步实际调用一次。输入类似用 my-skill-a 演示一下看它是否能正确进入该 skill 的逻辑。这一步能确认 skill 不只是被列出而是真的可执行。如果第三步就失败了先别急着改 config.toml因为问题几乎肯定在目录结构或 SKILL.md 上。可以临时把 skills 目录清空只留 my-skill-a 一个排除其他 skill 干扰。单个能通再逐个加回去。5. 本篇常见错误排查skills 不显示、SKILL.md 不生效、路径写错把排查过程中最容易踩的坑集中列一下对照着查能省不少时间。错误一skills 文件夹多套了一层。这是最高频的。git clone 下来的仓库通常长这样nature-skills/skills/xxx/SKILL.md。你如果直接把nature-skills复制进D:\codex\skills\codex 看到的第一层是nature-skills里面没有 SKILL.md跳过。正确做法是进到仓库的skills目录把里面的每个 skill 子文件夹单独复制到D:\codex\skills\下。错误二SKILL.md 不在第一层。有些 skill 的结构是my-skill/docs/SKILL.md或my-skill/src/SKILL.md。codex 只认 skill 文件夹第一层的 SKILL.md放在子目录里不生效。需要把 SKILL.md 移到 skill 文件夹根层或者调整目录结构。错误三文件名大小写或拼写不对。必须是SKILL.md不是skill.md、Skill.md、SKILLS.md。Windows 文件系统不区分大小写但 codex 内部匹配可能区分统一用大写最稳。错误四config.toml 里写了错误的 skills_dir。如果你手动指定了一个不存在的路径可能覆盖默认扫描。排查阶段先注释掉这一行。错误五改了文件没重启。skills 在启动时扫描改完必须完全退出再启动光刷新界面没用。错误六把模型接入问题和 skills 问题混在一起。如果 API key 无效对话本身就会报错这和 skills 不显示是两码事。先用模型对话确认 API 通再单独查 skills。错误七SKILL.md 的 frontmatter 格式错误。frontmatter 必须用---包裹且在第一行开始。如果前面有空行或 BOM 字符解析可能失败。可以用编辑器另存为 UTF-8 无 BOM 格式。排查顺序建议先看目录层级再看 SKILL.md 位置和文件名再看 frontmatter最后才怀疑 config.toml。因为实测下来九成以上的 skills 导入失败都是目录结构问题config.toml 反而是最不容易出错的。6. 修好之后把 skills 接入和长期编码工作流串起来skills 能正常加载后codex 的可用性会明显上一个台阶。你可以把常用的写作、代码审查、文档生成等 skill 都放进去用自然语言直接调用不用每次重复描述需求。如果你打算长期用 codex 做编码或 Agent 类任务建议把模型接入也固定下来。API Key 在控制台的 API Keys 页面管理接入细节看接入文档模型能力可以随时在模型对话里验证。对于需要长时间跑、频繁调用的编码场景Coding Plan 这类方案能减少反复配置的麻烦适合把 codex 当成日常工具的人。回到本篇的核心skills 导入失败先别怀疑 config.toml去D:\codex\skills\看一眼层级确认每个 skill 文件夹第一层有 SKILL.md重启 codex基本就恢复了。这个排查路径我走过一遍比改配置快得多。