Appearance
要使 Codex 模式的 OpenClaw agent 使用原生 Codex 插件，需要通过迁移将已有的 openai-curated 插件导入到目标 Codex 应用服务器，并在网关配置中正确设置 codexPlugins。迁移支持 dry-run 预览和严格源应用验证，之后可通过 /codex plugins 命令在聊天中管理插件开关。线程应用配置只在新建或替换会话时刷新，变更后需使用 /new 或 /reset。破坏性操作默认启用，但非安全 schema 或身份不明确时仍会拒绝。
OpenClaw 原生 Codex 插件配置与迁移
原生 Codex 插件支持让 Codex 模式的 OpenClaw agent 在同一个 Codex 线程中使用 Codex 应用服务器的自有应用和插件能力。OpenClaw 不会将 Codex 插件翻译成合成的 codex_plugin_* 动态工具；插件调用保留在原生 Codex 转录中，由 Codex 应用服务器执行应用支持的 MCP。
在开始本页配置前，请确保基础 Codex harness 已正常工作。
前置要求
- 选用的 OpenClaw agent 运行时必须是原生 Codex harness。
plugins.entries.codex.enabled必须为true。plugins.entries.codex.config.codexPlugins.enabled必须为true。- V1 仅支持迁移过程中源 Codex home 已 source-installed 的
openai-curated插件。 - 目标 Codex 应用服务器必须能访问到预期的市场、插件和应用清单。
codexPlugins 对 PI 运行、普通 OpenAI provider 运行、ACP 会话绑定或其他 harness 无效，因为这些路径不会创建带原生 apps 配置的 Codex 应用服务器线程。
快速开始
预览从源 Codex home 迁移：
bash
openclaw migrate codex --dry-run如需迁移前严格检查源应用是否可访问，使用 --verify-plugin-apps：
bash
openclaw migrate codex --dry-run --verify-plugin-apps确认迁移计划后执行：
bash
openclaw migrate apply codex --yes迁移会为符合条件的插件写入显式的 codexPlugins 条目，并调用 Codex 应用服务器的 plugin/install。迁移后的典型配置如下：
json5
{
plugins: {
entries: {
codex: {
enabled: true,
config: {
codexPlugins: {
enabled: true,
allow_destructive_actions: true,
plugins: {
"google-calendar": {
enabled: true,
marketplaceName: "openai-curated",
pluginName: "google-calendar",
},
},
},
},
},
},
},
}修改 codexPlugins 后，新的 Codex 对话会自动应用更新后的应用集合。使用 /new 或 /reset 刷新当前对话。启用或禁用插件无需重启网关。
从聊天中管理插件
在运行 Codex harness 的聊天中使用 /codex plugins 命令查看或修改已配置的原生 Codex 插件：
text
/codex plugins
/codex plugins list
/codex plugins disable google-calendar
/codex plugins enable google-calendar/codex plugins 是 /codex plugins list 的别名。列表输出显示已配置的插件键、开关状态、Codex 插件名和市场来源（来自 plugins.entries.codex.config.codexPlugins.plugins）。
enable 和 disable 仅写入 OpenClaw 配置（~/.openclaw/openclaw.json），不会编辑 ~/.codex/config.toml 或安装新 Codex 插件。只有所有者或拥有 operator.admin 作用域的网关客户端才能更改插件状态。
启用一个已配置的插件也会自动打开全局 codexPlugins.enabled 开关。如果插件因为迁移返回 auth_required 而被写为禁用状态，请先在 Codex 中重新授权该应用，然后在 OpenClaw 中启用。
原生插件设置的运作方式
该集成包含三个独立状态：
- 已安装（Installed）：Codex 在目标应用服务器运行时拥有本地的插件包。
- 已启用（Enabled）：OpenClaw 配置允许在 Codex harness 回合中使用该插件。
- 可访问（Accessible）：Codex 应用服务器确认插件的应用条目对当前账户可用，并能映射到已迁移的插件身份。
迁移是持久的安装/资格判定步骤。规划时，OpenClaw 读取源 Codex 的 plugin/read 详情，并检查源 Codex 应用服务器的账户响应是否为 ChatGPT 订阅账户。非 ChatGPT 或缺失的账户响应会跳过应用支持的插件，并标记为 codex_subscription_required。默认情况下，迁移不会调用源 app/list；通过账户检查的应用支持的源插件在规划时不验证源应用可访问性，账户查询传输失败时会跳过并标记为 codex_account_unavailable。使用 --verify-plugin-apps 时，迁移会获取一份新的源 app/list 快照，并要求每个拥有应用都必须存在、已启用且可访问，然后才规划原生激活。在该模式下，账户查询传输失败会回退到源应用清单检查。运行时应用清单是迁移后的目标会话可访问性检查。Codex harness 会话建立时，会根据启用且可访问的插件应用计算限制性线程应用配置。
线程应用配置在 OpenClaw 建立 Codex harness 会话或替换旧的 Codex 线程绑定时计算，不会在每个回合重新计算。因此 /codex plugins enable 和 /codex plugins disable 只影响新的 Codex 对话。当前对话需要更新应用集合时请使用 /new 或 /reset。
V1 支持边界
V1 有明确的范围限制：
- 仅迁移在源 Codex 应用服务器清单中已安装的
openai-curated插件。 - 应用支持的源插件必须通过迁移时的订阅检查。
--verify-plugin-apps增加源应用清单检查。订阅检查失败的账户，以及在验证模式下不可访问、已禁用、缺失的源应用或源应用清单刷新失败的，会被报告为跳过的手动项，而不是写入启用的配置条目。无法读取插件详情的，在源应用清单检查前即被跳过。 - 迁移写入的插件身份包含
marketplaceName和pluginName，不会写入本地的marketplacePath缓存路径。 codexPlugins.enabled是全局启用开关。- 没有
plugins["*"]通配符，也没有允许任意安装权限的配置键。 - 不支持的 marketplace、缓存的插件包、hooks 和 Codex 配置文件会被保留在迁移报告中，供人工审查。
应用清单与所有权
OpenClaw 通过应用服务器的 app/list 读取 Codex 应用清单，缓存一小时，并异步刷新过期或缺失的条目。缓存仅存在于内存中；重启 CLI 或网关会清空缓存，OpenClaw 会在下一次 app/list 读取时重建。
迁移和运行时使用不同的缓存键：
- 源迁移验证使用源 Codex home 和源应用服务器启动选项。仅在设置了
--verify-plugin-apps时运行，会为该次规划强制进行新的源app/list遍历。 - 目标运行时设置在构建 Codex 线程应用配置时，使用目标 agent 的 Codex 应用服务器身份。插件激活会使该目标缓存键失效，并在
plugin/install后强制刷新。
只有当 OpenClaw 能通过稳定的所有权（确切的插件详情中的应用 ID、已知的 MCP 服务器名称、唯一稳定的元数据）将插件应用映射回已迁移的插件时，该应用才会被暴露。仅通过显示名称或歧义匹配的应用，在下次清单刷新证明所有权之前会被排除。
线程应用配置
OpenClaw 为 Codex 线程注入一个限制性的 config.apps 补丁：_default 被禁用，仅启用已启用且已迁移的插件所拥有的应用。
OpenClaw 根据全局或每个插件的 allow_destructive_actions 策略设置应用级别的 destructive_enabled，让 Codex 根据其原生应用工具注释执行破坏性工具元数据。_default 应用配置的 open_world_enabled 为 false。已启用插件应用的 open_world_enabled 为 true；OpenClaw 不提供单独的插件开放世界策略开关，也不维护每个插件的破坏性工具名称拒绝列表。
插件应用的工具审批模式默认为自动，因此非破坏性读取工具可以在没有同一线程审批 UI 的情况下运行。破坏性工具仍然受每个应用的 destructive_enabled 策略控制。
破坏性操作策略
对于已迁移的 Codex 插件，破坏性插件调用默认允许，但非安全 schema 和歧义的所有权仍会安全失败：
- 全局
allow_destructive_actions默认为true。 - 每个插件的
allow_destructive_actions覆盖该插件的全局策略。 - 策略为
false时，OpenClaw 返回确定性的拒绝。 - 策略为
true时，OpenClaw 仅自动接受能映射到审批响应的安全 schema（例如布尔审批字段）。 - 缺失插件身份、歧义所有权、缺失回合 ID、错误回合 ID 或非安全 elicitation schema 将被拒绝而不是提示。
故障排除
auth_required：迁移已安装插件，但其中一个应用仍需身份验证。显式插件条目被写为禁用状态，直到你重新授权并启用它。
app_inaccessible、app_disabled 或 app_missing：迁移未安装插件，因为在使用 --verify-plugin-apps 时，源 Codex 应用清单未显示所有拥有应用为存在、已启用且可访问。请在 Codex 中重新授权或启用该应用，然后重新运行带 --verify-plugin-apps 的迁移。
app_inventory_unavailable：迁移未安装插件，因为请求了严格源应用验证但源 Codex 应用清单刷新失败。修复源 Codex 应用服务器访问，或在能接受较快账户检查的规划时，不加 --verify-plugin-apps 重试。
codex_subscription_required：迁移未安装应用支持的插件，因为源 Codex 应用服务器账户没有使用 ChatGPT 订阅账号登录。请使用订阅认证登录 Codex 应用，然后重新运行迁移。
codex_account_unavailable：迁移未安装应用支持的插件，因为无法读取源 Codex 应用服务器账户。修复源 Codex 应用服务器认证，或者当账户查询失败时希望源应用清单决定资格时，加 --verify-plugin-apps 重试。
marketplace_missing 或 plugin_missing：目标 Codex 应用服务器无法看到预期的 openai-curated 市场或插件。重新针对目标运行时运行迁移，或检查 Codex 应用服务器插件状态。
app_inventory_missing 或 app_inventory_stale：应用就绪状态来自空或过期的缓存。OpenClaw 会安排异步刷新，并在所有权和就绪状态明确之前排除插件应用。
app_ownership_ambiguous：应用清单仅按显示名称匹配，因此该应用不会暴露给 Codex 线程。
配置已更改但 agent 看不到插件：使用 /codex plugins list 确认配置状态，然后使用 /new 或 /reset。现有的 Codex 线程绑定会保留其启动时的应用配置，直到 OpenClaw 建立新的 harness 会话或替换旧的绑定。
破坏性操作被拒绝：检查全局和每个插件的 allow_destructive_actions 值。即使策略为 true，非安全 elicitation schema 和歧义的插件身份仍会安全失败。
相关文档
常见问题
迁移时出现 auth_required 怎么解决？
迁移已将插件安装到 Codex，但插件包含的应用需要单独的 OAuth 授权。在 Codex 中完成应用授权后，在 OpenClaw 配置中将该插件条目改为 enabled: true，或使用 /codex plugins enable <plugin-name> 启用。
为什么我启用了插件但在聊天中看不到效果？
插件状态变更只影响新的 Codex 对话。当前会话中请使用 /new 或 /reset 刷新线程应用配置。也可以通过 /codex plugins list 确认插件的 enabled 状态和配置键是否正确。
如何允许 Codex 插件执行破坏性操作？
全局 allow_destructive_actions 默认为 true，即允许。如果希望禁用，在 codexPlugins 下设置 allow_destructive_actions: false。也可以为单个插件设置覆盖，例如 plugins.entries.codex.config.codexPlugins.plugins["google-calendar"].allow_destructive_actions: false。当策略为 true 时，OpenClaw 仅自动接受能被映射到安全回复 schema 的破坏性请求，不安全 schema 仍会被拒绝。