Configure Native Codex Plugins for Codex-mode OpenClaw Agents

Native Codex plugin support enables a Codex-mode OpenClaw agent to use the app and plugin capabilities of the Codex app-server within the same Codex thread that processes the OpenClaw turn. Plugin calls remain inside the native Codex transcript, and the Codex app-server manages app-backed MCP execution. OpenClaw does not convert Codex plugins into synthetic codex_plugin_* OpenClaw dynamic tools.

Refer to this page after the base Codex harness is operational.

Requirements

• The agent must run on the native Codex harness.
• plugins.entries.codex.enabled is true.
• plugins.entries.codex.config.codexPlugins.enabled is true.
• The target Codex app-server has access to the required marketplace, plugin, and app inventory.
• Migration only supports openai-curated plugins that it detected as source-installed in the source Codex home.
• Manually configured workspace-directory plugins require a Codex app-server where plugin/list accepts marketplaceKinds and the pathless workspace summaries contain remotePluginId. The plugin must already be installed and enabled, and its owned apps must be reachable in app/list.

codexPlugins does not affect OpenClaw-provider runs, ACP conversation bindings, or other harnesses, since those paths never generate Codex app-server threads with native apps configuration.

OpenAI-side Codex account, app availability, and workspace app or plugin controls are governed by the signed-in Codex account. See Using Codex with your ChatGPT plan for details on the OpenAI account and admin model.

Quickstart

Preview a migration from the source Codex home:

openclaw migrate codex --dry-run

Add --verify-plugin-apps to make the migration call source app/list and require every owned app to be present, enabled, and accessible before planning native activation:

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

Apply the migration once the plan looks correct:

openclaw migrate apply codex --yes

Migration writes explicit codexPlugins entries for eligible plugins and calls Codex app-server plugin/install for selected plugins. A migrated configuration appears like this:

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

Migration is limited to openai-curated. To use an existing workspace-directory plugin, add it manually with the exact marketplace-qualified summary.id returned by plugin/list. For instance, if Codex returns example-plugin@workspace-directory, configure that complete value instead of its display name:

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            plugins: {
              "example-plugin": {
                enabled: true,
                marketplaceName: "workspace-directory",
                pluginName: "example-plugin@workspace-directory",
              },
            },
          },
        },
      },
    },
  },
}

OpenClaw does not invoke plugin/install or initiate authentication for a workspace-directory plugin. Install, enable, and authenticate it in Codex before adding or enabling the OpenClaw policy. OpenClaw hides apps when the response lacks the exact marketplace, plugin ID, detail ID, or app-readiness evidence. If Codex rejects the explicit workspace plugin/list request, OpenClaw reports marketplace_missing for each enabled workspace plugin and keeps any independently discovered curated plugins available.

After a codexPlugins change, new Codex conversations automatically pick up the updated app set. Run /new or /reset to refresh the current conversation. A gateway restart is unnecessary for plugin enable or disable changes.

Manage plugins from chat

/codex plugins inspects or modifies configured native Codex plugins from the same chat where you operate the Codex harness:

/codex plugins
/codex plugins list
/codex plugins disable google-calendar
/codex plugins enable google-calendar

/codex plugins is an alias for /codex plugins list. The list shows each configured plugin's key, on or off state, Codex plugin name, and marketplace from plugins.entries.codex.config.codexPlugins.plugins.

enable and disable only write to ~/.openclaw/openclaw.json; they never modify ~/.codex/config.toml or install new Codex plugins. Only the owner or a gateway client with the operator.admin scope can run them.

Enabling a configured plugin also activates the global codexPlugins.enabled switch. If a curated plugin was written as disabled because migration returned auth_required, reauthorize the app in Codex before enabling it in OpenClaw. For a workspace-directory entry, enabling it here only alters OpenClaw policy; the plugin and app must already be active in Codex.

How native plugin setup works

The integration tracks three states:

For openai-curated plugins, migration serves as the durable install and eligibility step:

• During planning, OpenClaw reads source Codex plugin/read details and verifies that the source Codex app-server account is a ChatGPT subscription account. A non-ChatGPT or missing account response skips app-backed plugins with codex_subscription_required.
• By default, migration skips the source app/list call: app-backed source plugins that pass the account gate are planned without source app accessibility verification, and account-lookup transport failures skip with codex_account_unavailable.
• With --verify-plugin-apps, migration takes a fresh source app/list snapshot and requires every owned app to be present, enabled, and accessible before planning native activation. Account-lookup transport failures then fall through to the source app-inventory gate instead of skipping outright.

For workspace-directory plugins, configuration is handled outside of OpenClaw. OpenClaw only queries that marketplace when at least one enabled workspace entry is configured, resolves each plugin using its exact summary.id, and reuses the existing plugin/read ownership and app/list readiness checks. If a plugin is uninstalled, disabled, inaccessible, or unauthenticated, it exposes no apps, and OpenClaw does not attempt installation or authentication.

The runtime app inventory serves as the accessibility check for the target session, covering both migrated curated plugins and manually configured workspace plugins. During Codex harness session setup, a restrictive thread app configuration is computed from the enabled and accessible plugin apps. This configuration is not recalculated per turn, so /codex plugins enable/disable only affect new Codex conversations. To apply the change in an active conversation, use /new or /reset.

V1 support boundary

• Only openai-curated plugins already installed in the source Codex app-server inventory qualify for migration.
• The runtime also supports explicit workspace-directory entries on app-server builds where plugin/list implements marketplaceKinds and returns remotePluginId for pathless workspace summaries. These entries must use their exact marketplace-qualified summary.id and must already be installed, enabled, and app-accessible. A rejected workspace list request triggers the existing per-plugin marketplace_missing diagnostic. If marketplace, plugin, detail, or app evidence is missing, no workspace app is exposed. Curated inventory from the default list request remains usable.
• App-backed source plugins must pass the migration-time subscription gate. --verify-plugin-apps adds the source app-inventory gate. Subscription-gated accounts, and accounts in verification mode with inaccessible, disabled, or missing source apps, or app-inventory refresh failures, are reported as skipped manual items rather than enabled config entries. Unreadable plugin details are skipped before the app-inventory gate.
• Migration writes explicit plugin identities (marketplaceName and pluginName) and does not write local marketplacePath cache paths.
• codexPlugins.enabled is the sole global enablement switch. There is no plugins["*"] wildcard or config key that grants arbitrary install authority.
• Non-curated marketplaces, cached plugin bundles, hooks, and Codex config files are preserved in the migration report for manual review and are not automatically activated. The runtime accepts manually configured workspace-directory entries, but other marketplaces remain unsupported.

App inventory and ownership

OpenClaw reads Codex app inventory via app-server app/list, caches it in memory for one hour, and asynchronously refreshes stale or missing entries. The cache is process-local, so restarting the CLI or gateway clears it, and OpenClaw rebuilds it from the next app/list read.

Migration and runtime use separate cache keys:

• Source migration verification uses the source Codex home and start options. It runs only with --verify-plugin-apps and forces a fresh source app/list traversal for that planning run.
• Target runtime setup uses the target agent's Codex app-server identity when building the thread app config. Curated plugin activation invalidates that target cache key and force-refreshes it after plugin/install. workspace-directory setup never executes this activation path.

A plugin app is exposed only when OpenClaw can map it back to the configured plugin through stable ownership, such as an exact app id from plugin detail, a known MCP server name, or unique stable metadata. Display-name-only or ambiguous ownership is excluded until the next inventory refresh proves ownership.

Connected account apps

Owner-operated agents can opt into every app already connected to their Codex account without needing a matching plugin package:

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

When a new native Codex thread is established, allow_all_plugins: true takes a complete app/list snapshot and admits only apps marked accessible for that account. It does not install, authenticate, or enable apps globally. Existing threads keep their persisted app set. To pick up newly connected or revoked apps, use /new, /reset, or restart the gateway.

Account apps inherit the global codexPlugins.allow_destructive_actions value, which accepts true, false, "auto", or "ask". Explicit per-plugin policy overrides the global policy for overlapping app ids. Inventory failures fail closed instead of falling back to an unrestricted default.

Thread app config

OpenClaw injects a restrictive config.apps patch for the Codex thread. _default is disabled, and only apps owned by enabled configured plugins or accessible account apps admitted by allow_all_plugins are enabled.

The destructive_enabled on each app comes from the effective global or per-plugin allow_destructive_actions policy. true, "auto", and "ask" all set destructive_enabled: true, and false sets it false. Codex still enforces destructive tool metadata from its native app tool annotations. _default is disabled with open_world_enabled: false, and enabled plugin apps get open_world_enabled: true. OpenClaw does not expose a separate plugin-level open-world policy knob and does not maintain per-plugin destructive tool-name deny lists.

Tool approval mode defaults to automatic for admitted apps, so non-destructive read tools run without a same-thread approval prompt. Destructive tools remain controlled by each app's destructive_enabled policy.

Destructive action policy

Destructive plugin elicitations are allowed by default for configured Codex plugins, while unsafe schemas and ambiguous ownership fail closed.

• The default for allow_destructive_actions is set to true.
• A per-plugin allow_destructive_actions can override the global policy for that specific plugin.
• When false is used, OpenClaw returns a deterministic decline.
• With true, OpenClaw automatically accepts only schemas it considers safe and can map to an approval response, like a boolean approve field.
• For "auto", OpenClaw makes destructive plugin actions visible to Codex, then converts ownership-verified MCP approval requests into OpenClaw plugin approvals before delivering the Codex approval response.
• Under "ask", OpenClaw applies the same Codex write or destructive gating as "auto", clears any persistent Codex per-tool approval overrides for the app before the thread begins, and only permits one-shot approval or denial so that durable approvals cannot block later write-action prompts. For each authorized app using "ask", OpenClaw designates Codex's human approvals reviewer for that app, causing Codex to send its approval requests to OpenClaw; other apps and non-app thread approvals retain their configured reviewer and policy.
• If a plugin identity is missing, ownership is ambiguous, a turn id is missing or mismatched, or the elicitation schema is unsafe, the request is declined without prompting.

Troubleshooting

Workspace plugin is installed but not visible: confirm the workspace plugin/list result reports the exact configured ID as installed and enabled, then confirm app/list reports every owned app accessible for the same Codex account. OpenClaw can enable an accessible app for the thread even when the account inventory currently reports that app disabled. If you changed that state after the gateway cached app inventory, wait for the one-hour cache refresh or restart the gateway, then use /new or /reset. OpenClaw does not repair or authenticate workspace plugins. If the explicit workspace list request is rejected, each enabled workspace entry reports marketplace_missing; unrelated curated entries still proceed from the default list response.

For plugin_detail_unavailable, a pathless workspace summary must include remotePluginId; OpenClaw keeps owned apps hidden when that selector or the subsequent plugin/read result is unavailable. For plugin_activation_failed, curated plugins may report a marketplace, auth, or post-install refresh failure. A workspace plugin reports this code when it is not already active; install, enable, and authenticate it outside OpenClaw.

Config changed but the agent cannot see the plugin: run /codex plugins list to confirm the configured state, then /new or /reset. Existing Codex thread bindings keep the app config they started with until OpenClaw establishes a new harness session or replaces a stale binding.

Destructive action is declined: check the global and per-plugin allow_destructive_actions values. Even with true, "auto", or "ask", unsafe elicitation schemas and ambiguous plugin identity still fail closed.

Related

• Codex harness
• Codex harness reference
• Codex harness runtime
• Configuration reference
• Migrate CLI