1. Codex Skill 部署前必须搞懂的目录结构与加载优先级Codex Skill 说白了就是一个以 SKILL.md 为核心的能力包你可以把它理解成给 Codex CLI 装的一个“插件说明书”——Codex 读到这份说明书就知道在什么场景下该调用哪些脚本、按什么步骤执行。它适合两类人一类是想把团队内部规范固化成可复用能力的开发者另一类是想让 Codex 自动完成重复性任务比如生成接口代码、跑数据校验的工程同学。我试过把几个常用脚本封装成 Skill 之后日常重复操作确实少了很多。在动手写 SKILL.md 之前先把目录规则搞清楚否则你写完发现 Codex 根本不加载排查起来很浪费时间。Codex CLI 加载 Skill 遵循“项目 用户 系统”的优先级也就是说同名 Skill 如果同时存在于多个层级项目级的会覆盖用户级和系统级。目录路径生效范围典型用途./.codex/skills/仅当前代码仓库团队共享可提交 Git~/.codex/skills/本机所有项目个人常用技能最常用/opt/codex/system/skills/全机器所有用户系统级公共能力这里有个容易踩的坑目录名就是技能 ID。比如你建了~/.codex/skills/api-generator/那这个技能的 ID 就是api-generator调用时写$.api-generator。目录名里不要带空格或中文否则 CLI 解析会出问题。一个完整的 Skill 目录长这样api-generator/ ├─ SKILL.md # 必填元数据 执行规则 ├─ scripts/ # 可选shell/python 执行脚本 ├─ references/ # 可选模板、参考文档 └─ assets/ # 可选配置、静态资源SKILL.md 是唯一强制要求的文件没有它 Codex 直接忽略整个目录。scripts 目录里的脚本会被 SKILL.md 正文引用Codex 执行到对应步骤时会去调用。references 和 assets 主要是给模型提供上下文素材比如代码模板、配置文件样例。加载优先级这件事在实际项目里很关键。假设你在~/.codex/skills/放了一个通用的api-generator但当前项目需要一套特殊规则你可以在项目根目录建.codex/skills/api-generator/Codex 会优先读项目里的这份。这样既不影响其他项目又能让团队通过 Git 共享同一套 Skill 配置。还有一点修改 SKILL.md 后不需要重启 CLI但需要新开一个 Codex 会话才会生效。因为 Skill 的元数据是在会话初始化时加载的当前会话里改文件不会热更新。这个机制和很多配置类工具一样理解之后就不会觉得奇怪了。2. TaoToken 前置配置让 Codex CLI 稳定跑通 Skill 调用Skill 部署本身不依赖特定网关但 Codex CLI 要真正跑起来、能调用模型执行 Skill 里的步骤你得先把 API 接入配好。TaoToken 在这里的角色是提供一个兼容的 API 入口让你用统一的 Base URL 和 Key 来驱动 Codex CLI。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先确认 Node.js 版本不低于 18然后全局装 CLInpm install -g openai/codex装完之后配置密钥。Codex CLI 支持环境变量和交互式登录两种方式用 TaoToken 的话推荐环境变量因为可以写进 shell 配置文件长期生效export OPENAI_API_KEY你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api如果你用的是 zsh把这两行加到~/.zshrcbash 就加到~/.bashrc。加完执行source ~/.zshrc让它生效。接下来验证 CLI 能不能正常连上。执行codex --version能输出版本号说明 CLI 装好了。然后跑一个最简单的对话测试codex 用一句话说明什么是 RESTful API如果返回了正常内容说明 Base URL 和 Key 都配对了。这一步很关键因为 Skill 执行过程中 Codex 需要多次调用模型如果基础接入不通后面 Skill 调试会一直报错你会分不清是 Skill 写错了还是网络问题。对于需要长期跑编码任务或 Agent 场景的同学可以考虑 Coding Plan它在频繁调用时更划算。入口在 https://taotoken.net/api 的 coding-plan 路径下具体可以看控制台里的说明。如果你只是想先验证模型对话是否正常用模型对话页面快速测一下就行。配置完成后建议把 Base URL 和 Key 的配置写进项目级的.env或者 shell profile避免每次开新终端都要重新 export。尤其是团队协作时把非敏感部分比如 Base URL写进项目文档Key 通过环境变量注入这样既方便又安全。3. 可复制配置SKILL.md 模板与 settings 片段这一节直接给你能复制粘贴的配置。先看 SKILL.md 的标准结构头部是 YAML 元数据正文是执行指令--- name: api-generator description: 根据参数自动生成 RESTful 接口代码 metadata: version: 1.0 author: your-name --- ## 触发规则 用户要求创建接口时自动启用本 Skill ## 执行步骤 1. 解析入参路由、请求方式、参数 2. 生成 TS/Express 接口代码 3. 输出文件到 src/routesname字段要和目录名一致description是 Codex 判断是否自动触发这个 Skill 的依据写得越具体隐式触发越准。metadata里的版本和作者信息是给你自己维护用的Codex 不强制要求但建议保留。如果你要做一个工具调用型 Skill需要在 YAML 里加functions配置用 JSON Schema 定义函数签名--- name: http-request description: 发起 HTTP 接口请求并返回结果 functions: - name: curl_api description: 发起 http 接口请求 parameters: type: object properties: url: type: string method: type: string enum: [GET, POST] ---对应的脚本放在scripts/curl_api.pyCodex 在需要调用时会自动执行。注意函数名要和脚本里的入口函数对应上。除了 SKILL.mdCodex CLI 本身也支持通过 settings 文件配置默认行为。在项目根目录建.codex/settings.json{ model: gpt-4o, baseUrl: https://taotoken.net/api, skillsDir: .codex/skills, enableFunctionCall: true }这个文件的作用是让项目内的 Codex 会话默认使用指定模型和 Base URL同时开启函数调用能力。skillsDir指向项目级 Skill 目录这样团队成员拉下代码后不用额外配置就能加载同一套 Skill。如果你用的是 TOML 格式的配置部分版本支持等价写法是model gpt-4o base_url https://taotoken.net/api skills_dir .codex/skills enable_function_call true三件套要记牢Base URL 填https://taotoken.net/apiKey 通过OPENAI_API_KEY环境变量注入Model ID 按你实际使用的模型填比如gpt-4o。这三项缺一不可尤其是 Model ID 写错的话请求会直接返回模型不存在的错误。部署落地命令也一并给你# 全局部署 mkdir -p ~/.codex/skills/api-generator cp -r ./my-api-tool/* ~/.codex/skills/api-generator/ # 项目局部部署 mkdir -p .codex/skills/api-generator cp -r ./my-api-tool/* .codex/skills/api-generator/复制完检查一下 SKILL.md 是否在目标目录根下ls ~/.codex/skills/api-generator/SKILL.md能列出文件就说明结构没问题。4. 验证请求与成功结果CLI 加载、调用与调试全流程配置写完之后最关键的一步是验证 Skill 到底有没有被加载。Codex CLI 提供了几个命令来查看和管理 Skill# 查看已安装技能 codex skill list # 添加注册技能 codex skills add ./技能目录 # 更新已部署技能 codex skills update ./技能目录 # 卸载删除技能 codex skills remove 技能名执行codex skill list后你应该能看到类似这样的输出Loaded skills: - api-generator (user) ~/.codex/skills/api-generator - http-request (project) ./.codex/skills/http-request括号里是生效层级后面是路径。如果列表里没有你刚部署的 Skill先检查目录名和 SKILL.md 是否存在再确认 YAML 头部有没有语法错误——YAML 对缩进很敏感多一个空格都可能导致解析失败。显式调用技能用$.技能名codex $.api-generator 帮我生成一个用户登录接口如果 Skill 正常加载Codex 会按照 SKILL.md 里的执行步骤逐步操作最后输出生成的代码文件。你也可以在启动时临时挂载单个 Skill不写入目录codex --instructions ./my-api-tool/SKILL.md这个方式适合调试阶段改完 SKILL.md 直接重新启动就能看到效果不用反复复制文件。对于函数调用型 Skill启动时需要开启函数调用开关codex --enable-function-call然后输入一个会触发函数的请求比如“帮我请求 https://example.com/api 的 GET 接口”Codex 应该会自动调用scripts/curl_api.py并返回结果。如果没触发检查 YAML 里的functions配置和脚本入口函数名是否一致。隐式自动触发是另一个验证点。你不需要写$.api-generator直接说“帮我创建一个订单查询接口”如果description写得够准Codex 会自动匹配并加载这个 Skill。实测下来description 里包含具体动作词如“生成接口代码”“发起 HTTP 请求”比泛泛的描述触发率高很多。调试过程中建议开一个单独的终端窗口跑codex另一个窗口改 SKILL.md每次改完新开会话测试。这样能快速定位是配置问题还是指令逻辑问题。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth部署 Skill 过程中遇到的报错大部分其实不在 Skill 本身而在 API 接入层。下面按真实报错逐个排查。401 Unauthorized最常见的原因是OPENAI_API_KEY没设置或设置错了。先确认环境变量echo $OPENAI_API_KEY如果输出为空说明没 export 成功。检查 shell 配置文件里有没有写对或者当前终端是不是新开的。另一个可能是 Key 本身失效了去控制台的 api-keys 页面重新生成一个。注意 Key 不要带多余空格或引号。local proxy failed这个报错通常出现在 Base URL 配置不对的时候。确认OPENAI_BASE_URL填的是https://taotoken.net/api不要多加路径或斜杠。有些同学会填成https://taotoken.net/api/v1这会导致请求路径拼接错误。改完环境变量后记得source一下再新开会话。reading choices 相关报错这类错误一般是返回体格式不符合预期常见于 Model ID 写错或模型不支持当前调用方式。检查 settings.json 里的model字段确认你填的模型 ID 在 TaoToken 的模型列表里存在。如果用的是函数调用型 Skill还要确认该模型支持 function calling。OAuth 相关报错如果你之前用过codex login做交互式授权后来又改了环境变量可能会出现凭证冲突。解决办法是清理旧的登录态codex logout然后重新用环境变量方式配置。OAuth 流程和 API Key 方式不要混用选一种保持到底。Skill 不加载codex skill list里看不到你的 Skill按这个顺序查——目录名是否合法、SKILL.md 是否存在、YAML 头部缩进是否正确、文件编码是否是 UTF-8。YAML 解析失败时 Codex 通常不会报明显错误只是静默跳过所以建议用在线 YAML 校验工具先过一遍。函数调用不触发检查--enable-function-call是否加了YAML 里functions的name和脚本入口函数是否一致参数 schema 是否合法。另外description 写得太模糊也会导致模型不调用改成明确的动作描述。排查时建议把 Codex 的输出日志级别调高或者在启动时加 verbose 参数这样能看到具体的请求和响应内容定位问题快很多。6. 长期编码与 Agent 场景的接入建议Skill 部署跑通之后如果你打算把它用在日常编码或 Agent 自动化里有几个实践建议。第一把常用 Skill 放在用户级目录~/.codex/skills/项目特有的放项目级.codex/skills/这样既能复用又不会互相干扰。第二SKILL.md 的 description 要随着使用不断打磨触发不准的时候优先改描述而不是改代码逻辑。对于需要频繁调用模型的场景Coding Plan 在成本上更有优势适合长期跑编码任务的开发者。接入文档在 https://taotoken.net/api 的 doc 路径下里面有完整的参数说明和示例。API Keys 管理在 console 的 api-keys 页面建议定期轮换。如果你用的是 Claude Code 或类似的 Agent 工具接入方式类似核心还是 Base URL、Key、Model ID 三件套配齐。ClaudeCodeAnthropic 相关的接入说明可以在文档里找到对应章节。最后提醒一点Skill 里的脚本不要直接连生产数据库或执行危险操作建议在脚本里加确认步骤或限制执行范围。Codex 自动调用时不会像人一样判断风险把安全边界写在 SKILL.md 的执行规则里比事后补救靠谱得多。