Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 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: 
openclaw migrate codex --dry-run
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: 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.