1. Codex 装 skills 时最容易卡在哪Codex 的 skills 本质上就是一组放在~/.codex/skills下的文件夹每个文件夹里放SKILL.md加若干脚本或模板Codex 启动时会扫描这个目录把技能描述注入到上下文里。听起来简单但真正动手装的时候很多人会卡在三个地方一是 skills 目录结构和预期不一致克隆下来发现路径对不上二是 Codex 的模型通道没配好skills 装完了却调不动模型报 401 或超时三是settings.json和config.toml两个配置文件各管什么、字段怎么写网上说法不一。这篇就按「先解决通道、再装 skills、最后验证」的顺序走一遍。核心思路是用 TaoToken 的统一 Key 和 API 通道把 Codex 的模型调用先跑通再把 skills 放进目录这样出问题时能快速判断是配置问题还是技能本身的问题。适合已经在用 Codex、想装 taskmaster / todo-list-csv / skill-creator 这类常用技能但被配置卡住的用户。我试过把通道和 skills 分开调试效率比混在一起高很多。下面从 TaoToken 的前置准备开始。2. TaoToken 前置统一 Key 与 API 通道TaoToken 在这里的角色是提供一个统一的 API 入口和 KeyCodex 通过它调用模型不用在多个供应商之间来回切换配置。你需要先拿到一个可用的 Key然后把它写进 Codex 的配置里。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在控制台里可以查看额度、创建和管理 Key。第二步创建 API Key。直接进 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点新建复制生成的 Key。这个 Key 只显示一次建议先存到本地密码管理器里。第三步确认 API 基地址。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这个。Codex 里通常需要填 base_url 和 api_key 两个字段base_url 就写这个。注意Key 不要直接提交到 Git 仓库。建议用环境变量或者本地未跟踪的配置文件存放后面配置片段里我会用占位符sk-xxxx表示。如果你还想先确认模型能不能正常对话可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条测试消息能正常返回就说明 Key 和通道没问题再去配 Codex 会省很多排查时间。3. 可复制配置settings.json 与 config.toml 骨架Codex 的配置分两处settings.json一般管模型通道、Key、base_url 这类运行时参数config.toml管 skills 路径、工具开关、行为偏好。不同版本字段名可能略有差异下面给的是通用骨架你按自己版本微调。先看settings.json的写法。文件通常放在~/.codex/settings.json{ model_provider: taotoken, providers: { taotoken: { base_url: https://taotoken.net/api, api_key: sk-xxxx, model: claude-sonnet-4-20250514 } }, timeout_ms: 60000, max_retries: 2 }几个字段说明base_url固定填 TaoToken 的 API 地址api_key换成你自己的model按你实际要用的模型名填不确定就先填一个通用对话模型timeout_ms给 60 秒网络波动时不容易断max_retries设 2 次避免偶发失败直接报错。再看config.toml通常放在~/.codex/config.toml[skills] enabled true paths [~/.codex/skills] [tools] shell true file_edit true [behavior] auto_approve_read true auto_approve_write false[skills]段是重点enabled true打开技能扫描paths指向 skills 目录。如果你把技能放在别的地方改这里就行。[tools]控制 Codex 能用哪些工具shell和file_edit建议都开否则 skills 里的脚本跑不起来。[behavior]里读操作自动批准、写操作手动确认是个比较稳的默认。配置写完后把两个文件都保存。如果你用的是环境变量方式可以把api_key那行改成api_key: ${TAOTOKEN_API_KEY}然后在 shell 里export TAOTOKEN_API_KEYsk-xxxx。4. 安装 skills 并验证调用生效配置就绪后开始装 skills。以常用的三个技能为例taskmaster 做多步骤任务跟踪todo-list-csv 做轻量任务清单skill-creator 用来生成新技能骨架。先把仓库克隆到临时目录再把技能文件夹移进 Codex 的 skills 目录。# 1. 克隆仓库到临时目录 git clone https://github.com/lili-luo/aicoding-cookbook.git ~/.codex/temp_cookbook # 2. 确保 skills 目录存在 mkdir -p ~/.codex/skills # 3. 把三个技能移进 Codex 技能库 mv ~/.codex/temp_cookbook/skills/codex/taskmaster ~/.codex/skills/ mv ~/.codex/temp_cookbook/skills/codex/todo-list-csv ~/.codex/skills/ mv ~/.codex/temp_cookbook/skills/codex/skill-creator ~/.codex/skills/ # 4. 清理临时文件 rm -rf ~/.codex/temp_cookbook移动完成后检查目录结构ls -la ~/.codex/skills/正常应该看到taskmaster、todo-list-csv、skill-creator三个文件夹每个里面至少有一个SKILL.md。如果某个文件夹是空的说明克隆时路径不对重新确认仓库里的skills/codex/目录名。接下来验证通道和技能是否都生效。先做一次连通性测试用 curl 直接打 TaoToken 的 APIcurl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-xxxx \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: ping}] }如果返回里有正常的文本内容说明 Key 和通道没问题。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否写成了带路径的形式应该只到/api。然后启动 Codex让它读一次技能列表。在 Codex 会话里输入类似「列出当前可用的 skills」的指令正常会看到 taskmaster、todo-list-csv、skill-creator 三个名字。再让它执行一个简单任务比如「用 todo-list-csv 建一个包含三项任务的清单」如果它能生成对应的 CSV 文件说明技能调用链完整生效。5. 本篇常见错排查装 skills 过程中报错集中在几类逐个说。第一类skills目录不生效。Codex 启动后完全看不到技能。先确认config.toml里[skills]的enabled是truepaths路径没有拼错。路径里的~有些版本不展开建议写成绝对路径比如/Users/你的用户名/.codex/skills。改完重启 Codex。第二类401 Unauthorized。这是 Key 问题。检查settings.json里api_key有没有多余空格环境变量方式的话确认export在当前 shell 生效。如果 Key 是在控制台刚创建的确认没有复制到换行符。第三类连接超时。timeout_ms调大到 60000 或 90000。如果公司网络有出口限制确认能访问taotoken.net。这类问题不要用任何非正规网络手段处理直接检查本地网络和 DNS 即可。第四类技能脚本执行失败。Codex 能识别技能名但跑脚本报权限错误。给脚本加执行权限chmod x ~/.codex/skills/taskmaster/*.sh如果脚本是 Python确认本地 Python 版本满足SKILL.md里的要求。第五类config.toml解析报错。TOML 对格式敏感字符串必须用双引号数组用方括号。常见错误是paths [~/.codex/skills]少了引号改成paths [~/.codex/skills]。第六类模型名写错导致 400。model字段必须和 TaoToken 支持的模型名完全一致大小写和版本号都不能差。不确定就先在模型对话页面确认可用模型名再填回配置。排查时建议按「先 curl 验通道、再启动 Codex 验技能、最后跑任务验链路」的顺序每步单独确认不要一次改多个地方。6. 配好之后怎么继续用通道和 skills 都跑通后日常使用基本就是维护目录和按需加技能。新技能装法一样克隆或下载到临时目录把技能文件夹移进~/.codex/skills重启 Codex 即可。想自己写技能用 skill-creator 生成骨架改完SKILL.md里的描述和触发条件再放进目录。如果你后面要长期跑编码任务或者接 Agent 流程可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的编码场景。接入细节和字段说明可以查接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对 Codex 和 ClaudeCode 的配置示例。ClaudeCode 相关配置参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。最后提醒一句settings.json和config.toml改完一定要重启 Codex很多「配置不生效」其实是进程没重载。把这两个文件纳入版本管理时记得把 Key 抽成环境变量别把明文提交上去。
