×−+
插件第 11 课 · Codex 教程
第 11 课 · PLUGINS

插件：
把整套本事打包带走

第 8 到 10 课，你给 order-admin 写了一个技能、接了 GitHub MCP、加了两个钩子。它们都在 order-admin 仓库里，拉下仓库就有；可团队还有别的仓库，换一个就得一样一样照着配。插件就是一个能安装的箱子：把这些装进去，别人点一下就装齐，不用每个仓库再配一遍。这一课先装别人做好的插件，再把你自己的这一套打包成 order-admin-kit。

约 35 分钟 11 节 · 5 个动手练习 章末测验 形式参考 luongnv89/claude-howto · 事实依据 OpenAI 官方文档
同事在另一个仓库里也想用这一套，要做几步？
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

时间紧就先看"入门"和"实战"：会装、会用、会打包。"原理"讲清单文件和分发，决定你做的插件同事装上能不能直接用。

01入门

插件是什么

插件是一个可以安装的包。装上一个，Codex 就多会几样本事。ChatGPT 和 Codex 共用同一个插件目录。

插件像新同事的入职套装操作手册、门禁卡、打卡机的设置装在一个箱子里。新人领一箱就齐了，不用挨个部门去要。
装上一个，就多一样本事官方举的例子：装 Slack 插件，它能总结频道、起草回复；装 Google Drive 插件，它能在 Drive、Docs、Sheets、Slides 里干活；装 Codex Security 插件，它能扫描你有权扫描的代码，确认可能存在的漏洞。

一个插件里能装四样东西

点每一样看看。前三课做的东西，正好对上其中三样。

不是每个插件都四样齐全

大多数插件只装其中一两样。除了这四样，插件还能带图标、截图这类素材，用来在插件目录里展示自己。

02入门

在哪能用

在 ChatGPT 桌面 App 的 Codex 里，插件装和用都最完整。IDE 扩展不支持插件，这一点和技能不一样。

入口能不能装装上以后
桌面 App · Codex
本教程主线		能 在 Plugins 页装新对话里就能用插件带的技能和 MCP 工具；插件带的钩子，你审查、信任以后才运行
Codex CLI
（命令行）		能 输入 /plugins 打开插件浏览器，从配置好的 marketplace 装开一个新会话后能用；在插件浏览器里按空格键开关已装的插件
IDE 扩展不能插件在 IDE 扩展里用不了，要去桌面 App 或 CLI 装。单独放在技能文件夹里的技能，IDE 扩展照样能用
ChatGPT 网页、手机
Chat 和 Work		能 网页上在 Plugins 页装；手机上用账号里已有的插件里的技能、远程 MCP 工具能用；钩子脚本不会跟着部署过去；标着 Desktop only 的插件用不了

在桌面 App 里装好的插件，ChatGPT 的 Chat、Work 和 Codex 都能用。公开插件只发布一次，ChatGPT 和 Codex 两边都搜得到。

标着 Desktop only 的插件只能在桌面 App 里装和用：网页上看得到，但要回到桌面 App 安装；手机上用不了。

用 API key 登录也能装吗

能。用 API key 登录 Codex 时，在桌面 App 和命令行里都能浏览、安装 OpenAI 精选的插件。个别插件的连接流程要用 API key 不支持的登录方式，这些就装不了。插件的用量在 OpenAI Platform 的 Usage 页查看。

03原理

技能是写法，插件是分发

官方用一句话说清两者的关系："Skills remain the authoring format; plugins are the installable distribution unit." 技能是你写流程用的格式，插件是把它装箱、发给别人安装的单位。

技能 = 书架上的一本操作手册写给 Codex 看的一套步骤。你在自己的技能文件夹里写、改、试，直到顺手（第 8 课）。
插件 = 封好箱、贴好标签的入职套装可以装几本手册，也可以连门禁卡（MCP 服务器）、打卡机（钩子）一起装。有名字、有版本，别人一装就齐。

什么时候做成插件

你的情况官方建议
还在反复打磨一个自己用的流程先写成技能，在技能文件夹里改
流程只跟一个仓库有关直接放在仓库的技能文件夹里，clone 下仓库的人都有
要分享给别人装；要把两个以上相关的技能打包；技能要配一个外部服务的连接；要给团队发一个稳定的能力做成插件
别人已经做好了类似的先装现成的插件，复用验证过的做法

插件的四种形状

形状什么时候选
只有技能说明写清楚，再用上 Codex 现有的工具就够了
只有 MCP 服务器需要 MCP 工具，不需要额外的流程说明
技能 + MCP 服务器要用技能带着 Codex 走完一套用到这些工具的流程
MCP 服务器 + 界面有一部分工作用可视界面操作明显更好

官方建议从够用的最小形状开始，以后再加 MCP 服务器或界面，插件的用途不用变。这张表没把钩子算进去；钩子可以和技能、MCP 服务器一起装进插件。本课的 order-admin-kit 是"技能 + MCP 服务器"，外加两个钩子。

04实战

练一练：写技能，还是做插件

6 个场景，每个选一种做法。选完会看到解析。

05入门

装一个现成的插件

打开 Plugins，挑一个，点 + 装上，开个新对话就能用。五步。

1
打开 Plugins（插件目录）目录按来源分成几栏：OpenAI（官方做的）、你的工作区（管理员提供的）、Personal（你个人 marketplace 里的，含 Created by me 和 Shared with me）。已经装的插件在单独的 Installed 一行。
2
搜索或浏览，打开详情，点 + 安装详情里会写这个插件能干什么。
3
需要连接就连接插件要连外部服务（MCP 服务器）时，会提示你连接、登录。有的安装时就要登录，有的等你第一次用时再提示。
4
开一个新对话官方的做法是装好以后开一个新对话再用：插件带的技能和工具，在新对话里可用。
5
直接说要做的事，或者打 @ 点名像"总结今天没读的 Gmail 邮件"这样直接说，它会从装好的插件里挑合适的。想指定，就在输入框打 @，选插件或插件带的某个技能。

下面是一个可以点的插件目录：切换来源、搜索、打开详情、安装、连接、卸载都能试。

Plugins
示意

插件名称和用途取自官方文档里的例子；"你的工作区"那一栏是虚构的示例；每个插件要不要连接、什么时候连接，以你 App 里的提示为准。

Sign in with ChatGPT Beta

部分合作方的插件（例如 Airtable、GitLab、HubSpot、Notion、Supabase、Vercel）连接时可以选 Sign in with ChatGPT，直接用 ChatGPT 账号在对方那边建号或关联。它只会把你的名字、邮箱和头像给对方，不会因此让插件读你的数据，也不会自动批准任何操作。插件要的权限，你还得单独审一遍。

命令行里输入 /plugins 打开插件浏览器：按 marketplace 分栏，能装、能卸，按空格键开关已装的插件，装完开一个新会话。

06原理

打开箱子看看：目录和清单

插件就是一个文件夹。最要紧的是清单文件 plugin.json，它说明"我是谁"；其余东西按固定位置放，Codex 自己会找到。

order-admin-kit/插件文件夹。清单里写的路径都相对于它，而且不能跑出这个文件夹。
plugin.json清单：名字、版本、说明。名字要稳定，用 kebab-case（小写字母加连字符），它既是插件的标识，也是里面各组件的命名空间。
skills/技能。一个技能一个子文件夹，里面是 SKILL.md，连同它用到的 scripts/、references/、assets/ 整个搬进来。放进来就会被自动发现。
mcp.json插件带的 MCP 服务器。装好以后，服务器由插件启动，你的配置管不着它的启动命令，但能开关它、调它的工具审批（第 10 节）。
hooks/hooks.json钩子配置，默认就在这个位置。脚本也放在 hooks/ 里，命令里用 ${PLUGIN_ROOT} 指向插件装好后的位置。
assets/素材：图标、logo、截图，在插件目录里展示用。

两种清单格式

现在有两种写法，Codex 都认。官方说新做的包应该用便携格式（Agent Plugins）；而 $plugin-creator 目前生成的是兼容格式。

便携格式兼容格式
清单在哪插件根目录的 plugin.json，开头写 $schema.codex-plugin/plugin.json
谁会生成自己手写（官方推荐新包用）$plugin-creator 目前生成这种；它一定会建的只有这个清单文件，其余文件按需生成
技能放进 skills/ 自动发现，清单里不用写清单里写 "skills": "./skills/"
MCP 服务器根目录 mcp.json，开头写 $schema，传输类型按便携格式写（例如 streamable-http）.mcp.json，由清单引用；传输类型是另一种写法（官方示例里是 http）
钩子默认 hooks/hooks.json；要换位置，写在 extensions.com.openai.hooks默认 hooks/hooks.json；要换位置，写在清单的 hooks
显示名、图标等写在 extensions.com.openai 里写在清单的 interface 等字段里
两个容易踩的坑

① 根目录 plugin.json 里一旦写了 extensions.com.openai，显示名、钩子路径这类 OpenAI 专属设置就只看它，.codex-plugin/plugin.json 里的这些设置整个不用了，两边不合并。名字、版本和 skills/、mcp.json 这些，不管哪种情况都以根目录的清单为准。② 别把 .mcp.json 直接改名成 mcp.json：便携格式开头要写 $schema，每个服务器的传输类型也要按便携格式写（例如 streamable-http），两种写法不一样。

便携格式下，skills/ 和 mcp.json 的位置是固定的，在清单里另写 skills 或 mcpServers 既不能替换、也不能增减它们。

找不到 $plugin-creator？

9 月 29 日的 CLI 更新说明写着：去掉了内置的 plugin-creator 技能。可插件打包的官方文档还在教"在 Codex 里用 $plugin-creator"，两边没对上。你的 Codex 里输入 $ 找不到它，就照上面表里的便携格式自己建：一个根目录的 plugin.json，加上 skills/ 等文件夹，也可以直接让 Codex 照这个结构帮你建。第 9 节的演练按文档里的流程演示。

07实战

装箱：做一个 order-admin-kit

把第 5–10 课做过的东西往箱子里装。点一张卡片装进去（电脑上也可以直接拖进箱子），再点一次拿出来；切换清单格式，看文件怎么变。有几张卡是装不进去的，试试看。

第 5–10 课做过的东西
order-admin-kitv0.1.0 

              

              

            

            
文件内容为示意：GitHub MCP 的地址是虚构的，技能和钩子沿用第 8、10 课的示例；目录位置、文件名、字段名与官方文档一致。

            
装好箱，把仓库里原来那几份移走
技能在 .agents/skills/、钩子在 .codex/hooks.json，是跟着 order-admin 仓库走的。打包以后它们还留在原处，同事拉取仓库、信任项目、再装上插件，就会有两份：钩子从项目和插件各加载一次，同一个钩子会跑两遍（prettier 跑两遍，.env 检查也跑两遍），审查、信任也得各做一次；技能也是仓库里一份、插件里一份，两份都可能出现在技能列表里。所以打包后，把 .agents/skills/add-api-endpoint/、.codex/hooks.json 里这两个钩子和 protect_env.py 移走，和插件一起提交（第 9 节演练第 6 步）。项目 .codex/config.toml 里第 9 课那段 [mcp_servers.github]，也可以把工具限制改写到插件的配置下（第 10 节），免得同一个服务配两份。

          


          
          

            

              08原理
              
放上货架：marketplace

              
做好的插件要放进一个 marketplace 才能安装。marketplace 就是一张货架清单：一个 JSON 文件，写着有哪些插件、各在哪个文件夹。

            

            

              
仓库 marketplace：跟着仓库走清单放在仓库的 .agents/plugins/marketplace.json，插件一般放在仓库的 plugins/ 下。拉下这个仓库的人都能在 Plugins 里看到它。

              
个人 marketplace：只有你自己清单放在 ~/.agents/plugins/marketplace.json，插件常放在 ~/.codex/plugins/。适合先在自己电脑上试。

            

            
加好或改了 marketplace 文件以后，重启 ChatGPT 桌面 App。在 Plugins 里，每个 marketplace 是一个可以选的来源，选中它就能装上面的插件。一个 marketplace 可以只放一个插件，也可以慢慢攒成你们团队自己的精选清单。

            
.agents/plugins/marketplace.json

            
    
              
  • name：货架的名字。配置里点名某个插件时写成 插件名@货架名，比如 order-admin-kit@order-admin。
    • 
              
  • interface.displayName：App 里显示的货架标题。
    • 
              
  • source.path：插件文件夹在哪。以 ./ 开头，相对于 marketplace 的根（这里是仓库根），不是相对于 .agents/plugins/。
    • 
              
  • policy.installation：AVAILABLE（可以装）、INSTALLED_BY_DEFAULT（默认装上）、NOT_AVAILABLE（不提供）。
    • 
              
  • policy.authentication：什么时候登录外部服务，ON_INSTALL（安装时）或 ON_USE（第一次用时）。每一项都要写 policy.installation、policy.authentication 和 category。
    • 
            

            
改了插件，要重启 App
App 安装插件时，会把它复制到 ~/.codex/plugins/cache/货架名/插件名/版本/（本地插件的"版本"这一级叫 local），之后用的是这份副本。所以改了插件文件，要重启 App，本地安装才会拿到新文件。

            
另外，.agents 文件夹即使在项目里也是只读的。让 Codex 写 marketplace 文件，默认档位下它会先停下来问你（第 9 节演练里会遇到）。


            
其他分发方式

            

              

                
方式给谁用怎么做

                
                  
发布到工作区工作区里你指定的角色要工作区管理员权限：在 ChatGPT 的 Plugins 页选 Personal，打开插件的 ⋯ 菜单，选 Publish，再选哪些角色能用。只在工作区里，不会进公共目录

                  
管理员导入 GitHub marketplace整个工作区（按角色）管理员在 Admin > Plugins 里导入，之后每天自动同步。管理员的事，这里只提一句

                  
提交到公共目录所有 ChatGPT 和 Codex 用户走 OpenAI 的插件提交和审核流程，上架后两边都能搜到

                  
命令行添加货架你自己的电脑codex plugin marketplace add owner/repo（命令行）

                
              

            

            
想给同事一个直达链接：codex://plugins/install/order-admin-kit?marketplace=order-admin 会打开这个插件的安装页；找不到这个货架或插件时，会打开 Plugins 页。


            
练一练：发给谁，走哪条路

            

            

          


          
          

            

              09实战
              
完整走一遍：装、用、打包、分享

              
先装一个现成的 Slack 插件用一用，再用 $plugin-creator 把你的东西打包成 order-admin-kit，最后看同事怎么装上。中途有三处要你拿主意，可以点允许，也可以点拒绝。

            

            

              

              
            

            
画面为教学示意：Slack 里的消息、issue 编号、提交号、测试数量和 Codex 说的话都是虚构的；插件目录的分栏、安装流程、清单位置、受保护文件夹的规则与官方文档一致。

          


          
          

            

              10深入
              
进阶与避坑

              
插件装得多了、做给团队用了，会碰到的事。

            

            
旧教程对照
    
              
  1. "每个插件都必须有 .codex-plugin/plugin.json"：这是 2026 年 3 月插件刚上线时的写法。现在新做的包推荐用根目录的 plugin.json（便携格式），.codex-plugin/plugin.json 作为兼容写法继续支持，$plugin-creator 目前也还生成它。
    2. 
              
  2. "IDE 扩展里也能装插件"：上线公告里这么写过，现在的文档写的是 IDE 扩展不支持插件，要在桌面 App 或 CLI 里装。
    3. 
              
  3. "Codex 有自己的一套插件目录"：现在 ChatGPT 和 Codex 共用一个插件目录，公开插件发布一次，两边都能搜到。
    4. 
              
  4. "在 Codex 里输入 @plugin-creator"：那是 ChatGPT 里的写法。在 Codex 里调用技能用 $plugin-creator。
    5. 
            


            
在配置里管插件

            
本地 marketplace 里的插件，可以在 config.toml 里单独开关，还能收紧它带的 MCP 服务器，不用改插件本身。键名写成 插件名@货架名。

            
.codex/config.toml（示意）
# 在这个仓库里开关插件；设成 false 就关掉，不用卸载
[plugins."order-admin-kit@order-admin"]
enabled = true

# 只放行插件里 GitHub MCP 的两个工具，而且每次用都先问
[plugins."order-admin-kit@order-admin".mcp_servers.github]
enabled_tools = ["get_issue", "list_issues"]
default_tools_approval_mode = "prompt"

            
项目里的 .codex/config.toml 只在信任的项目里加载（第 3、7 课）。这些设置管不到工作区管理员导入的插件，那些插件的开关由工作区决定。enabled_tools、disabled_tools、审批方式的含义和第 9 课讲的一样；工具名是示意。


            
常见问题

            

              
装了插件，Codex 好像不知道它
先开一个新对话试试：官方说插件带的技能和工具在新对话里可用。带 MCP 服务器的插件，还要先连接、登录才能用。也可以在输入框打 @ 直接点名这个插件试试。

              
插件里的钩子没有运行
    
                
  1. 插件带的钩子默认不信任，审查、信任之前会被跳过。命令行里用 /hooks 审查；App 里在哪审查，以你的 App 为准。
    2. 
                
  2. 信任是按钩子当时的内容记下的。插件更新后钩子内容变了，要重新审查。
    3. 
                
  3. 钩子脚本和它调用的程序，得在运行 Codex 的那台电脑上有。在网页上装插件，不会把脚本部署到任何地方。
    4. 
                
  4. 公司管理员可以设成只运行托管的钩子（allow_managed_hooks_only），这时插件带的钩子都不会运行。
    5. 
              

              
同一个钩子跑了两遍，技能也出现了两个
多半是打包以后，仓库里原来的 .codex/hooks.json 和 .agents/skills/ 没移走。钩子的规矩是：用户、项目、插件各处的钩子全部加载，谁也不覆盖谁，所以项目里一份、插件里一份，同一件事就做两遍。把仓库里原来那份移走，只留插件里的。

              
改了插件文件，装好的那份没变
App 用的是安装时复制到 ~/.codex/plugins/cache/ 下的副本。改完插件文件夹，重启 App。同事那边，拉取仓库后也要重启。

              
插件装多了，会不会影响 Codex
官方提醒：多个钩子和插件塞进上下文的内容会累加，可能让模型表现变差。做插件时，钩子的输出要尽量简短；用插件时，只装用得上的，暂时不用的可以关掉或卸载。

              
插件能拿我的数据做什么
插件的能力在 Codex 里运行时，照样受你的沙箱和审批规则约束（第 3 课）。连接外部服务，用的是那个服务自己的登录和权限，插件只能做你这个账号本来就能做的事。数据经 MCP 服务器发出去时，适用那家服务的条款和隐私政策。

              
为什么有的插件标着 Desktop only
比如管理员从 GitHub 导入的插件，只要在 mcp.json 或 .mcp.json 里声明了 MCP 服务器（哪怕是远程的 HTTPS 地址），就会被标成 Desktop only，只能在桌面 App 里用。

              
公司管着插件，我能做什么
工作区管理员可以按角色决定哪些插件可用、哪些默认装上；插件能不能用，和它带的 MCP 连接能做哪些操作，是分开管的。管理员装给你的插件，可能没有卸载按钮。管理员还可以关掉工作区里的插件分享（features.plugin_sharing = false）、限定能添加哪些 marketplace 来源。这些都是管理员的事，知道有就行。

              
Claude Code 里的插件能搬过来吗
App 的导入功能会把插件一起导进来，还需要补设置的会在导入完成的状态卡片里提示你（专题 D）。App 也能读仓库里 Claude 兼容的 .claude-plugin/marketplace.json；插件钩子的命令除了 PLUGIN_ROOT，还会拿到 CLAUDE_PLUGIN_ROOT，方便沿用已有的钩子脚本。

            

          


          
          

            

              11检验
              
小测验

              
8 道题，每题选完会立刻看到解析。