Codex 插件实战：三个 marketplace 怎么读、插件怎么装怎么停

2026-08-09

Codex（OpenAI Codex）的插件这块，最常见的翻车姿势不是装不上，而是装完之后一脸茫然：到底装没装上？装到哪个 marketplace 下面去了？为什么关掉之后好像还在？这几个问题的答案其实全在一条只读命令的输出里，只是那张表要会读。

下面这套流程，我在 codex-cli 0.147.0（Windows 11）上把只读部分逐条跑过；涉及安装、卸载这类会改动本地状态的动作，我会明确标出哪些是命令帮助里的原文、哪些是没实测的，不替它打包票。

一、先摸清家底，别急着装

任何插件问题的第一步都是这条：

codex plugin list

在 codex-cli 0.147.0（Windows 11）上，它的输出不是一张平表，而是按 marketplace 分组的：每组先打一行 marketplace 名字和这个 marketplace 对应的 marketplace.json 文件路径，然后才是四列表格。

<marketplace 名>   (<该 marketplace 的 marketplace.json 路径>)
PLUGIN             STATUS              VERSION    PATH
...

（上面是结构示意：列名 PLUGIN | STATUS | VERSION | PATH 与分组方式是实测所见，具体行内容和路径涉及本机信息，已略去。）

这个分组结构比四列本身更重要。它意味着同一个插件名在不同 marketplace 下是不同的条目，你排查”我装的到底是哪个”时，光看插件名不够，得看它挂在哪一组下面。

STATUS 列在 codex-cli 0.147.0（Windows 11）上我观测到两种取值：installed, enabled 和 not installed。注意第一种是两个状态拼在一起——installed 说的是本地有没有这份东西，enabled 说的是它现在起不起作用。这两件事是分开的，后面讲启停时会反复用到这个区分。

本机存在三个 marketplace：openai-primary-runtime、openai-bundled、openai-curated。

openai-bundled 这组下面我看到的条目名有：sites、browser、chrome、computer-use、visualize、latex。openai-curated 这组下面看到的是一批尚未安装的条目名：linear、atlassian-rovo、google-calendar、gmail、slack、teams、sharepoint、outlook-email、outlook-calendar、canva、figma、hugging-face、jam、netlify、stripe。

这里我要把话说死：这些名字我只是在 marketplace 列表里看见了，一个都没有安装、没有运行过。它们各自具体能干什么、需要什么授权、有什么限制，我没有验证过，所以本文不描述。你要用哪个，自己跑 codex plugin list 确认它在你机器上的 STATUS，再去官方对应文档页看能力说明。openai-primary-runtime 这一组本文不展开，本机记录里没有留下它的条目清单。

二、四个子命令，各管一段

在 codex-cli 0.147.0（Windows 11）上，codex plugin 有四个子命令，帮助里的职责划分是这样的：

子命令	帮助里的职责
`add`	从已配置的 marketplace 快照安装插件
`list`	列出插件（就是上面那张分组表）
`marketplace`	marketplace 本身的增、删、查、改与升级
`remove`	移除插件

add 那句说明里的”已配置的 marketplace 快照”是全篇最值得抠的一个词。它说明两件事：

第一，add 不是随便给个 URL 就能装的，它装的是你本地已经配置好的那几个 marketplace 里有的东西。所以想装一个当前三组里都没有的插件，正确顺序是先动 codex plugin marketplace 把源加进来，再回头 codex plugin add——顺序反了会白折腾。

第二，既然是”快照”，那本地这份清单就有新旧之分。marketplace 子命令的职责里明确带了”升级”，也就是说清单本身是需要刷新的。你在 plugin list 里看不到某个条目，先怀疑是快照旧了，而不是这东西不存在。

具体参数我不替你编。这四个子命令的完整选项，以你本机这个版本的帮助为准：

codex plugin --help
codex plugin add --help
codex plugin marketplace --help
codex plugin remove --help

我实测跑过的是 plugin list 这类只读命令，add/remove/marketplace 的实际参数格式和执行效果没有实测，所以只转述帮助里的一句话职责，不给伪造的示例命令。这一点请务必先 --help 一遍再动手。

三、启停是分层的，这才是”关不掉”的根源

插件在 Codex 里不是一个开关，是至少三层。理解这个分层，“我明明关了它怎么还在”就有答案了。

第一层：总闸。 插件整体受一个特性开关控制。在 codex-cli 0.147.0（Windows 11）上执行 codex features list，plugins 这一项的阶段是 stable，生效值 true。想临时关掉整个插件体系，顶层选项就够：

codex --disable plugins

按帮助里的说明，--enable <FEATURE> / --disable <FEATURE> 可重复出现，且等价于 -c features.<name>=true / =false。也就是说下面这条是同一件事：

codex -c features.plugins=false

第二层：单个插件的安装/启用状态。 就是 plugin list 里 STATUS 那两个词。not installed 是压根没装，installed, enabled 是装了且在用。这层归 plugin add / plugin remove 管。

第三层：插件自带的 MCP server。 这层最容易被忽略。官方《Configuration Reference》里有一组配置键叫 plugins.<plugin>.mcp_servers.<server>.*，管的正是插件自带的 MCP server 的启停与工具审批。也就是说，你可以不卸载整个插件，只把它带进来的某一个 server 停掉。

把这三层组合成一段配置，长这样：

# ~/.codex/config.toml

[features]
plugins = true                        # 总闸：0.147.0 上阶段为 stable
remote_plugin = true                  # 远程插件目录，官方默认 true
skill_mcp_dependency_install = true   # 允许提示并安装 MCP 依赖，官方默认 true

# 第三层：只停某个插件带进来的某一个 MCP server，插件本体不动
[plugins.my-plugin.mcp_servers.my-server]
enabled = false

逐条说为什么这几个键在这：

features.plugins：写出来是为了显式。默认值一般不需要写进配置，但插件出问题时，把总闸显式写死能排除掉”是不是被别的层改掉了”这个变量。
features.remote_plugin：官方标注默认 true，作用是启用远程插件目录。如果你的环境不希望走远程目录，这就是要动的那一个键，而不是去关总闸。
features.skill_mcp_dependency_install：官方标注默认 true，含义是允许提示并安装 MCP 依赖。装插件过程中出现依赖安装提示、而你所在环境不允许随便装东西，关它比关插件更精准。
plugins.my-plugin.mcp_servers.my-server.enabled：外科手术式停用。整插件留着，只掐掉某个 server。

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。my-plugin / my-server 是占位名，请换成你 plugin list 里实际看到的名字。另外，官方在 mcp_servers.<id> 那一节还列了 enabled、startup_timeout_sec（默认 10）、tool_timeout_sec（默认 60）、enabled_tools / disabled_tools 等键；插件自带 server 这一路径下具体可用哪些键位，请以官方《Configuration Reference》为准，我没有逐项验证过。

顺带提一个官方明写、但读名字容易搞反的规则：disabled_tools 是在 enabled_tools 之后套用的。两个都配的时候以 deny 为准。插件带的工具太多想做白名单时，别指望 enabled_tools 能盖过 disabled_tools。

四、改完怎么验收：三条只读命令，按顺序跑

配置这种东西，最坑的不是写错，是写错了还静悄悄的。按下面的顺序验收，能把大部分”改了没生效”挡住。

第一步，先确认配置到底加载成功了没有。

codex doctor --summary

在 codex-cli 0.147.0（Windows 11）上，我故意用 codex -c 'features=[unclosed' doctor --summary 传了一段语法不合法的 TOML。结果值得记住：命令没有崩溃退出，doctor 照常跑完，但输出里多了一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

这就是”改完配置没生效”的第一嫌疑人。TOML 括号少一个、引号漏一个，Codex 不会拦着你，它只是安静地不加载。所以改完 config.toml 第一件事永远是跑 doctor 看这一行。

doctor 的 Configuration 分组里还有一行 mcp，格式是 N server (N stdio) · N disabled（codex-cli 0.147.0 上实测）。这行值得顺手扫一眼，但要说清楚边界：插件自带的 server 是否计入这一行的 disabled 数，我没有验证过，以你本机改动前后两次 doctor 输出的差异为准——改配置之前先跑一次留个底，改完再跑一次对比，比听我下断言可靠。

第二步，回头看 plugin list。 STATUS 从 not installed 变成 installed, enabled 才算装上了。只看命令有没有报错不够。

第三步，看 MCP 侧。

codex mcp list

最容易出错的两步

一是 -c 传值被当成字符串。 帮助里写得很明白：-c 的 value 按 TOML 解析，解析失败则按字面字符串处理。所以 -c features.plugins=false 里那个 false 要是被你不小心加了引号，它就变成字符串 "false" 而不是布尔假，命令一声不吭地跑过去，效果却完全不同。嵌套键用点号路径，写成 foo.bar.baz。

二是别指望 --strict-config 能替你抓所有拼写错误。 它的职责是配置里出现本版本不认识的字段时报错退出。但在 codex-cli 0.147.0（Windows 11）上我跑 codex -c model_reasoning_effortt=high --strict-config exec --help（注意那个多打的 t），结果是正常打印 help，没有报未知字段错误。说明校验发生在真正加载配置去跑会话的路径上，--help 这类不进会话的路径不触发。拿 --help 当校验手段是无效的。

五、什么情况别这么干

别把插件当放宽权限的捷径。 插件跑起来之后到底还受不受沙箱与审批约束，我没有实测过，也没有在取到的官方文档里核到明确口径，所以这篇不给结论。但正因为没结论，就更不该默认它是一条能省掉审批的近路——真要确认，只能去看官方《Plugins》《Build plugins》这类专门页面，或者在你自己的受控环境里验。顺带把审批那档最容易读反的地方说清楚：approval_policy 三档里 never 的官方释义是”从不询问，执行失败直接回传给模型”——这不等于放开权限，是不再问你而已。真要收紧，approval_policy 除了写成字符串（粗粒度三档），还可以写成一张表用细粒度开关（比如 approval_policy.granular.mcp_elicitations 管 MCP elicitation 弹窗是允许还是自动拒绝）。想”只放行某一类弹窗”，字符串形式做不到，必须用表。

别凭 marketplace 里的名字推断能力。 上面那串 openai-curated 下的条目名，我一个都没装过。看名字猜功能，是插件这块最容易写出错误结论的地方。

受管环境别照搬本文。 官方文档索引里有一页《Plugin controls》属于企业与管理那一组，我没有取过它的内容，所以本文对企业受管场景不给任何做法。你所在的组织如果有统一配置下发，以那一页和你们管理员的口径为准。

桌面应用、Codex cloud、IDE 扩展那几个面本文不覆盖。 我只在 CLI 上跑过只读命令，那几个面的插件行为一律以官方文档为准。顺便说一个查文档的省事办法：官方任何文档页 URL 后面加 .md 后缀就能拿到 Markdown 版本，站点还提供 llms.txt（完整页面索引）和 llms-full.txt（合并全文），直接喂给工具比手翻网页快。

最后，版本号别用记忆里的。 采集这批素材时，同一台机器开头 codex --version 还是 codex-cli 0.131.0，十几分钟后再跑就成了 0.147.0，而 which -a codex 全程只有一个可执行文件。Codex 有自更新能力（配置里 check_for_update_on_startup 默认 true），所以”我昨天看到的和今天不一样”是正常的。排查插件问题时，第一句话永远是先跑一次 codex --version，用当次的实时输出，别用你以为的那个版本。