1. 从 SKILL.md 到工具调用Codex 工具链路到底卡在哪很多人第一次用 Codex CLI 跑带 Skill 的任务时都会遇到一个很迷惑的现象明明SKILL.md写得好好的description也写了脚本也放在scripts/里了但 Codex 就是不动手要么回你一段我可以帮你打开浏览器的文字要么干脆答非所问。你以为是模型不够聪明其实大概率是链路里某一层没接上。Codex 的工具调用链路可以拆成三层Skill 声明层、Agent Runtime 调度层、工具执行层。Skill 声明层负责告诉 Runtime我有什么能力、什么时候该用我Agent Runtime 调度层负责发现 Skill、判断触发、按需加载正文、把工具接口暴露给模型工具执行层才是真正跑 shell、读文件、开浏览器的地方。三层里任何一层断了模型都只能嘴上说说。这篇文章面向需要在本地复现 Codex 工具调用流程的开发者。我会给出一个可跑的SKILL.md示例、Agent Runtime 侧的工具注册片段以及把 Codex 的 Base URL 改到 TaoToken 统一 Key/API 通道后的可复制配置最后做一次端到端调用验证。核心检索词就三个Skill 是什么、Agent Runtime 怎么调度、Codex 工具调用链路怎么打通。适合谁适合已经能跑通 Codex CLI 基础对话、但一上 Skill 就翻车的同学。先说结论Skill 不是插件程序它是一个能力包Codex 不是自己会执行命令是 Runtime 把工具接口递到它手里。理解这两句话后面所有配置你都能自己推出来。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在动 Skill 之前先把模型通道理顺。Codex CLI 默认走的是官方通道但如果你要在本地做多模型对比、或者想让 Skill 链路里的模型调用走统一入口把 Base URL 改到 TaoToken 是更省事的选择。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。前置准备分三步拿 Key、配环境变量、验证通道。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面新建一个 Key复制出来。这个 Key 后面会同时被 Codex 主模型调用和 Skill 链路里的辅助调用复用所以别到处散落统一放环境变量。第二步配置环境变量。Codex CLI 读取的是OPENAI_API_KEY和OPENAI_BASE_URL这两个变量不同版本可能略有差异以你本地codex --help为准。在~/.zshrc或~/.bashrc里加export OPENAI_API_KEYsk-你的TaoTokenKey export OPENAI_BASE_URLhttps://taotoken.net/api改完执行source ~/.zshrc让它生效。这里有个坑如果你之前配过官方 Key一定要确认新变量覆盖了旧的否则 Codex 会继续走老通道你会以为是 Skill 的问题其实是通道没切。第三步验证通道。用 curl 打一次模型列表或对话接口确认 Key 和 Base URL 都对curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices字段就说明通道通了。如果返回 401先别怀疑 Skill先回去检查 Key 有没有复制全、有没有多余空格。这一步过了再进 Skill 配置。如果你还想在浏览器里直接对比不同模型对同一段 Skill 描述的理解差异可以用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 手动测几轮确认 description 写得够不够清楚。这个动作看着多余但能帮你提前排掉Skill 描述太泛导致不触发的问题。3. 可复制配置SKILL.md 示例与 Agent Runtime 工具注册片段这一节是全文最硬的部分直接给可复制的配置。先建目录结构skills/ └── bilibili-browser/ ├── SKILL.md ├── agents/ │ └── openai.yaml └── scripts/ └── open_bilibili.shSKILL.md的 frontmatter 决定会不会被触发正文决定触发后怎么做。示例--- name: bilibili-browser description: 当用户要求打开 bilibili、在 bilibili 搜索关键词、或用指定浏览器访问 bilibili 时使用。典型输入包括帮我打开 bilibili用 firefox 打开 bilibili去 bilibili 搜索 杨旭游记。 --- # bilibili-browser ## 用途 在真实桌面浏览器中打开 bilibili支持直接打开首页或带关键词搜索。 ## 工作流 1. 解析用户意图判断是打开首页还是搜索。 2. 如果是搜索提取关键词。 3. 调用 scripts/open_bilibili.sh传入 --keyword 参数。 4. 如果脚本返回非零退出码向用户报告失败原因不要重试超过一次。 ## 参数 - --keyword: 搜索关键词可选。不传则打开首页。 - --browser: 指定浏览器可选默认系统默认浏览器。 ## 回退 如果脚本找不到浏览器 opener提示用户手动打开并给出拼接好的 URL。agents/openai.yaml是给 UI 和产品层用的元数据不参与执行逻辑display_name: Bilibili Browser short_description: 在桌面浏览器打开 bilibili 或搜索关键词 default_prompt: 帮我打开 bilibiliscripts/open_bilibili.sh把脆弱逻辑收敛进脚本别让模型每次临场拼命令#!/usr/bin/env bash set -euo pipefail KEYWORD BROWSER while [[ $# -gt 0 ]]; do case $1 in --keyword) KEYWORD$2; shift 2 ;; --browser) BROWSER$2; shift 2 ;; *) echo unknown arg: $1 2; exit 2 ;; esac done if [[ -n $KEYWORD ]]; then ENCODED$(python3 -c import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1])) $KEYWORD) URLhttps://search.bilibili.com/all?keyword${ENCODED} else URLhttps://www.bilibili.com fi if [[ -n $BROWSER ]]; then exec $BROWSER $URL fi if command -v open /dev/null 21; then exec open $URL elif command -v xdg-open /dev/null 21; then exec xdg-open $URL else echo no browser opener found, url$URL 2 exit 3 fi给脚本加执行权限chmod x skills/bilibili-browser/scripts/open_bilibili.sh。接下来是 Agent Runtime 侧的工具注册片段。Codex 的 Runtime 会扫描 skills 目录解析每个SKILL.md的name和description建立索引。如果你用的是支持自定义工具注册的 Runtime注册片段大致长这样以 JSON 配置为例{ skills_dir: ./skills, tools: [ { name: shell, enabled: true, allowlist: [bash, sh, python3], timeout_ms: 15000, max_output_bytes: 65536 }, { name: file_read, enabled: true, root: ./skills } ], skill_loading: { mode: lazy, load_body_on_trigger: true } }这里三个字段最关键skills_dir告诉 Runtime 去哪扫 Skilltools里的shell是模型真正能调用的执行接口skill_loading.mode设成lazy表示先只加载元信息触发后才读正文避免上下文被撑爆。如果你用的是 Codex CLI 的config.toml风格配置等价写法是[model] base_url https://taotoken.net/api api_key_env OPENAI_API_KEY [skills] dir ./skills lazy_load true [tools.shell] enabled true timeout_ms 15000注意base_url和api_key_env这两行就是把 Codex 的模型调用统一到 TaoToken 通道的地方。Key 不写死在配置里走环境变量避免泄露。4. 验证请求一次端到端工具调用怎么跑通配置写完必须做一次端到端验证否则你永远不知道断在哪一层。验证分四步确认 Skill 被发现、确认触发判断、确认正文加载、确认工具执行。第一步确认 Skill 被发现。在 Codex CLI 里输入一个能列出可用 Skill 的命令不同版本命令不同常见是/skills或codex skills list。如果列表里没有bilibili-browser说明skills_dir路径不对或者SKILL.md的 frontmatter 格式有问题。frontmatter 必须是文件开头第一段---包裹的内容前面不能有空行或注释。第二步确认触发判断。输入帮我打开 bilibili观察 Runtime 日志。正常情况你会看到类似skill candidate matched: bilibili-browser的记录。如果没有匹配回去改description把用户可能的表达方式都写进去。这一步是纯语义匹配模型不参与所以 description 写得越贴近真实口语越好。第三步确认正文加载。触发后 Runtime 会读取SKILL.md正文并注入上下文。日志里会出现loading skill body: bilibili-browser。如果卡在这检查文件编码是不是 UTF-8有没有 BOM 头。第四步确认工具执行。模型应该生成类似这样的调用bash skills/bilibili-browser/scripts/open_bilibili.sh --keyword 杨旭游记执行后浏览器打开 bilibili 搜索结果页Runtime 把执行结果回传给模型模型再告诉你已经打开了。整条链路走完你会看到从用户输入到浏览器弹出的完整过程。如果想让验证更可控可以先用一个不依赖浏览器的 Skill 测比如一个只做echo的 Skill确认 Runtime 调度和 shell 工具都正常再换成浏览器 Skill。这样排障时能快速定位是调度问题还是执行问题。验证通过后如果你打算长期跑编码类 Agent 任务可以考虑用 Coding Plan 把额度固定下来入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。短期验证用按量 Key 就够别一上来就上套餐。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth链路跑不通时报错信息往往指向不同层。下面按真实报错对照排查。401 Unauthorized。这是通道层问题不是 Skill 问题。原因通常是OPENAI_API_KEY没生效、Key 复制不全、或者 Base URL 写成了带 UTM 的地址。检查两点echo $OPENAI_API_KEY有没有值OPENAI_BASE_URL是不是https://taotoken.net/api注意结尾不要多加/v1具体以你 Runtime 文档为准。改完记得重开终端环境变量不会自动刷新到已运行的进程。local proxy failed / connection refused。这是网络层问题。先确认本机能访问https://taotoken.net/api用 curl 打一次。如果 curl 通但 Codex 不通检查 Codex 配置里有没有残留的代理设置或者config.toml里base_url被别的配置覆盖了。还有一种情况是 Runtime 启动时读的是旧配置重启 Codex 进程即可。reading choices 报错 / choices 字段为空。这是响应解析层问题。通常是模型名写错了或者请求体格式不对。Codex 内部会构造请求如果你在 Skill 里让模型生成额外的模型调用要确保model字段是 TaoToken 支持的模型 ID。用 curl 单独打一次确认返回结构再对比 Codex 日志里的请求体。OAuth 相关报错。Codex 某些版本会走 OAuth 登录流程如果你已经改用 API Key 通道需要在配置里显式关闭 OAuth否则它会尝试走登录流程然后失败。检查配置里有没有auth_mode之类的字段设成api_key。这一步不做你会看到 OAuth 报错但完全不知道和 Skill 有什么关系。Skill 不触发。这不是报错但最常见。排查顺序Skill 目录在不在skills_dir下SKILL.mdfrontmatter 的name和description有没有解析成功description 是否覆盖了用户的表达方式。我试过把 description 写成打开浏览器结果用户说帮我访问 bilibili就不触发改成包含访问打开搜索三个动词后才稳定。脚本执行超时。Runtime 的timeout_ms设太短或者脚本里有阻塞操作。把超时调到 15000 以上脚本里避免交互式输入。排障时记住一个原则先分层再定位。通道层看 401 和连接错误调度层看 Skill 是否被发现和触发执行层看脚本退出码和输出。三层分开测比盯着一个报错瞎猜快得多。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置字段不确定时对着文档核对。6. 把链路固定下来从一次性验证到可复用接入一次端到端跑通只是开始真正省事的是把这条链路固定成可复用的接入方式。我的做法是把三样东西版本化SKILL.md、Runtime 配置、环境变量模板。前两个进 Git第三个用.env.example占位真实 Key 只放本地。环境变量模板长这样# .env.example OPENAI_API_KEYsk-your-taotoken-key OPENAI_BASE_URLhttps://taotoken.net/api新机器上克隆仓库后复制成.env填真实 Key再source一下就能跑。这样 Skill 链路和模型通道解耦换机器、换模型都不用改 Skill 本身。如果你要接多个 Skill建议按能力域分目录比如skills/browser/、skills/file/、skills/api/Runtime 的skills_dir支持递归扫描。每个 Skill 的 description 保持互斥避免两个 Skill 抢同一个触发场景。抢触发比不触发更难排因为日志里两个都匹配模型选哪个不确定。最后一步是把 Key 管理收口。所有模型调用不管是 Codex 主循环还是 Skill 里的辅助调用都走同一个 TaoToken Key。这样额度、日志、限流都在一个地方看出问题不用满世界找 Key。API Keys 管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要轮换 Key 时在这里操作轮换后更新本地.env即可Skill 配置不用动。链路固定下来之后你会发现加新 Skill 的成本很低写一个SKILL.md、放一个脚本、重启 Runtime就能用。模型负责决策Runtime 负责调度Skill 负责把可靠做法沉淀下来这三层各司其职才是 Codex 工具调用真正跑顺的样子。