在 Codex 里敲/plugins翻插件详情、再回头读 Build Plugins 文档时最容易卡的不是安装按钮而是 Plugin 与 Skill 的边界到底怎么划。TaoToken 的思路很简单去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建一把 Key把 Codex 的 Base URL 填成 https://taotoken.net/api让那些解释plugin.json、marketplace.json的请求走统一 API 通道再继续往下读分发层。原文把 Codex 扩展体系拆成六层AGENTS.md 管项目级长期规则Skill 管某类任务的可复用工作流App/MCP 管外部系统能力Plugin 是可安装的分发单元Marketplace 是 Plugin 的 JSON Catalog最上面还有 Universal Plugin Directory 负责跨 Surface 分发。这六层很难一口气吃下来通常是一边开着官方文档一边在会话里追问这个字段归谁管一轮下来十几二十次请求很正常。问题也出在这里。会话越长越怕中途 401、越怕模型 ID 接不上思路断一次就得重新捡起plugin.json和marketplace.json的上下文。把模型出口固定住是读这套扩展架构之前最省事的一步。1. 边读 Plugin 文档边追问 Codex通道先别散1.1 读扩展体系时的请求密度比写业务代码还高对照官方 Build Plugins 文档解释 Plugin 结构本质上是一种高频短问看一眼目录树问一句skills 字段是相对谁解析看到.app.json再问一句它和.mcp.json有什么区别。这类对话的特点是每轮上下文都不长但轮次极多而且高度依赖连续性——上一轮刚把 Plugin 与 Skill 的职责对齐下一轮如果模型换了、报错了前面的铺垫基本白费。这也是很多人读 Codex 扩展文档读不下去的真实原因不是概念难而是通道不稳导致上下文反复重建。Plugin、Marketplace、Universal Plugin Directory 这三层本身是递进关系中间断一次就得从AGENTS.md → Skill → App/MCP → Plugin重新爬一遍。比较省心的做法是先把 Codex 的模型出口收敛到一个统一入口上。这样一来无论你是在解释plugin.json的最小 Manifest还是在核对$REPO_ROOT/.agents/plugins/marketplace.json的source.path请求都从同一条通道出去模型 ID 也不用每次手动切。1.2 结论先把 Base URL 固定再谈 Plugin 分层结论不绕弯如果你打算长时间对着 Codex 啃 Plugin、Marketplace 与通用插件目录先把模型通道换成统一 API。具体到操作就是三个动作——拿一把 Key、改~/.codex/config.toml、新开 Session 验证。Key 从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建Base URL 填 https://taotoken.net/api末尾不带/v1也不要挂任何查询参数。把这三步做完后面的技术章节才有稳定的对照环境。Plugin 的目录结构、Marketplace 的 Catalog 语义、/plugins安装后为什么要新开 Session这些讨论都需要连续的多轮问答通道一散讨论就变形。2. 对照 plugin.json 最小 Manifest 之前先创建一把 Key2.1 在 TaoToken 控制台拿到 YOUR_API_KEY打开 TaoToken注册登录后进控制台创建 API Key。拿到的字符串不要直接粘进对话窗口也不要提交到 Git后面所有配置里一律写成YOUR_API_KEY占位。顺手在模型广场看一下当前可用的模型 ID 写法记下来——这一步很关键因为 Codex 的model字段必须和通道侧实际支持的 ID 对得上抄别人博客里的旧 ID 是最常见的翻车方式。Key 拿到之后先别急着改配置文件先在模型对话页面发一条最普通的测试消息确认这把 Key 能通。如果这一步就失败后面改config.toml只会更乱。2.2 两个地址别混给人点的和给工具填的这是新手最容易混淆的地方值得单独拉一张表。落地页只用来注册、创建 Key、看模型广场和用量真正填进 Codex 的是接口地址两者不是一回事。用途地址注意事项注册、创建 Key、看模型广场、查用量https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end给人点的带 UTM 参数填进 Codex 的 Base URLhttps://taotoken.net/api末尾不加/v1不加 UTM把带 UTM 的落地页地址填进base_url请求会直接打歪反过来把接口地址当官网去点也看不到模型列表。记住一句话看模型和拿 Key 走落地页发请求走接口地址。3. ~/.codex/config.toml 里把 Codex 的模型出口指到统一通道3.1 model_provider 与 base_url 的正确写法Codex 用的是 TOML 配置不是环境变量套壳。打开~/.codex/config.toml把模型和供应商标成下面这样。注意字段名是model_provider供应商标里写base_url和env_key不要把这套东西和 Claude Code 的ANTHROPIC_*变量混用那两个工具的配置体系完全不同。model YOUR_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEYmodel里的YOUR_MODEL_ID以模型广场当时列表为准不要凭印象编一个带日期后缀的名字。配置里其它字段例如和流式、超时相关的部分保持你原来的写法不动只改上面这几行改动面越小出问题时越好定位。3.2 把 Key 放进环境变量别写进配置文件env_key声明的是变量名不是值。真正存 Key 的地方是 shell 环境。Linux / macOS 下在~/.zshrc或~/.bashrc里加一行Windows 用setxexport TAOTOKEN_API_KEYYOUR_API_KEY这里YOUR_API_KEY就是你在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 控制台创建的那串字符。变量名要和config.toml里的env_key完全一致大小写也算写错了启动就是 401报错信息还不会告诉你差在哪。写完之后重开一个终端echo $TAOTOKEN_API_KEY确认能打印出值再去启动 Codex。4. 用 plugin.json 当尺子量清 Plugin 与 Skill 的边界4.1 .codex-plugin/plugin.json 的最小结构把通道配通之后就可以安静地读结构了。一个 Codex Plugin 本质上是一个目录必须带.codex-plugin/plugin.json可以选带skills/、.app.json、.mcp.json、assets/。最小可用形态长这样{ name: my-first-plugin, version: 1.0.0, description: Reusable greeting workflow, skills: ./skills/ }官方要求name用稳定的 kebab-case因为它不只是给人看的显示名Plugin Host 会把它当作 Plugin Identifier 和组件命名空间使用。换句话说改名字等于改运行时身份不是换个标签那么简单。这一点在团队协作里尤其要注意名字一旦被引用改动成本就不只是一处字符串。4.2 plugin.json 管包SKILL.md 管能力很多人把这两个文件当成同一层的东西其实职责完全不同。SKILL.md顶部的 frontmatter 负责 Skill 的语义身份和路由回答这个任务该怎么做plugin.json负责包的身份、版本和组件位置回答哪些能力属于同一个可安装单元。engineering-productivity/ ├── .codex-plugin/ │ └── plugin.json └── skills/ ├── code-review/ │ └── SKILL.md ├── fix-ci/ │ └── SKILL.md └── release/ └── SKILL.md一个 Plugin 里塞多个 Skill 是常态因为团队标准包天然是一组工作流。这也解释了为什么 Plugin 和 Skill 不能互相替代Skill 是创作单位Plugin 是分发单位前者关心内容后者关心打包和安装。4.3 .app.json 与 .mcp.json 是两条不同的外部能力路径如果 Plugin 还要带外部能力有两条路。一条是.app.json指向已经注册好的 App / Connector 映射官方在 Plugin Builder 流程里会强调核对它是否映射到正确的 Connection ID另一条是.mcp.json直接携带 MCP Server 配置。两者最终都会给 Agent 提供外部 Tool但认证时机和生命周期不一样。这也是读文档时最容易被绕晕的地方。建议在会话里让 Codex 按文件 → 职责 → 何时认证三段式复述一遍确认自己理解的边界和文档一致再往 Marketplace 走。5. marketplace.json 的两个落点以及 source.path 的解析陷阱5.1 Repo Marketplace$REPO_ROOT/.agents/plugins/marketplace.jsonMarketplace 本质是一个 JSON Catalog它不包含 Plugin 的实现只告诉 Codex 有哪些 Plugin、在哪、能不能装、什么时候认证。项目级的默认落点是$REPO_ROOT/.agents/plugins/marketplace.jsonPlugin 通常放在$REPO_ROOT/plugins/下。{ name: local-example-plugins, interface: { displayName: Local Example Plugins }, plugins: [ { name: engineering-release, source: { source: local, path: ./plugins/engineering-release }, policy: { installation: AVAILABLE, authentication: ON_INSTALL }, category: Engineering } ] }这里有个非常容易踩的点source.path是相对 Marketplace Root 解析的不是相对.agents/plugins/目录本身。层级写错一个../Codex 就找不到 Plugin而报错往往只告诉你没找到不会指出路径基准错了。5.2 Personal Marketplace 与远程 Catalog用户级的 Marketplace 放在~/.agents/plugins/marketplace.json官方示例里 Plugin 目录常用~/.codex/plugins/但这只是示例路径不是强制规定——真正决定位置的是source.path。同一个 Catalog 既可以指向本地目录也可以指向 GitHub 仓库、Git HTTP/HTTPS 或 SSH 地址。Codex CLI 已经给了独立的 Marketplace 生命周期命令可以用来对照理解 Source Registry 这个概念codex plugin marketplace add owner/repo --ref main codex plugin marketplace add ./local-marketplace-root codex plugin marketplace list codex plugin marketplace upgrade marketplace-name codex plugin marketplace remove marketplace-name--ref用来固定 Git Ref--sparse可以做稀疏检出。从这些命令能看出来Marketplace 已经不是一个静态文件而是一套配置源 → 解析/快照 → Catalog → Plugin Entry的流程。理解了这一层再看$REPO_ROOT和~/.agents两个落点就不会觉得它们只是两个路径。6. 新开一个 Session验证通道和 /plugins 的生效链6.1 /plugins 安装之后为什么必须重开会话这一点官方文档写得很明确在 Codex CLI 里用/plugins安装 Plugin 后需要开始一个新的 Session才能使用它带进来的 skills 和 tools。原因是安装动作改变的是能力目录而当前会话的上下文在启动时就已经组装好了不存在热注入。安装、启用、可用是三个不同状态。配好通道之后正好用这件事做验证。重开一个 Codex Session把下面这句话发给它请按 Plugin → Skill → Workflow → Tool 的顺序说明在 Codex CLI 里用 /plugins 安装一个 Plugin 之后为什么要新开 Session 才能用到它带的 skills以及 Marketplace 的 source.path 是相对哪个目录解析的。如果它能连贯答出安装不等于当前上下文可见能力注册发生在会话初始化阶段这类内容并且没有报错中断说明请求确实走了你刚配的那条通道。6.2 回控制台对一下这次调用验证完之后回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的控制台看这次会话有没有正常记上用量。如果列表里出现了刚才那几轮请求说明 Key、环境变量、base_url三者都对上了如果一条都没有那问题一定在配置侧不用怀疑 Plugin 文档。对账这个动作很值得养成习惯。后面你会不断在读 Marketplace Catalog和读 Runtime 行为之间来回切换每次切换后对一眼用量能最快确认通道还活着。7. 配完之后真会撞上的几个报错7.1 401env_key 名字和实际变量对不上config.toml里写env_key TAOTOKEN_API_KEY结果 shell 里导出的是别的名字或者导出之后没重开终端就会出现 401。排查顺序是先echo变量有没有值再确认大小写完全一致最后确认 Codex 是从哪个 shell 启动的。Key 本身无效也会 401这时去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 重新创建一把更省时间。7.2 模型不存在别拿旧博客里的 ID 直接抄model字段填了一个通道侧没有的 ID表现通常是明确的模型不存在类报错。解决方式不是反复重试而是回到模型广场核对当前列表把 ID 换成真实存在的那个。名字里带不带日期后缀、带不带版本号各模型规则不同没有统一规律可猜。7.3 多写了 /v1 导致路径拼接错误base_url应该是https://taotoken.net/api末尾不要跟/v1也不要带任何查询参数。多写一段路径请求会被拼到一个不存在的端点上报错形式可能是 404也可能是别的业务错误但根因就在这一行。把base_url单独拎出来看一遍比逐行检查整个配置文件快得多。7.4 Plugin 装了但 skills 没出现这个报错和通道无关。先确认是不是没新开 Session再确认 Plugin 在/plugins里是不是处于 Enabled 状态——Available、Installed、Enabled 是三个不同状态只安装不启用能力不会进入目录。最后再检查marketplace.json里的source.path有没有指错基准目录。8. 通道稳了再往上读Marketplace 与 Universal Plugin Directory8.1 OpenAI / Workspace / Personal 三个来源Plugin Directory 把 Plugin 分成三类来源OpenAI 官方构建的、当前 Workspace 提供的、以及用户自己 Marketplace 里的。Workspace 发布的 Plugin 只属于当前组织不会自动进入公共目录所以它和公开目录里的 Plugin是两套东西。理解这条边界比记住 UI 上有几个标签页更重要。8.2 requirements.toml 与企业侧权限边界企业侧可以通过requirements.toml里的开关关掉 Workspace 的插件分享这说明 Plugin 已经进入治理体系。同样值得记住的是权限继承Plugin 里带 App不代表 Plugin 自己决定 App 权限已有 App 的策略——谁能访问、只读还是可执行、是否需要确认——都会继续生效。把这段读完你手上应该已经有了一条稳定的模型通道和一整套 Plugin 分层的对照框架。接下来最顺的路是先确认通道在业务场景下够用用同一把 Key 去 TaoToken 模型对话 发一条消息试模型 ID如果打算长期对着 Codex 啃 Plugin 和 Marketplace 文档、写 Manifest 和 Catalog可以看 Coding Plan 是否合适新的 Key 统一在 控制台 API Keys 创建。会话里反复调同一个模型做结构对照比来回换模型更省心。