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

---
summary: "Configure migrated native Codex plugins for Codex-mode OpenClaw agents"
title: "Native Codex plugins"
read_when:
  - 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](/plugins/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 PI 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:

```bash
openclaw migrate codex --dry-run
```

Apply the migration when the plan looks right:

```bash
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:

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

After changing `codexPlugins`, use `/new`, `/reset`, or restart the gateway so
future Codex harness sessions start with the updated app set.

## 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. Runtime app inventory is the
accessibility check. 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.

## 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.
- 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.

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 prompted by default for plugin apps because OpenClaw does
not have an interactive app-elicitation UI in this same-thread path.

## Destructive action policy

Destructive plugin elicitations fail closed by default:

- Global `allow_destructive_actions` defaults to `false`.
- 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.

**`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 `/new`, `/reset`, or
restart the gateway. 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](/plugins/codex-harness)
- [Codex harness reference](/plugins/codex-harness-reference)
- [Codex harness runtime](/plugins/codex-harness-runtime)
- [Configuration reference](/gateway/configuration-reference#codex-harness-plugin-config)
- [Migrate CLI](/cli/migrate)