企业官网建设流程全解析

1. 为什么 codex++ 明明配好了 config.toml，skills 还是加载不出来

如果你最近在 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 官方 API，base_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 的最小示例。一个能被识别的 skill，SKILL.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++，基本就恢复了。这个排查路径我走过一遍，比改配置快得多。