docs(codex): clarify first-party plugin marketplaces

steipete · steipete · commit 729712d19467 · 2026-05-31T13:22:00.000+01:00
diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md
@@ -222,6 +222,13 @@ The native Codex plugin config also accepts first-party `openai-bundled` and
 `openai-primary-runtime` marketplace identities, but migration does not
 auto-discover or install them from source state.
 
+OpenAI-side app/plugin availability still comes from the signed-in Codex
+account and workspace app controls. See
+[Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
+for OpenAI's account and workspace-control overview, then use
+[Native Codex plugins](/plugins/codex-native-plugins#manual-first-party-marketplace-entries)
+for manual first-party marketplace entries.
+
 If Codex app-server plugin inventory is unavailable during planning, migration
 falls back to cached bundle advisory items instead of failing the whole
 migration.
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
@@ -317,7 +317,9 @@ conversation bindings, or any non-Codex harness.
   Default: `true` for explicit entries.
 - `plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName`:
   stable marketplace identity. V1 supports `"openai-curated"`,
-  `"openai-bundled"`, and `"openai-primary-runtime"`.
+  `"openai-bundled"`, and `"openai-primary-runtime"`. See
+  [Native Codex plugins](/plugins/codex-native-plugins#manual-first-party-marketplace-entries)
+  for manual bundled and primary-runtime examples.
 - `plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName`: stable
   Codex plugin identity from migration, for example `"google-calendar"`.
 - `plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions`:
diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md
@@ -658,6 +658,11 @@ For migration eligibility, app inventory, destructive action policy,
 elicitations, and native plugin diagnostics, see
 [Native Codex plugins](/plugins/codex-native-plugins).
 
+OpenAI-side app and plugin access is controlled by the signed-in Codex account
+and, for Business and Enterprise/Edu workspaces, workspace app controls. See
+[Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
+for OpenAI's account and workspace-control overview.
+
 ## Computer Use
 
 Computer Use is covered in its own setup guide:
@@ -782,6 +787,7 @@ provider refs stay on their normal provider path in `auto` mode.
 - [Agent runtimes](/concepts/agent-runtimes)
 - [Model providers](/concepts/model-providers)
 - [OpenAI provider](/providers/openai)
+- [OpenAI Codex help](https://help.openai.com/en/collections/14937394-codex)
 - [Agent harness plugins](/plugins/sdk-agent-harness)
 - [Plugin hooks](/plugins/hooks)
 - [Diagnostics export](/gateway/diagnostics)
diff --git a/docs/plugins/codex-native-plugins.md b/docs/plugins/codex-native-plugins.md
@@ -33,6 +33,10 @@ Use this page after the base [Codex harness](/plugins/codex-harness) is working.
 conversation bindings, or other harnesses because those paths do not create
 Codex app-server threads with native `apps` config.
 
+OpenAI-side Codex access, app availability, and workspace app/plugin controls
+come from the signed-in Codex account. For the OpenAI account and admin model,
+see [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan).
+
 ## Quickstart
 
 Preview migration from the source Codex home:
@@ -89,6 +93,49 @@ After changing `codexPlugins`, new Codex conversations pick up the updated app
 set automatically. Use `/new` or `/reset` to refresh the current conversation.
 A gateway restart is not required for plugin enable or disable changes.
 
+## Manual first-party marketplace entries
+
+Migration writes `openai-curated` entries for eligible source-installed plugins.
+For first-party plugins that live in Codex's bundled or primary-runtime
+marketplaces, add explicit entries after confirming the target Codex app-server
+inventory exposes that marketplace and plugin.
+
+Use the same config shape for every first-party marketplace:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          codexPlugins: {
+            enabled: true,
+            plugins: {
+              chrome: {
+                enabled: true,
+                marketplaceName: "openai-bundled",
+                pluginName: "chrome",
+              },
+              documents: {
+                enabled: true,
+                marketplaceName: "openai-primary-runtime",
+                pluginName: "documents",
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+The key under `plugins` is OpenClaw's local config key. `pluginName` and
+`marketplaceName` must match the Codex app-server inventory exactly. If the
+plugin is not listed in `/codex plugins list` or Codex app diagnostics, OpenClaw
+keeps the entry configured but cannot expose its apps to Codex turns.
+
 ## Manage plugins from chat
 
 Use `/codex plugins` when you want to inspect or change configured native Codex
