openclaw/docs/plugins/codex-native-plugins.md

summary, title, read_when

summary	title	read_when
Configure migrated native Codex plugins for Codex-mode OpenClaw agents	Native Codex plugins	You want Codex-mode OpenClaw agents to use native Codex plugins You are migrating source-installed openai-curated Codex plugins You are troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics

Native Codex plugin support lets a Codex-mode OpenClaw agent use Codex app-server's own app and plugin capabilities inside the same Codex thread that handles the OpenClaw turn.

OpenClaw does not translate Codex plugins into synthetic codex_plugin_* OpenClaw dynamic tools. Plugin calls stay in the native Codex transcript, and Codex app-server owns the app-backed MCP execution.

Use this page after the base Codex harness is working.

Requirements

• The selected OpenClaw agent runtime must be the native Codex harness.
• plugins.entries.codex.enabled must be true.
• plugins.entries.codex.config.codexPlugins.enabled must be true.
• V1 supports only openai-curated plugins that migration observed as source-installed in the source Codex home.
• The target Codex app-server must be able to see the expected marketplace, plugin, and app inventory.

codexPlugins has no effect on OpenClaw runs, normal OpenAI provider runs, ACP conversation bindings, or other harnesses because those paths do not create Codex app-server threads with native apps config.

Quickstart

Preview migration from the source Codex home:

openclaw migrate codex --dry-run

Use strict source app verification when you want migration to check source app accessibility before planning native plugin activation:

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

Apply the migration when the plan looks right:

openclaw migrate apply codex --yes

Migration writes explicit codexPlugins entries for eligible plugins and calls Codex app-server plugin/install for selected plugins. A typical migrated config looks 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",
              },
            },
          },
        },
      },
    },
  },
}

After changing codexPlugins, new Codex conversations pick up the updated app set automatically. Use /new or /reset to refresh the current conversation. A gateway restart is not required for plugin enable or disable changes.

Manage plugins from chat

Use /codex plugins when you want to inspect or change 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 output shows the configured plugin keys, on/off state, Codex plugin name, and marketplace from plugins.entries.codex.config.codexPlugins.plugins.

enable and disable write only to OpenClaw config at ~/.openclaw/openclaw.json; they do not edit ~/.codex/config.toml or install new Codex plugins. Only the owner or a gateway client with the operator.admin scope can change plugin state.

Enabling a configured plugin also turns on the global codexPlugins.enabled switch. If the plugin was written disabled because migration returned auth_required, reauthorize the app in Codex before enabling it in OpenClaw.

How native plugin setup works

The integration has three separate states:

• Installed: Codex has the local plugin bundle in the target app-server runtime.
• Enabled: OpenClaw config is willing to make the plugin available to Codex harness turns.
• Accessible: Codex app-server confirms the plugin's app entries are available for the active account and can be mapped to the migrated plugin identity.

Migration is the durable install/eligibility step. During planning, OpenClaw reads source Codex plugin/read details and checks that the source Codex app-server account response is a ChatGPT subscription account. Non-ChatGPT or missing account responses skip app-backed plugins with codex_subscription_required. By default, migration does not call source app/list; 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. In that mode, account lookup transport failures fall through to the source app-inventory gate. Runtime app inventory is the target-session accessibility check after migration. Codex harness session setup then computes a restrictive thread app config for the enabled and accessible plugin apps.

Thread app config is computed when OpenClaw establishes a Codex harness session or replaces a stale Codex thread binding. It is not recomputed on every turn, so /codex plugins enable and /codex plugins disable affect new Codex conversations. Use /new or /reset when the current conversation should pick up the updated app set.

V1 support boundary

V1 is intentionally narrow:

• Only openai-curated plugins that were already installed in the source Codex app-server inventory are migration-eligible.
• App-backed source plugins must pass the migration-time subscription gate. --verify-plugin-apps adds the source app-inventory gate. Subscription-gated accounts plus, in verification mode, inaccessible, disabled, missing source apps or source app-inventory refresh failures are reported as skipped manual items instead of enabled config entries. Unreadable plugin details are skipped before the source app-inventory gate.
• Migration writes explicit plugin identities with marketplaceName and pluginName; it does not write local marketplacePath cache paths.
• codexPlugins.enabled is the global enablement switch.
• There is no plugins["*"] wildcard and no config key that grants arbitrary install authority.
• Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files are preserved in the migration report for manual review.

App inventory and ownership

OpenClaw reads Codex app inventory through app-server app/list, caches it for one hour, and refreshes stale or missing entries asynchronously. The cache is in memory only; restarting the CLI or gateway drops 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 source app-server start options. This runs only when --verify-plugin-apps is set, and it forces a fresh source app/list traversal for that planning run.
• Target runtime setup uses the target agent's Codex app-server identity when it builds the Codex thread app config. Plugin activation invalidates that target cache key and then force-refreshes it after plugin/install.

A plugin app is exposed only when OpenClaw can map it back to the migrated plugin through stable ownership:

• exact app id from plugin detail
• known MCP server name
• unique stable metadata

Display-name-only or ambiguous ownership is excluded until the next inventory refresh proves ownership.

Thread app config

OpenClaw injects a restrictive config.apps patch for the Codex thread: _default is disabled and only apps owned by enabled migrated plugins are enabled.

OpenClaw sets app-level destructive_enabled from the effective global or per-plugin allow_destructive_actions policy and lets Codex enforce destructive tool metadata from its native app tool annotations. The _default app config is disabled with open_world_enabled: false. Enabled plugin apps are emitted with open_world_enabled: true; OpenClaw does not expose a separate plugin open-world policy knob and does not maintain per-plugin destructive tool-name deny lists.

Tool approval mode is automatic by default for plugin apps so non-destructive read tools can run without a same-thread approval UI. Destructive tools remain controlled by each app's destructive_enabled policy.

Destructive action policy

Destructive plugin elicitations are allowed by default for migrated Codex plugins, while unsafe schemas and ambiguous ownership still fail closed:

• Global allow_destructive_actions defaults to true.
• Per-plugin allow_destructive_actions overrides the global policy for that plugin.
• When policy is false, OpenClaw returns a deterministic decline.
• When policy is true, OpenClaw auto-accepts only safe schemas it can map to an approval response, such as a boolean approve field.
• Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn id, or an unsafe elicitation schema declines instead of prompting.

Troubleshooting

auth_required: migration installed the plugin, but one of its apps still needs authentication. The explicit plugin entry is written disabled until you reauthorize and enable it.

app_inaccessible, app_disabled, or app_missing: migration did not install the plugin because the source Codex app inventory did not show all owned apps as present, enabled, and accessible while --verify-plugin-apps was set. Reauthorize or enable the app in Codex, then rerun migration with --verify-plugin-apps.

app_inventory_unavailable: migration did not install the plugin because strict source app verification was requested and source Codex app inventory refresh failed. Fix source Codex app-server access or retry without --verify-plugin-apps if you accept the faster account-gated plan.

codex_subscription_required: migration did not install the app-backed plugin because the source Codex app-server account was not logged in with a ChatGPT subscription account. Log in to the Codex app with subscription auth, then rerun migration.

codex_account_unavailable: migration did not install the app-backed plugin because the source Codex app-server account could not be read. Fix source Codex app-server auth or rerun with --verify-plugin-apps if you want source app inventory to decide eligibility when account lookup fails.

marketplace_missing or plugin_missing: the target Codex app-server cannot see the expected openai-curated marketplace or plugin. Rerun migration against the target runtime or inspect Codex app-server plugin status.

app_inventory_missing or app_inventory_stale: app readiness came from an empty or stale cache. OpenClaw schedules an async refresh and excludes plugin apps until ownership and readiness are known.

app_ownership_ambiguous: app inventory only matched by display name, so the app is not exposed to the Codex thread.

Config changed but the agent cannot see the plugin: use /codex plugins list to confirm the configured state, then use /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 when policy is true, unsafe elicitation schemas and ambiguous plugin identity still fail closed.

Related

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