跳转至

原生 Codex 插件

原生 Codex 插件支持让 Codex 模式下的 OpenClaw 代理能够在处理 OpenClaw 回合的同一个 Codex 线程中,使用 Codex app-server 自身的应用和插件能力。插件调用保留在原生 Codex 记录中;Codex app-server 负责支持应用的后端 MCP 执行。OpenClaw 不会将 Codex 插件转换为合成的 codex_plugin_* OpenClaw 动态工具。

请在基础的 Codex 工具链 正常工作后再使用此页面。

要求

  • 代理运行时必须是原生 Codex 工具链。
  • plugins.entries.codex.enabled 为 true。
  • plugins.entries.codex.config.codexPlugins.enabled 为 true。
  • Codex app-server 报告版本为 0.149.0 或更高。官方插件提供 @openai/codex 0.160.0;更新的自定义、远程和 macOS 桌面版二进制文件会继续显示兼容性警告,并执行正常的运行时验证。
  • 目标 Codex app-server 能看到预期的市场、插件和应用清单。
  • 迁移仅支持其在源 Codex home 中观察到已由源安装的 openai-curated 插件。Codex 通过 openai-api-curated 线路名称向 API-key 和 Bedrock 账户提供相同的目录;OpenClaw 将这两个名称视为同一个策展目录,因此配置的 openai-curated 插件可以从任一名称解析。
  • 原生运行时支持还包括 Codex 已可用的其他市场,例如 openai-bundled、openai-primary-runtime、workspace-directory 以及当前仓库中的市场清单。在所有者或 operator.admin 明确安装或启用其市场限定身份之前,插件始终不可用。
  • OpenClaw 将 visualize@openai-bundled 技能排除在 Codex 线程之外。该技能会发出 Codex 特有的内联可视化指令,而 OpenClaw 的可视化在受支持的界面上使用 show_widget 工具。

codexPlugins 对 OpenClaw-provider 运行、ACP 对话绑定或其他工具链没有影响,因为这些路径永远不会创建带原生 apps 配置的 Codex app-server 线程。

OpenAI 侧的 Codex 账户、应用可用性以及工作区应用/插件控制来自已登录的 Codex 账户。有关 OpenAI 账户和管理员模型,请参阅将 Codex 与你的 ChatGPT 方案配合使用。

快速入门

源 Codex home 是你要从中迁移的 Codex CLI 状态目录:默认为 ~/.codex,如果设置了该变量则为 CODEX_HOME。参见 openclaw migrate 以使用 --from 指向不同的位置。

从源 Codex home 预览迁移:

openclaw migrate codex --dry-run

添加 --verify-plugin-apps 让迁移读取源已安装应用快照和应用元数据,要求每个拥有的应用在规划原生激活之前都存在、已启用且可访问:

openclaw migrate codex --dry-run --verify-plugin-apps

当计划看起来正确时,应用迁移:

openclaw migrate apply codex --yes

迁移会为符合条件的插件写入显式 codexPlugins 条目,并为选中的插件调用 Codex app-server plugin/install。迁移后的配置如下所示:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
              },
            },
          },
        },
      },
    },
  },
}

迁移仍仅限于 openai-curated。要查找 Codex 已经可见的其他插件,请列出可用的市场目录,并安装确切的市场限定身份:

/codex plugins available
/codex plugins install security-review@company-tools
/codex plugins status security-review@company-tools

Codex 从当前对话工作空间中的 .agents/plugins/marketplace.json 发现仓库市场。所有者无需先将该市场添加到 OpenClaw 配置中,即可列出或安装其插件。官方 bundled、primary-runtime、curated、workspace、shared 和 personal 市场取决于已登录的 Codex 账户以及上游功能或管理员策略。当 Codex 要求显式配置或将市场来源列入允许清单时,这些要求仍然适用;OpenClaw 不会绕过它们。

安装会写入类似如下的显式配置条目:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            plugins: {
              "security-review@company-tools": {
                enabled: true,
                marketplaceName: "company-tools",
                pluginName: "security-review",
              },
            },
          },
        },
      },
    },
  },
}

安装命令在调用 Codex plugin/install 之前会检查经过身份验证的所有者或管理员。Codex 会继续强制执行市场来源、工作区管理员、账户和连接器身份验证策略。需要 Codex 安装中间页、或未报告是否需要中间页的远程插件,必须先由 Codex 安装;之后重新运行 OpenClaw 安装命令,以授权已安装的插件。当响应缺少确切的市场、插件身份、详细信息身份或应用就绪证据时,OpenClaw 会隐藏应用。如果连接器需要额外登录,请先完成该授权,然后再期待插件的工具可用。

安装插件包并配置 OpenClaw 应用访问并不确认托管应用连接。当安装返回仍需要登录的应用时,OpenClaw 会提供 在 ChatGPT 中打开 <app> 链接,指向 Codex 返回的应用页面。请使用 Codex 工具链所用的同一个 ChatGPT 账户和工作区登录。打开链接不会验证连接,也不会使其工具在当前对话中可调用。如果浏览器显示的是目录而不是应用,或者没有安全链接可用,请在 Codex CLI 中运行 /apps 并在此选择应用。响应最多显示五个应用链接,并明确报告需要在 Codex CLI 中查看的其他应用。这些链接用于托管的 ChatGPT 应用;原生 MCP 服务器设置保持独立。

应用也可以在您首次使用其某个工具时请求登录。在 Control UI 中,选择 Open link 可在单独的标签页中打开所请求的页面。在您登录期间,问题会保持待处理状态。完成浏览器步骤后,选择 I've completed this step 并提交,以让 Codex 刷新并重试。仅打开链接不会恢复工具或确认连接。没有链接操作的客户端在回答前仍会显示需手动打开的 URL。

对于在活动 Codex 登录提示之外完成的设置,请刷新当前 Codex 账户/运行时的托管应用清单:

/codex plugins refresh

此刷新涵盖该运行时中的所有托管应用;它不是按插件进行的后端刷新。插件的 Refresh hosted apps 按钮会运行此命令。单独的 Check status 按钮仅检查该插件,不刷新托管工具。这两个操作都不会更改授权或当前对话的应用策略。连接后请使用 /new 或 /reset,然后在新对话中检查状态。

在 codexPlugins 更改后,新的 Codex 对话会自动采用更新后的应用集合。运行 /new 或 /reset 以刷新当前对话。插件启用/禁用更改不需要网关重启。

Scheduled automations

当经过身份验证的所有者从 Codex 轮次创建自动化时,OpenClaw 会捕获该确切 Codex 线程上可调用的应用 ID 和批准限制。存储的授权绑定到创建者准备好的 Codex 配置文件和账户。计划运行将该上限与当前 Codex 策略和应用可用性相交。它们永远不会获得新的应用 ID,也不会获得更广泛的破坏性、开放世界或批准上限。之后在已捕获的应用中添加的工具,只有在存储的上限和当前策略都允许时才能运行。

计划应用调用是无人值守的。只有在作业创建时和运行时都明确允许的操作才能在没有提示的情况下继续。仍需要批准或引导的操作会被拒绝。账户变更、运行时变更、应用被撤销、策略收紧或清单不可用都会在应用执行前停止,并报告如何恢复访问或重新授权自动化。模型回退不能将此授权转移到另一个运行时或账户。

此路径比普通的交互式轮次更严格。OpenClaw 会根据当前工具元数据和捕获的授权生成每个工具的 enabled 和 approval_mode 值。显式的原生 enabled: true 不能覆盖计划运行上已捕获或当前的破坏性/开放世界限制。批准交集会在任一侧要求时保留 "prompt";"approve" 服从另一侧。将 "auto" 与 "writes" 组合会产生 "prompt",因为它们基于注解的规则并非完全有序。

在捕获应用授权之前创建的作业可能会保留其普通的 OpenClaw 工具上限并继续非应用工作,但无法自动恢复 Codex 应用访问。仅重新创建或重新授权需要应用访问的作业,且必须来自新的经身份验证的所有者轮次。请参阅 Automations。普通编辑会保留捕获的应用授权。显式替换作业的 toolsAllow 上限而没有新的经身份验证的 Codex 授权捕获,会清除该授权;下次运行时会报告应用访问需要重新授权。来自新的经身份验证的所有者轮次的更新可以改为捕获并为更新后的作业存储新的应用上限。

Manage plugins from chat

/codex plugins 可在您操作 Codex harness 的同一聊天中检查或更改已配置的原生 Codex 插件:

/codex plugins
/codex plugins list
/codex plugins available
/codex plugins available security
/codex plugins available --page 2
/codex plugins install security-review@company-tools
/codex plugins status security-review@company-tools
/codex plugins refresh
/codex plugins disable google-calendar
/codex plugins enable google-calendar
/codex plugins disable security-review@company-tools

/codex plugins 是 /codex plugins list 的别名。列表显示每个已配置插件的键、开/关状态、Codex 插件名称,以及来自 plugins.entries.codex.config.codexPlugins.plugins 的市场。

available [query] [--page <n>] 需要所有者或 operator.admin。它使用绑定的工作区读取 Codex 的市场目录,包括仓库本地插件,而不会安装或启用它们。搜索会在返回的完整目录中不区分大小写地匹配名称、显示标题、发布者、市场和描述,然后每页显示十条结果。Next page 和 Previous page 会保留您的搜索;没有按钮的渠道会显示要发送的命令。搜索文本限制为 100 个字符。在包含 --page 的字面搜索文本之前使用 --。

当 Codex 提供显示标题、发布者和描述时,结果会显示它们,并为缺失的发布者或描述提供显式占位符。它们保留市场限定的身份和可用性限制;显示标题和发布者名称不会更改安装身份。这会搜索 Codex 目录,而不是 OpenClaw 的插件注册表或每个 ChatGPT 连接。所有者范围的 codex_plugins 模型工具使用相同的搜索匹配,并且也是只读的:它可以推荐精确的安装命令,但不能安装、启用或添加市场。

status <name>@<marketplace> [page] 检查恰好一个已配置的插件,需要所有者或 operator.admin。限定身份是必需的;裸的 status 或未限定的名称会返回指向 list 的用法指引。

状态分别显示包安装、市场限制、Codex 启用状态以及共享的 OpenClaw 应用访问。对 OpenClaw 应用访问的更改会在下一条消息时生效;它们不会安装或启用 Codex 包。

应用结果每页最多显示五个应用。ChatGPT 应用页面链接要求已确认的托管应用运行时支持、其目录策略下可用的插件,以及来自 app/read 的匹配授权元数据。插件自身的应用声明或设置 URL 并不能确立该访问权限。当符合资格的 ChatGPT 页面仍可用时,OpenClaw 应用访问可以被禁用;打开该页面不会启用 OpenClaw 应用访问。没有托管应用的插件不会获得 ChatGPT 连接或设置指引。状态不会评估它们的技能或原生 MCP 服务器就绪情况。

所选的代理(agent)、认证配置文件、对话工作区以及账户邮箱/套餐会在可用时显示。当 Codex 未报告 ChatGPT 工作区身份时,该身份保持未知;在浏览器中打开符合条件的托管应用页面时,请使用同一个账户和工作区。

Status 使用 app/read 获取应用元数据,并显示 app/installed 返回的 enabled 和 callable 标志。运行时范围在可用时为所绑定的 Codex 线程,否则为账户范围。这些标志反映的是有效的 Codex 配置和当前运行时工具快照;它们与 OpenClaw 应用访问权限相互独立。Status 不会推断单独的连接状态。缺失的应用记录和读取失败会被明确报告,而不会变成错误的标志。

/codex plugins refresh 需要所有者(owner)权限或 operator.admin 权限,并且所选 Codex 账户/运行时需已确认支持托管应用。它可以在未配置插件的情况下工作。它会使该运行时的 OpenClaw 应用缓存失效,以 forceRefresh: true 且不带 threadId 的方式调用 Codex app/installed,然后读取返回应用的元数据。它不会刷新市场目录、重新安装插件包或重新加载原生 MCP 服务器。

刷新后,可使用 /codex plugins status <name>@<marketplace> 检查单个插件。Status 绝不强制进行托管刷新。已禁用或被阻止的插件仍保持禁用或被阻止,但不会阻止本来被允许的托管刷新。

请求完成并不证明 Codex 已替换其快照,也不能证明实时工具调用一定会成功。刷新绝不会安装、启用、认证或替换任何线程,也不会重新加载其他对话。连接后,请使用 /new 或 /reset 并再次检查状态。浏览器设置不会改变 OpenClaw 应用访问权限;本地应用访问更改将在下一条消息时生效。不支持的方法、取消操作和刷新失败都会提供重试操作,而不会将之前的清单视为已确认。

install、enable 和 disable 需要所有者权限,或需要具有 operator.admin 范围的网关客户端。OpenClaw 保留的 /codex 命令会在代理调用之前被分发,因此模型生成的推荐不算是安装批准。对于 Codex 尚未安装的插件,install 会调用 Codex app-server,并且仅在安装成功后记录明确的插件策略。如果 Codex 确认该插件已安装并启用,同一命令会记录其授权,而不会再次安装。enable 和 disable 会更改 OpenClaw 的持久化策略;合格的身份标识和现有的配置键都可以接受。

安装或启用已配置的插件也会打开全局 codexPlugins.enabled 开关,但不会启用 allow_all_plugins。如果插件报告 auth_required,请在新对话开始前在 Codex 中授权该应用。该授权在后续对话中持续有效,直到插件被禁用或上游账户/工作区撤销访问权限。

只安装你信任的插件。Codex 插件可以提供技能(skills)、应用、MCP 服务器和钩子(hooks)。某些钩子可以参与权限决策,因此显式安装意味着信任所选插件的代码;这不是安全审查,也不是隔离边界。

原生插件设置的工作原理

该集成跟踪三种状态:

状态 含义
Installed Codex 在目标 app-server 运行时中拥有该插件包。
Enabled Codex 报告该插件已启用,并且 OpenClaw 配置允许其在 Codex harness 对话轮次中使用。
Accessible Codex app-server 确认该插件的应用条目对当前账户可用,并映射到已配置的插件身份。

对于 openai-curated 插件,迁移是持久的安装/资格认定步骤:

  • 在规划阶段,OpenClaw 读取源 Codex 的 plugin/read 详细信息,并检查源 Codex app-server 账户。codex_subscription_required 表示 account/read 明确识别出 API 密钥(API-key)或其他非 ChatGPT 账户;缺少账户并不能证明订阅不存在。
  • 默认情况下,迁移会跳过源应用清单调用:通过账户门槛的、由应用支持的源插件会在不验证源应用可访问性的情况下被规划。账户缺失或 account/read 失败会以 codex_account_unavailable 跳过这些插件。
  • 使用 --verify-plugin-apps 时,迁移会获取新的源 app/installed 快照,通过 app/read 获取经过认证的元数据,并要求每个所属应用在规划原生激活之前都存在于源 Codex 账户中、处于启用状态且可访问。如果 account/read 缺失或失败,严格验证仍然可以通过源 app-server 配置的 bearer 或 header 认证来证明访问权限。被明确识别为非 ChatGPT 的账户仍然不具备资格。

对于来自任何已发现市场的、获得明确批准的插件,OpenClaw 会使用其 plugin/installed 快照和 plugin/read 详细信息来确定确切的市场限定身份和应用所有权。普通线程设置期间的仅安装检查是只读的;来自已禁用或未批准插件的应用仍会被拒绝。所有者发起的安装是显式变更路径。缺失或模糊的所有权会以失败关闭(fail closed)方式处理,而不会授予账户级访问权限。

运行时应用清单是针对迁移的精选插件和手动配置的工作区插件两者的目标会话可访问性检查。在启用策略的对话轮次之前,包括热复用(warm reuse)和冷恢复(cold resume),Codex harness 会根据当前原生设置重建限制性的线程应用策略,同时复用其应用清单和插件元数据缓存。

支持边界

  • 只有已安装在源 Codex 应用服务器清单中的 openai-curated 插件才符合迁移条件。
  • 运行时支持来自 Codex 发现的官方、工作区、个人、共享和仓库本地市场中被明确批准的插件。缺少市场、插件、所有权细节或应用就绪证据时,不会暴露任何插件应用。
  • 被明确识别为非 ChatGPT 的源账户无法通过订阅门槛。缺失或不可读的源账户默认不可用。使用 --verify-plugin-apps 则可通过经过身份验证的源应用清单建立访问,包括使用 bearer 或 header 认证的应用服务器。不可访问、已禁用或缺失的源应用以及清单刷新失败仍作为跳过的手动项保留。不可读的插件详情会在应用清单门槛之前被跳过。
  • 迁移会写入显式插件标识(marketplaceName 和 pluginName);不会写入本地的 marketplacePath 缓存路径。
  • codexPlugins.enabled 是唯一的全局启用开关;不存在 plugins["*"] 通配符或可授予任意安装权限的配置键。
  • 迁移不会自动导入非精选市场、缓存的插件包、钩子或 Codex 配置文件。请使用 /codex plugins available 以及所有者发出的 /codex plugins install <plugin>@<marketplace> 命令来选择加入额外发现的插件。
  • OpenClaw 在此流程中不会添加新的 Git 或本地市场来源。其他来源必须已在 Codex 中配置,或可从绑定仓库中发现。

应用清单与所有权

OpenClaw 首先读取并缓存一个限定于目标 Codex 应用服务器和已配置工作区的 plugin/installed 快照。该快照涵盖该范围内可见市场中的插件,包括已禁用的插件标识;失败或不完整的快照永远不会被缓存。同一运行时和工作区中的对话共享此元数据,所有者安装会使所有这些对话的元数据失效。应用就绪状态仍特定于每个线程。plugin/read 仅限于建立所有权所需的精确配置的插件详情。显式发现查询使用对话工作区调用 plugin/list 来查找仓库市场。常规设置保留其现有的精选恢复行为;额外的市场安装需要明确的所有者或管理员命令。

插件安装后,Codex 负责刷新技能、钩子和 MCP。OpenClaw 会刷新其插件和应用清单,而无需重新加载无关线程。如果较旧的自定义 Codex 运行时未能在现有对话中提供新安装的插件,请使用 /new 或 /reset。

OpenClaw 通过 app/installed 读取已安装的应用运行时状态,并通过 app/read 以每次最多 100 个应用 ID 的批次获取规范化应用元数据。首次读取会强制刷新冷启动的已安装运行时快照。当安装了多个配置的精选插件时,OpenClaw 会将它们的缓存失效合并为一次应用清单刷新。普通缓存读取不会为每个新线程强制刷新连接器。OpenClaw 将合并后的清单在内存中缓存一小时,并异步刷新过期或缺失的条目。该缓存是进程本地的;重启 CLI 或网关会将其丢弃。

缺失清单方法、身份验证错误、传输失败和连接器刷新失败都不会接纳应用工具。普通轮次(包括使用 allow_destructive_actions: "ask" 的轮次)可以在清单超出其启动预算时继续运行,但本机应用会被禁用。如果计划运行所捕获的应用策略无法在该预算内重新验证,则计划运行会停止。

迁移和运行时使用独立的缓存键:

  • 源迁移验证使用源 Codex 主目录和启动选项。它仅在 --verify-plugin-apps 下运行,并为该规划运行强制刷新源运行时快照和元数据读取。
  • 目标运行时设置在构建和验证线程应用配置时使用目标代理的 Codex 应用服务器身份。精选插件激活会使该目标缓存键失效,然后在 plugin/install 之后强制刷新它。显式市场安装会在后续对话使用插件之前刷新相同的目标运行时状态。

仅当 OpenClaw 能通过稳定的所有权将插件应用映射回已配置的插件时,该应用才会被暴露:来自插件详情的精确应用 ID、已知的 MCP 服务器名称,或唯一稳定的元数据。仅凭显示名称或存在歧义的所有权会被排除,直到下一次清单刷新证明所有权为止。

缺失的插件和市场会保留在已保存的设置中以便将来发现,但会被排除在有效运行时插件策略之外。OpenClaw 会记录错误,并继续使用健康的插件和已连接的账户应用。缺失条目的权限不适用于其他应用,即使它们的显示名称匹配。该条目会在下一次正常清单刷新时被重新考虑;不会移除任何已保存的设置。被管理员禁用的已发现插件会保留其限制。

已连接的账户应用

所有者操作的代理可以选择加入其 Codex 账户中已连接的每一个应用,而无需匹配的插件包:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_all_plugins: true,
            allow_destructive_actions: "auto",
          },
        },
      },
    },
  },
}

allow_all_plugins: true 会在建立新的本机 Codex 线程时读取已安装的应用快照和经过身份验证的元数据。它只接纳账户可访问的应用。Codex 还必须确认每个被接纳的应用在该线程中已启用且可调用。OpenClaw 不会全局安装、认证或启用应用。现有线程会保留其持久化的应用集合;使用 /new、/reset 或重启网关来获取新连接或已撤销的应用。

在清单中找到的显式禁用的已配置插件会覆盖账户范围的应用访问。由于 Codex app/read 会省略已禁用工作区插件的显示名称,OpenClaw 会使用其 plugin/installed 快照,并且只读取该确切已配置插件的详细信息,以保留其拥有的应用 ID。这种狭窄的只读检查不会发现无关的市场,不会激活该插件,也不会授予其应用。如果无法确定已禁用插件的所有权,账户范围的应用选择将失败关闭。

账户应用继承全局 codexPlugins.allow_destructive_actions 值,该值接受 true、false、"auto" 或 "ask"。显式的按插件策略会覆盖重叠应用 ID 的全局策略。清单失败会失败关闭,而不是回退到无限制默认值。

线程应用配置

OpenClaw 会为 Codex 线程注入一个限制性 config.apps 补丁:_default 被禁用,并且只有由已启用的已配置插件拥有的应用,或 allow_all_plugins 允许的可访问账户应用才会被启用。

当 _default 被禁用时,一个应用可以在账户范围快照中已安装且已认证,但不可调用。OpenClaw 暂时只允许所有权已证明且策略允许的应用,创建限制性线程,然后使用生成的线程 ID 和 forceRefresh: false 重新读取一次 app/installed。如果快照报告某个应用缺失、被禁用或不可调用,OpenClaw 会记录一条警告,列出不可用的应用,并继续使用剩余工具。Codex 仍会执行线程的有效应用、托管、工作区和工具策略。不可用的可选应用不会阻止无关的聊天或心跳运行。

如果快照请求本身失败,临时线程永远不会绑定或使用。OpenClaw 会删除失败的持久临时线程,取消订阅失败的临时线程,并在无法确认安全清理时退役 app-server 连接。

每个应用上的 destructive_enabled 来自有效全局或按插件的 allow_destructive_actions 策略;true、"auto" 和 "ask" 都会设置 destructive_enabled: true,而 false 会将其设置为 false。Codex 仍会按以下顺序评估原生工具启用状态和注释。_default 以 open_world_enabled: false 禁用;已启用的插件应用获得 open_world_enabled: true。OpenClaw 不暴露单独的插件级开放世界策略旋钮,也不维护按插件的破坏性工具名称拒绝列表。

审批决策顺序

对于普通交互式 Codex 回合,按以下顺序遵循这些决策:

  1. 准入: OpenClaw 选择此线程上允许的插件/应用身份。不可用的清单或未证明的所有权不会授予访问权限。
  2. 线程配置: OpenClaw 将其应用策略叠加到目标 app-server 的原生配置上。Codex 管理要求仍然适用。
  3. 工具启用: Codex 决定特定工具是否可调用。已禁用的工具不能通过批准提示而变为可调用。
  4. 审批模式和审查者: Codex 决定调用是否需要审查,以及是使用其自动审查者还是发送用户审批请求。
  5. OpenClaw 响应: 当插件审批请求到达 OpenClaw 时,其征询桥接会应用有效的 allow_destructive_actions 值。

这些是独立的决策。enabled: true 不意味着自动批准,approval_mode: "approve" 也不会启用已禁用的工具。OpenClaw 动态工具、普通 MCP 表单和原生 shell 权限有各自的流程;参见 原生权限和 MCP 征询。

哪个配置拥有每个设置

设置 所有者和用途
plugins.entries.codex.config.codexPlugins OpenClaw 的准入和插件征询策略。
codexPlugins.allow_destructive_actions 已配置插件和被允许账户应用的共享 OpenClaw 默认值。
codexPlugins.plugins.<key>.allow_destructive_actions 针对该已配置插件的显式覆盖。
原生 apps._default、apps.<appId> 和 apps.<appId>.tools 在配置层和 OpenClaw 线程补丁合并后的 Codex 应用默认值和按工具设置。
plugins.entries.codex.config.appServer.approvalPolicy 和 approvalsReviewer 通用的 Codex 审批姿态和审查者,区别于应用/工具策略。参见 审批和沙箱模式。

OpenClaw 将破坏性操作设置解析为:

per-plugin value ?? codexPlugins shared value ?? true

省略按插件值会继承共享值。显式的 false、true、"auto" 和 "ask" 都会覆盖它。特别是,生成的按插件 "auto" 会覆盖共享的 false;"auto" 是一个策略值,而不是继承指令。

共享默认值与插件条目位于同一个 OpenClaw 配置中。它不需要单独的整个主机配置文件。原生 Codex 设置属于运行工具的 app-server:默认托管本地服务器使用 agent 范围的 Codex home;远程服务器使用其自己的配置。从 OpenClaw 或部署管理器启动 Codex 不会移除这个原生配置层。OpenClaw 的线程补丁不会重写已保存的原生设置。

原生工具启用

在 OpenClaw 的准入补丁之后,Codex 按以下顺序评估应用工具:

  1. 已禁用的应用会阻止其所有工具,包括显式启用的工具。 受管应用的禁用状态仍然具有权威性。
  2. 显式 apps.<appId>.tools.<tool>.enabled 对该工具优先。
  3. 否则,显式 apps.<appId>.default_tools_enabled 优先。
  4. 否则,Codex 对照工具的注解检查 destructive_enabled 和 open_world_enabled。 每个类别设置从应用回退到 apps._default,然后回退到 true。 缺失的注解在此资格检查中被视为破坏性/开放世界。

对于工具配置,精确的工具名称条目优先于工具标题条目。 Codex 首先选择整个条目;它不会从标题条目中填充缺失字段。 省略 enabled 以继承;TOML 没有 null 值。

例如,对于具有 destructive_enabled: false 的已准入应用,省略工具 enabled 会使破坏性工具保持被阻止。显式 enabled: true 允许该特定工具通过此原生资格检查,而 enabled: false 即使应用允许破坏性工具也会阻止它。该调用 仍必须通过审批和执行检查。这是对应用默认值的例外, 而不是启用未准入应用或扩大计划权限的方式。

原生审批模式

对于已启用的工具,Codex 选择第一个适用的审批模式:

  1. 受管的逐工具审批要求。
  2. 所选原生工具条目的 approval_mode。
  3. 所选连接账户的 apps.<appId>.links.<linkId>.default_tools_approval_mode。
  4. apps.<appId>.default_tools_approval_mode。
  5. apps._default.default_tools_approval_mode。
  6. "auto"。

账户链接是本次调用使用的连接账户,而不是 OpenClaw 会话。以下模式决定是否需要审查; 它们本身并不保证 OpenClaw 提示:

原生模式 审批要求
"approve" 无工具审批请求。其他访问和执行限制仍然适用。
"prompt" 需要审批,包括只读工具。
"writes" 除非工具明确声明自身为只读,否则需要审批。
"auto" 使用注解:明确破坏性的工具需要审批;否则明确只读的工具不需要。其余工具在破坏性/开放世界提示为 true 或缺失时需要审批。

审查者选择是独立的:连接账户的审查者覆盖 应用审查者,然后是 apps._default.approvals_reviewer,然后是线程 审查者。Codex 仅接受管理要求允许的已配置审查者;否则使用线程 审查者。针对特定模型的 自动审查要求具有优先权。严格自动审查 还可以在工具模式本会跳过审查时要求审查。

除非 OpenClaw 策略显式为 "ask",已准入应用保留其 原生审批模式和审查者,包括应用默认值以及已保存的账户链接 或工具覆盖。恢复线程或提出 /btw 旁路问题时也是如此。如果没有原生审批设置,Codex 回退到 "auto"。

使用 OpenClaw allow_destructive_actions: "auto" 可将原生人工审批 请求通过 OpenClaw 同意流程路由。原生 "prompt" 配合 "auto_review" 审查者仍保留在 Codex 的自动审查流程中。OpenClaw true 也保留 原生模式,但会自动接受到达桥接的支持的审批请求, 如下所述。

OpenClaw "ask" 还会为当前非只读 工具名称/别名和连接账户覆盖已保存的审批字段,选择原生 "auto" 以及 人工应用/账户审查者。它保留工具启用状态。如果工具摘要 不可用,它会针对所有已保存的工具审批条目。因此 "ask" 要求对 Codex 发送审批的操作进行一次性同意;它 并不意味着对每次读取都使用原生 "prompt"。其他应用保留其审查者。

在普通原生插件轮次以及带有绑定应用的 /btw 旁路问题中, OpenClaw 会启用 MCP 征询委托,即使通用 appServer.approvalPolicy 为 "never";这不会启用无关的 shell 审批类别。应用模式、审查者和桥接响应仍 决定结果。通用审批策略不能替代上述 按应用/工具的设置。

破坏性操作策略

对于已配置的 Codex 插件,破坏性插件征询默认允许, 而不安全的架构和模糊的所有权会失败关闭:

  • 全局 allow_destructive_actions 默认为 true。
  • 按插件的 allow_destructive_actions 覆盖该插件的 全局策略。
  • false:OpenClaw 设置原生 destructive_enabled: false;工具资格 遵循上述原生默认值和显式例外。符合条件的托管应用工具的审批 请求仍会通过 OpenClaw 同意, 包括允许的读取和 /btw 旁路问题。桥接不会 再次对工具分类,也不会一概拒绝其请求。插件提供的 MCP 服务器审批请求仍会收到确定性拒绝。
  • true:OpenClaw 仅自动接受它可以映射到审批 响应的安全架构,例如布尔审批字段。
  • "auto":OpenClaw 向 Codex 暴露破坏性插件操作,然后 在返回 Codex 审批响应之前,将所有权已证明的 MCP 审批征询转换为 OpenClaw 插件 审批。
  • "ask":OpenClaw 使用与 "auto" 相同的 Codex 写入/破坏性门控, 应用上述工具/账户审批覆盖,并且 只提供一次性批准或拒绝。已保存的原生设置保持不变, 用户配置重载会保留线程的审批策略。这些检查 也会在重用线程或回答 /btw 旁路问题之前运行。更改的覆盖键会使用当前策略重建线程。
  • 缺少插件身份、所有权模糊、turn id 缺失或不匹配, 或不安全的征询架构会拒绝而不是提示。

不在已准入策略范围内的应用将保持禁用状态,即使原生 Codex 设置启用了它们。在已启用的策略能够准入应用工具之前,必须先验证原生设置。当没有任何应用可以准入时,Codex 的应用工具界面会在不读取原生应用设置的情况下被禁用。禁用插件应用也会跳过应用清单发现。处于活动状态的旧版受管应用设置优先于原生线程配置,并阻止应用准入;请将这些应用设置迁移到受支持的用户或项目配置层。原生管理要求仍然具有权威性。

审批示例

假设存在一个已准入且已认证的应用,没有冲突的受管要求,并且对于需要审批的调用存在人工审核者。以下读取工具声明了 readOnlyHint: true 和 destructiveHint: false:

配置 普通回合中的可观察结果
OpenClaw 共享 false,按插件 "auto" 插件覆盖生效。破坏性工具符合资格;到达 OpenClaw 的审批请求会请求同意。
OpenClaw "auto",原生应用默认 "prompt",无工具/链接覆盖,非破坏性读取 原生 "prompt" 保留。读取请求同意;“允许一次”允许该调用,“拒绝”阻止它。
OpenClaw "auto",原生读取工具 approval_mode: "prompt" 按工具模式保留。读取请求同意;“允许一次”允许该调用,“拒绝”阻止它。
OpenClaw false,原生应用默认 "prompt",无工具/链接覆盖,非破坏性读取 原生资格允许读取,并且 OpenClaw 请求同意。“允许一次”允许该调用,“拒绝”阻止它。
OpenClaw false,破坏性工具显式 enabled: true 且 approval_mode: "approve" 原生工具例外会绕过类别默认值,并且不需要工具审批请求。桥接的拒绝路径不是执行时的类别上限。
OpenClaw "ask",已保存的非只读工具审批 "approve" 线程覆盖会用原生 "auto" 替换该已保存审批;需要审批的调用使用一次性同意。

如果原生 "prompt" 示例中的审核者是 "auto_review" 而不是 "user",Codex 会执行自动审核,而不是显示 OpenClaw 同意提示。两种审核者选择都不会启用未通过资格检查的工具。

记住的审批和显式启用是不同的设置。Codex 的持久化应用工具审批会写入 approval_mode: "approve",而不是 enabled: true;“允许一次”不会持久化任一设置。在解释某个工具为何运行或为何未出现提示时,请重新检查这两项。

故障排查

代码 含义 修复
auth_required 迁移已安装插件,但其某个应用仍需要认证。该条目会被写入为禁用状态,直到你重新授权。 在 Codex 中重新授权该应用,然后在 OpenClaw 中启用插件。
app_inaccessible、app_disabled、app_missing 使用 --verify-plugin-apps 时,源 Codex 应用清单未显示所有已拥有应用均存在、已启用且可访问。 在 Codex 中重新授权或启用该应用,然后使用 --verify-plugin-apps 重新运行迁移。
app_inventory_unavailable 请求了严格的源应用验证,但源 Codex 应用清单刷新失败。 修复源 Codex app-server 访问,或者不使用 --verify-plugin-apps 重试,以接受更快的账户门控方案。
codex_subscription_required 源 app-server 明确识别出 API 密钥或其他非 ChatGPT 账户。 使用订阅认证登录 Codex 应用,然后重新运行迁移。
codex_account_unavailable 源账户缺失,或者在未进行严格应用验证时 account/read 失败。 恢复源账户访问,或者在已认证的源应用清单能够证明访问权限时使用 --verify-plugin-apps。
marketplace_missing、plugin_missing 在已安装快照中,确切的 marketplace 或已配置插件不可用;插件应用会失败关闭。 验证目标 app-server 的 plugin/installed 响应以及确切的已配置插件标识。
plugin_detail_unavailable OpenClaw 无法读取确切已配置插件的所有权详情。 检查目标 app-server 的 plugin/installed 和 plugin/read 响应。
代码 含义 修复
plugin_disabled Codex 报告该插件已安装但被禁用。 在 Codex 中启用该插件,或让所有者重新显式安装并授权。
plugin_activation_failed 插件激活未完成。 使用附带的诊断信息来区分插件市场、身份验证、刷新或工作区就绪状态故障。
app_inventory_missing, app_inventory_stale 应用就绪状态来自空缓存或过期缓存。 OpenClaw 会自动安排异步刷新;在所有权和就绪状态确定之前,插件应用保持被排除。
app_ownership_ambiguous 应用清单仅通过显示名称匹配。 在后续刷新证明所有权之前,该应用对 Codex 线程保持隐藏。

工作区插件已安装但不可见: 确认工作区 plugin/installed 快照报告确切的已配置 ID 为已安装且 已启用,然后确认 app/installed 返回同一 Codex 账户的所有已拥有应用,并且 app/read 返回其元数据。仅由 账户范围默认设置禁用的应用,在 OpenClaw 启动并验证 其显式配置的线程后可能变为可调用。已撤销的身份验证、缺失的元数据、已禁用的 工作区插件,以及 Codex 托管或工作区限制仍会阻止 访问。在启动新 线程之前,重新授权或修复这些上游条件。如果在网关缓存应用清单后更改了该状态,请运行 /codex plugins refresh,然后使用 /new 或 /reset。 OpenClaw 不会代表所有者对插件应用进行身份验证。

对于 plugin_detail_unavailable,请验证确切的已安装插件市场 和插件标识能够选中一个匹配的 plugin/read 结果。当该选择器或所有权详情不可用时,OpenClaw 会保持 隐藏已拥有的应用。对于 plugin_activation_failed,请检查插件市场、应用授权和 安装后刷新诊断。显式批准的插件必须 已安装、已启用且已完成身份验证,其应用才能出现在线程中。

配置已更改但代理无法看到插件: 运行 /codex plugins list 以确认已配置状态,然后使用 /new 或 /reset。现有 Codex 线程绑定会保留其启动时使用的应用配置,直到 OpenClaw 建立新的测试框架会话或替换过期的绑定。

破坏性操作被拒绝: 检查全局和每个插件的 allow_destructive_actions 值。即使为 true、"auto" 或 "ask", 不安全的引导模式和模糊的插件标识仍会失败关闭。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw