OpenClaw Codex plugin integration spec

codex-v2.md

Codex Plugin Integration

Summary

OpenClaw should be able to use plugins that are available from the user's Codex installation while preserving the way the Codex client activates and executes plugins. The minimal implementation is a bridge inside the bundled codex plugin that:

• inventories Codex plugin marketplace entries through Codex app-server,
• installs or re-enables selected plugin bundles through plugin/install,
• refreshes plugin, skill, hook, app, and MCP runtime state after install,
• publishes one OpenClaw tool per enabled plugin,
• invokes the plugin by starting an isolated Codex app-server thread with the installed plugin runtime available,
• applies OpenClaw configuration for plugin enablement and destructive-action handling

The bridge should treat Codex app-server as the authority for plugin bytes, installed skills, authentication, plugin MCP wiring, and app execution. OpenClaw owns discovery policy, activation policy, tool exposure, migration, and the fail-closed destructive-action decision.

Goals

• Support plugin usage inside OpenClaw for plugins that are already installed in the user's Codex home.
• Support plugin/install for those migrated Codex plugins so associated skills, apps, MCP servers, and hooks are activated in the OpenClaw-managed Codex app-server runtime.
• Support migration through openclaw migrate codex.
• Support enablement and disablement per plugin.
• Support allow_destructive_actions globally and per plugin with values always and never.
• Reuse the bundled codex plugin and Codex app-server lifecycle already present in OpenClaw.
• Preserve OpenClaw's tool policy model so plugin tools can still be allowed or denied by normal tool configuration.

Non-Goals

• Installing plugins that migration did not observe as installed in the source Codex home.
• User-configurable plugin installation policy. V1 activation eligibility is derived from migration state, not from an install config switch.
• Supporting custom marketplaces.
• Supporting plugin elicitations as an interactive OpenClaw approval flow.
• Reimplementing Codex plugin execution outside Codex app-server.
• Supporting plugins outside the Codex harness.
• Supporting general Codex plugin MCP server passthrough beyond app-backed plugin invocation in the first implementation.

Proposed User Model

{
  "plugins": {
    "entries": {
      "codex": {
        "enabled": true,
        "config": {
          "appServer": {
            "mode": "guardian"
          },
          "codexPlugins": {
            "enabled": true,
            "allow_destructive_actions": "never",
            "plugins": {
              "*": {
                "enabled": true
              },
              "google-calendar": {
                "enabled": true,
                "marketplaceName": "openai-curated",
                "pluginName": "google-calendar",
                "allow_destructive_actions": "always"
              },
              "slack": {
                "enabled": false,
                "marketplaceName": "openai-curated",
                "pluginName": "slack"
              }
            }
          }
        }
      }
    }
  }
}

Semantics:

• codexPlugins.enabled enables the bridge.
• plugins["*"].enabled: true means all discovered plugins are exposed unless a plugin overrides it.
• plugins.<id>.enabled: false hides that plugin from OpenClaw even if Codex has it installed.
• plugins.<id>.marketplaceName and plugins.<id>.pluginName are stable migration metadata; OpenClaw resolves the local marketplacePath from Codex app-server inventory when calling plugin/install.
• allow_destructive_actions defaults to never.
• plugin-level allow_destructive_actions overrides the global bridge setting.
• if a plugin is explicitly disabled in OpenClaw config, OpenClaw does not install, re-enable, or expose it.

Defaults

When user sets up codex provider for first time with codex harness, enable all installed plugins but set allow_destructive_actions to false. Should later be changed to on-request when we supprot elicitations.

Fast Follow

• add plugins to codex migrate command
• support elicitations