Native Codex plugins

기준일: 2026-07-26
공식 기준: Native Codex plugins

Native Codex plugins 문서는 OpenClaw 공식 문서(plugins/codex-native-plugins)를 한국어로 정리한 가이드입니다. Configure native Codex plugins for Codex-mode OpenClaw agents 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Configure native Codex plugins for Codex-mode OpenClaw agents

한국어 가이드 범위: plugins/codex-native-plugins 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 요구사항
• Quickstart
• Manage plugins from chat
• How native plugin setup works
• V1 support boundary
• App inventory and ownership
• Connected account apps
• Thread app config
• Destructive action policy
• 트러블슈팅
• 관련 문서

상세 내용

본문

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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

요구사항

source-installed in the source Codex home.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• The agent runtime must be the native Codex harness.
• plugins.entries.codex.enabled is true.
• plugins.entries.codex.config.codexPlugins.enabled is true.
• The target Codex app-server can see the expected marketplace, plugin, and
• Migration supports only openai-curated plugins that it observed as
• Manually configured workspace-directory plugins require a Codex app-server

Quickstart

Preview migration from the source Codex home:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw migrate codex --dry-run

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

openclaw migrate apply codex --yes

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

Manage plugins from chat

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

/codex plugins
/codex plugins list
/codex plugins disable google-calendar
/codex plugins enable google-calendar

How native plugin setup works

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• During planning, OpenClaw reads source Codex plugin/read details and
• By default, migration skips the source app/list call: app-backed source
• With --verify-plugin-apps, migration takes a fresh source app/list

State	Meaning
Installed	Codex has the plugin bundle in the target app-server runtime.
Enabled	Codex reports the plugin enabled, and OpenClaw config allows it for Codex harness turns.
Accessible	Codex app-server confirms the plugin's app entries are available for the active account and map to the configured plugin identity.

V1 support boundary

app-server inventory are migration-eligible.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Only openai-curated plugins already installed in the source Codex
• Runtime also supports explicit workspace-directory entries on app-server
• App-backed source plugins must pass the migration-time subscription gate.
• Migration writes explicit plugin identities (marketplaceName and
• codexPlugins.enabled is the only global enablement switch; there is no
• Non-curated marketplaces, cached plugin bundles, hooks, and Codex config

App inventory and ownership

OpenClaw reads Codex app inventory through app-server app/list, caches it in memory for one hour, and refreshes stale or missing entries asynchronously. The cache is process-local; restarting the CLI or gateway drops it, and OpenClaw rebuilds it from the next app/list read.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Source migration verification uses the source Codex home and start
• Target runtime setup uses the target agent's Codex app-server identity when

Connected account apps

Owner-operated agents can opt into every app already connected to their Codex account without requiring a matching plugin package:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

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.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Destructive action policy

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Global allow_destructive_actions defaults to true.
• Per-plugin allow_destructive_actions overrides the global policy for
• false: OpenClaw returns a deterministic decline.
• true: OpenClaw auto-accepts only safe schemas it can map to an approval
• "auto": OpenClaw exposes destructive plugin actions to Codex, then
• "ask": OpenClaw uses the same Codex write/destructive gating as
• Missing plugin identity, ambiguous ownership, a missing or mismatched

트러블슈팅

plugin/list result reports the exact configured ID as installed and enabled, then confirm app/list reports every owned app accessible for the same Codex account. OpenClaw can enable an accessible app for the thread even when the account inventory currently reports that app disabled. If you changed that state after the gateway cached app inventory, wait for the one-hour cache refresh or restart the gateway, then use /new or /reset. OpenClaw does not repair or authenticate workspace plugins. If the explicit workspace list request is rejected, each enabled workspace entry reports marketplace_missing; unrelated curated entries still proceed from the default list response.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Code	Meaning	Fix
auth_required	Migration installed the plugin, but one of its apps still needs authentication. The entry is written disabled until you reauthorize.	Reauthorize the app in Codex, then enable the plugin in OpenClaw.
app_inaccessible, app_disabled, app_missing	With --verify-plugin-apps, the source Codex app inventory did not show all owned apps as present, enabled, and accessible.	Reauthorize or enable the app in Codex, then rerun migration with --verify-plugin-apps.
app_inventory_unavailable	Strict source app verification was requested but the source Codex app inventory refresh failed.	Fix source Codex app-server access, or retry without --verify-plugin-apps to accept the faster account-gated plan.
codex_subscription_required	The source Codex app-server account was not a ChatGPT subscription account.	Log in to the Codex app with subscription auth, then rerun migration.
codex_account_unavailable	The source Codex app-server account could not be read.	Fix source Codex app-server auth, or rerun with --verify-plugin-apps to let source app inventory decide eligibility.
marketplace_missing, plugin_missing	Marketplace or exact plugin unavailable; the explicit workspace catalog request may have been rejected; workspace apps fail closed.	Verify the compatible app-server contract and exact ID described below.
plugin_detail_unavailable	OpenClaw could not read plugin ownership details.	Inspect the target app-server's plugin/list and plugin/read responses.
plugin_disabled	Codex reports the plugin installed but disabled.	Curated activation may repair it; enable a workspace plugin in Codex before retrying.
plugin_activation_failed	Plugin activation did not complete.	Use the attached diagnostic to distinguish marketplace, auth, refresh, or workspace-readiness failures.
app_inventory_missing, app_inventory_stale	App readiness came from an empty or stale cache.	OpenClaw schedules an async refresh automatically; plugin apps stay excluded until ownership and readiness are known.
app_ownership_ambiguous	App inventory only matched by display name.	The app stays hidden from the Codex thread until a later refresh proves ownership.

관련 문서

주요 항목:

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

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/codex-native-plugins
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw migrate codex --dry-run

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

openclaw migrate apply codex --yes

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

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            plugins: {
              "example-plugin": {
                enabled: true,
                marketplaceName: "workspace-directory",
                pluginName: "example-plugin@workspace-directory",
              },
            },
          },
        },
      },
    },
  },
}

/codex plugins
/codex plugins list
/codex plugins disable google-calendar
/codex plugins enable google-calendar

관련 링크

• 공식 원문: plugins/codex-native-plugins
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.