Native Codex plugins

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. Plugin calls stay in the native Codex transcript; Codex app-server owns app-backed MCP execution. OpenClaw does not translate Codex plugins into synthetic codex_plugin_* OpenClaw dynamic tools.

Use this page after the base Codex harness is working.

Requirements

• The agent runtime must be the native Codex harness.
• plugins.entries.codex.enabled is true.
• plugins.entries.codex.config.codexPlugins.enabled is true.
• Codex app-server reports 0.149.0 or newer. The official plugin ships @openai/codex 0.153.4; newer custom, remote, and macOS desktop-owned binaries continue with a compatibility warning and normal runtime validation.
• The target Codex app-server can see the expected marketplace, plugin, and app inventory.
• Migration supports only openai-curated plugins that it observed as source-installed in the source Codex home. Codex serves the same catalog to API-key and Bedrock accounts under the openai-api-curated wire name; OpenClaw treats both names as the one curated catalog, so configured openai-curated plugins resolve from either.
• Native runtime support also includes other marketplaces already available to Codex, such as openai-bundled, openai-primary-runtime, workspace-directory, and marketplace manifests in the current repository. Plugins remain unavailable until an owner or operator.admin explicitly installs or enables their marketplace-qualified identity.

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

OpenAI-side Codex account, app availability, and workspace app/plugin controls come from the signed-in Codex account. See Using Codex with your ChatGPT plan for the OpenAI account and admin model.

Quickstart

The source Codex home is the Codex CLI state directory you are migrating from: ~/.codex by default, or CODEX_HOME when that variable is set. See openclaw migrate to point at a different one with --from.

Preview migration from the source Codex home:

openclaw migrate codex --dry-run

Add --verify-plugin-apps to make migration read the source installed app snapshot and app metadata, requiring every owned app to be present, enabled, and accessible before planning native 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 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",              },            },          },        },      },    },  },}

Migration remains limited to openai-curated. To find another plugin that Codex can already see, list the available marketplace catalog and install the exact marketplace-qualified identity:

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

Codex discovers repository marketplaces from .agents/plugins/marketplace.json in the current conversation workspace. An owner does not need to add that marketplace to OpenClaw configuration before listing or installing its plugins. Official bundled, primary-runtime, curated, workspace, shared, and personal marketplaces depend on the signed-in Codex account and upstream feature or administrator policies. When Codex requires marketplace sources to be explicitly configured or allowlisted, those requirements still apply; OpenClaw does not bypass them.

Installation writes an explicit configuration entry such as:

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

The install command checks the authenticated owner or administrator before it calls Codex plugin/install. Codex continues to enforce marketplace source, workspace administrator, account, and connector-authentication policies. Remote plugins that require a Codex installation interstitial, or do not report whether one is required, must be installed in Codex first; rerun the OpenClaw install command afterward to authorize the already-installed plugin. OpenClaw keeps apps hidden when the response omits the exact marketplace, plugin identity, detail identity, or app-readiness evidence. If a connector requires additional sign-in, complete that authorization before expecting the plugin's tools to become available.

Installing the plugin bundle and configuring OpenClaw app access do not confirm hosted app connections. When installation returns apps that still need sign-in, OpenClaw provides Open <app> in ChatGPT links to the app pages returned by Codex. Sign in with the same ChatGPT account and workspace used by the Codex harness. Opening a link does not verify the connection or make its tools callable in the current conversation. If the browser shows a directory instead of the app, or no safe link is available, run /apps in Codex CLI and select the app there. Responses show up to five app links and explicitly report additional apps to review in Codex CLI. These links are for hosted ChatGPT apps; native MCP server setup remains separate.

An app can also request sign-in when you first use one of its tools. In the Control UI, choose Open link to open the requested page in a separate tab. The question stays pending while you sign in. After completing the browser step, select I've completed this step and submit to let Codex refresh and retry. Opening the link alone does not resume the tool or confirm a connection. Clients without a link action still show the URL to open manually before answering.

For setup completed outside an active Codex sign-in prompt, refresh hosted app inventory for the current Codex account/runtime:

/codex plugins refresh

This refresh covers all hosted apps in that runtime; it is not a per-plugin backend refresh. A plugin's Refresh hosted apps button runs this command. The separate Check status button inspects only that plugin without refreshing hosted tools. Neither action changes authorization or the current conversation's app policy. Use /new or /reset after connecting, then inspect status in the new conversation.

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

Scheduled automations

When an authenticated owner creates an automation from a Codex turn, OpenClaw captures the app IDs and approval limits callable on that exact Codex thread. The stored authority is bound to the creator's prepared Codex profile and account. Scheduled runs intersect that cap with current Codex policy and app availability. They never gain new app IDs or a broader destructive, open-world, or approval ceiling. Tools added later within an already captured app may run only when both the stored ceiling and current policy allow them.

Scheduled app calls are unattended. Only actions explicitly allowed both when the job was created and when it runs can proceed without a prompt. An action that still requires approval or elicitation is declined. A changed account, runtime, revoked app, narrower policy, or unavailable inventory stops before app execution and reports how to restore access or reauthorize the automation. Model fallbacks cannot move this authority to another runtime or account.

Jobs created before app authority capture may keep their ordinary OpenClaw tool cap and continue non-app work, but cannot recover Codex app access automatically. Recreate or reauthorize only a job that needs app access, from a fresh authenticated owner turn. See Automations. Ordinary edits preserve captured app authority. Explicitly replacing a job's toolsAllow cap without a fresh authenticated Codex authority capture clears that authority; the next run reports that app access requires reauthorization. An update from a fresh authenticated owner turn can instead capture and store a new app ceiling for the updated job.

Manage plugins from chat

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

/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 is an alias for /codex plugins list. The list shows each configured plugin's key, on/off state, Codex plugin name, and marketplace from plugins.entries.codex.config.codexPlugins.plugins.

available [query] [--page <n>] requires an owner or operator.admin. It reads Codex's marketplace catalogs using the bound workspace, including repository-local plugins, without installing or enabling them. Search matches names, display titles, publishers, marketplaces, and descriptions case-insensitively across the full returned catalog before showing ten results per page. Next page and Previous page preserve your search; channels without buttons show the commands to send. Search text is limited to 100 characters. Use -- before literal search text containing --page.

Results show display titles, publishers, and descriptions when supplied by Codex, with explicit placeholders for missing publishers or descriptions. They retain marketplace-qualified identities and availability restrictions; display titles and publisher names do not change installation identity. This searches Codex catalogs, not OpenClaw's plugin registry or every ChatGPT connection. The owner-scoped codex_plugins model tool uses the same search matching and is also read-only: it can recommend an exact install command but cannot install, enable, or add a marketplace.

status <name>@<marketplace> [page] inspects exactly one configured plugin and requires an owner or operator.admin. The qualified identity is required; bare status or an unqualified name returns usage guidance pointing to list.

Status shows bundle installation, marketplace restrictions, Codex enablement, and shared OpenClaw app access separately. Changes to OpenClaw app access take effect on the next message; they do not install or enable the Codex bundle.

App results show at most five apps per page. A ChatGPT app-page link requires confirmed hosted-app runtime support, an available plugin under its catalog policy, and matching authorized metadata from app/read. A plugin's app declaration or setup URL alone does not establish that access. OpenClaw app access can be disabled while an eligible ChatGPT page remains available; opening that page does not enable OpenClaw app access. Plugins without hosted apps receive no ChatGPT connection or setup guidance. Status does not assess their skills or native MCP server readiness.

The selected agent, auth profile, conversation workspace, and account email/plan are shown when available. ChatGPT workspace identity remains unknown when Codex does not report it; use the same account and workspace in the browser when opening an eligible hosted app page.

Status uses app/read for app metadata and displays the enabled and callable flags returned by app/installed. The runtime scope is the bound Codex thread when available, or the account otherwise. These flags reflect effective Codex configuration and the current runtime tool snapshot; they are separate from OpenClaw app access. Status does not infer a separate connection state. Missing app records and failed reads are reported explicitly instead of becoming false flags.

/codex plugins refresh requires owner or operator.admin authority and confirmed hosted-app support in the selected Codex account/runtime. It works without a configured plugin. It invalidates that runtime's OpenClaw app cache, calls Codex app/installed with forceRefresh: true and no threadId, and reads metadata for the returned apps. It does not refresh marketplace catalogs, reinstall plugin bundles, or reload native MCP servers.

After refreshing, use /codex plugins status <name>@<marketplace> to inspect one plugin. Status never forces a hosted refresh. Disabled or blocked plugins remain disabled or blocked, but do not prevent an otherwise permitted hosted refresh.

A completed request does not prove that Codex replaced its snapshot or that a live tool call will succeed. Refresh never installs, enables, authenticates, or replaces a thread, and does not reload other conversations. After connecting, use /new or /reset and inspect status again. Browser setup does not change OpenClaw app access; local app-access changes take effect on the next message. Unsupported methods, cancellation, and refresh failures provide a retry action without treating the previous inventory as confirmed.

install, enable, and disable require the owner or a gateway client with the operator.admin scope. OpenClaw's reserved /codex command is dispatched before agent invocation, so a model-generated recommendation does not count as installation approval. For a plugin that Codex has not installed yet, install calls the Codex app-server and records the explicit plugin policy only after installation succeeds. If Codex confirms that the plugin is already installed and enabled, the same command records its authorization without installing it again. enable and disable change OpenClaw's persisted policy; qualified identities and existing configuration keys are both accepted.

Installing or enabling a configured plugin also turns on the global codexPlugins.enabled switch without enabling allow_all_plugins. If a plugin reports auth_required, authorize the app in Codex before starting a new conversation. Authorization remains in effect for later conversations until the plugin is disabled or the upstream account or workspace revokes access.

Only install plugins you trust. A Codex plugin can contribute skills, apps, MCP servers, and hooks. Some hooks can participate in permission decisions, so explicit installation trusts the selected plugin's code; it is not a security review or an isolation boundary.

How native plugin setup works

The integration tracks three states:

For openai-curated plugins, migration is the durable install/eligibility step:

• During planning, OpenClaw reads source Codex plugin/read details and checks the source Codex app-server account. codex_subscription_required means account/read positively identified an API-key or other non-ChatGPT account; a missing account is not evidence that a subscription is absent.
• By default, migration skips source app inventory calls: app-backed source plugins that pass the account gate are planned without source app accessibility verification. A missing account or failed account/read skips them with codex_account_unavailable.
• With --verify-plugin-apps, migration takes a fresh source app/installed snapshot, fetches authenticated metadata with app/read, and requires every owned app to be present, enabled, and accessible in the source Codex account before planning native activation. If account/read is missing or fails, strict verification can still prove access through the source app-server's configured bearer or header authentication. A positively identified non-ChatGPT account remains ineligible.

For explicitly approved plugins from any discovered marketplace, OpenClaw uses its plugin/installed snapshot and plugin/read details to establish the exact marketplace-qualified identity and app ownership. The installed-only check during ordinary thread setup is read-only; apps from disabled or unapproved plugins stay denied. Owner-issued installation is the explicit mutation path. Missing or ambiguous ownership fails closed instead of granting account-wide access.

Runtime app inventory is the target-session accessibility check for both migrated curated plugins and manually configured workspace plugins. Before enabled-policy turns, including warm reuse and cold resume, the Codex harness rebuilds the restrictive thread app policy from current native settings while reusing its app inventory and plugin metadata caches.

Support boundary

• Only openai-curated plugins already installed in the source Codex app-server inventory are migration-eligible.
• Runtime supports explicitly approved plugins from Codex-discovered official, workspace, personal, shared, and repository-local marketplaces. A missing marketplace, plugin, ownership detail, or app readiness evidence exposes no plugin app.
• Positively identified non-ChatGPT source accounts fail the subscription gate. Missing or unreadable source accounts are unavailable by default. --verify-plugin-apps can instead establish access through authenticated source app inventory, including bearer- or header-authenticated app-servers. Inaccessible, disabled, or missing source apps and inventory refresh failures remain skipped manual items. Unreadable plugin details are skipped before the app-inventory gate.
• Migration writes explicit plugin identities (marketplaceName and pluginName); it does not write local marketplacePath cache paths.
• codexPlugins.enabled is the only global enablement switch; there is no plugins["*"] wildcard or config key that grants arbitrary install authority.
• Migration does not automatically import non-curated marketplaces, cached plugin bundles, hooks, or Codex config files. Use /codex plugins available and an owner-issued /codex plugins install <plugin>@<marketplace> command to opt into an additional discovered plugin.
• OpenClaw does not add new Git or local marketplace sources in this flow. Additional sources must already be configured in Codex or be discoverable from the bound repository.

App inventory and ownership

OpenClaw first reads and caches one plugin/installed snapshot scoped to the target Codex app-server and configured workspace. That snapshot covers plugins from the marketplaces visible in that scope, including disabled plugin identities; failed or incomplete snapshots are never cached. plugin/read is limited to exact configured plugin details required to establish ownership. Explicit discovery queries plugin/list with the conversation workspace to find repository marketplaces. Routine setup retains its existing curated recovery behavior; additional marketplace installation requires the explicit owner or administrator command.

OpenClaw reads installed app runtime state through app/installed and fetches canonical app metadata with app/read in batches of at most 100 app IDs. The first read force-refreshes a cold installed runtime snapshot. When multiple configured curated plugins are installed, OpenClaw combines their cache invalidations into a single app-inventory refresh. Ordinary cached reads do not force a connector refresh for every new thread. OpenClaw caches the combined inventory in memory for one hour and refreshes stale or missing entries asynchronously. The cache is process-local; restarting the CLI or gateway drops it.

Missing inventory methods, authentication errors, transport failures, and connector refresh failures do not admit app tools. Ordinary turns, including those using allow_destructive_actions: "ask", can continue with native apps disabled when inventory exceeds its startup budget. Scheduled runs stop if their captured app policy cannot be revalidated within that budget.

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 runtime snapshot and metadata read for that planning run.
• Target runtime setup uses the target agent's Codex app-server identity when building and verifying the thread app config. Curated plugin activation invalidates that target cache key, then force-refreshes it after plugin/install. Explicit marketplace installation refreshes the same target runtime state before subsequent conversations use the plugin.

A plugin app is exposed only when OpenClaw can map it back to the configured plugin through stable ownership: 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 requiring a matching plugin package:

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

allow_all_plugins: true reads the installed app snapshot and authenticated metadata when a new native Codex thread is established. It admits only account-accessible apps. Codex must also confirm each admitted app is enabled and callable for that thread. OpenClaw does not install, authenticate, or enable apps globally. Existing threads keep their persisted app set; use /new, /reset, or restart the gateway to pick up newly connected or revoked apps.

An explicitly disabled configured plugin always overrides account-wide app access. Because Codex app/read omits a disabled workspace plugin's display names, OpenClaw uses its plugin/installed snapshot and reads only that exact configured plugin's details to reserve its owned app IDs. This narrow, read-only check does not discover unrelated marketplaces, activate the plugin, or grant its apps. If the disabled plugin's ownership cannot be established, the account-wide app selection fails closed.

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.

An app can be installed and authenticated but non-callable in the account-wide snapshot while _default is disabled. OpenClaw provisionally admits only ownership-proven, policy-allowed apps, creates the restrictive thread, and then rereads app/installed once with the resulting thread ID and forceRefresh: false. If the snapshot reports an app missing, disabled, or non-callable, OpenClaw logs one warning listing the unavailable apps and continues with the remaining tools. Codex still enforces the thread's effective app, managed, workspace, and tool policies. An unavailable optional app does not block unrelated chat or heartbeat runs.

If the snapshot request itself fails, the provisional thread is never bound or used. OpenClaw deletes a failed persistent provisional thread, unsubscribes a failed ephemeral thread, and retires the app-server connection if safe cleanup cannot be confirmed.

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; 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 stay 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:

• Global allow_destructive_actions defaults to true.
• Per-plugin allow_destructive_actions overrides the global policy for that plugin.
• false: OpenClaw returns a deterministic decline.
• true: OpenClaw auto-accepts only safe schemas it can map to an approval response, such as a boolean approve field.
• "auto": OpenClaw exposes destructive plugin actions to Codex, then turns ownership-proven MCP approval elicitations into OpenClaw plugin approvals before returning the Codex approval response.
• "ask": OpenClaw uses the same Codex write/destructive gating as "auto", overrides saved per-tool and per-account approvals in the native thread's configuration, and offers only one-shot approval or denial. Saved native settings stay unchanged, and user-config reloads preserve the thread's approval policy. These checks also run before reusing a thread or answering a /btw side question. Changed override keys rebuild the thread with current policy. For each admitted app using "ask", OpenClaw selects Codex's human approvals reviewer for that app so Codex sends its approval elicitations to OpenClaw; other apps and non-app thread approvals keep their configured reviewer and policy.
• Missing plugin identity, ambiguous ownership, a missing or mismatched turn id, or an unsafe elicitation schema declines instead of prompting.

Apps outside the admitted policy stay disabled even if native Codex settings enable them. Native settings must be verified before an enabled policy can admit app tools. When no app can be admitted, Codex's app tool surface is disabled without reading native app settings. Disabling plugin apps also skips app inventory discovery. Active legacy managed app settings outrank native thread configuration and prevent app admission; move those app settings to a supported user or project configuration layer. Native administrative requirements remain authoritative.

Troubleshooting

Workspace plugin is installed but not visible: confirm the workspace plugin/installed snapshot reports the exact configured ID as installed and enabled, then confirm app/installed returns every owned app for the same Codex account and app/read returns its metadata. An app disabled only by the account-wide default can become callable after OpenClaw starts and verifies its explicitly configured thread. Revoked auth, missing metadata, disabled workspace plugins, and Codex managed or workspace restrictions still block access. Reauthorize or repair those upstream conditions before starting a new thread. If you changed that state after the gateway cached app inventory, run /codex plugins refresh, then use /new or /reset. OpenClaw does not authenticate plugin apps on the owner's behalf.

For plugin_detail_unavailable, verify that the exact installed marketplace and plugin identity select a matching plugin/read result. OpenClaw keeps owned apps hidden when that selector or ownership detail is unavailable. For plugin_activation_failed, inspect the marketplace, app authorization, and post-install refresh diagnostics. An explicitly approved plugin must be installed, enabled, and authenticated before its apps can appear in a thread.

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