mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-12 21:53:00 -06:00
feat(codex): support workspace-directory plugins (#104188)
* feat(codex): support workspace directory plugins * fix(codex): contain workspace catalog failures * chore(config): refresh documentation baseline
This commit is contained in:
Kevin Lin
@@ -1,9 +1,10 @@
|
||||
---
|
||||
summary: "Configure migrated native Codex plugins for Codex-mode OpenClaw agents"
|
||||
summary: "Configure native Codex plugins for Codex-mode OpenClaw agents"
|
||||
title: "Native Codex plugins"
|
||||
read_when:
|
||||
- You want Codex-mode OpenClaw agents to use native Codex plugins
|
||||
- You are migrating source-installed openai-curated Codex plugins
|
||||
- You are configuring an existing workspace-directory Codex plugin
|
||||
- You are troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics
|
||||
---
|
||||
|
||||
@@ -23,8 +24,12 @@ working.
|
||||
- `plugins.entries.codex.config.codexPlugins.enabled` is `true`.
|
||||
- The target Codex app-server can see the expected marketplace, plugin, and
|
||||
app inventory.
|
||||
- V1 supports only `openai-curated` plugins that migration observed as
|
||||
- Migration supports only `openai-curated` plugins that it observed as
|
||||
source-installed in the source Codex home.
|
||||
- Manually configured `workspace-directory` plugins require a Codex app-server
|
||||
whose `plugin/list` accepts `marketplaceKinds` and whose pathless workspace
|
||||
summaries include `remotePluginId`. The plugin must already be installed and
|
||||
enabled, and its owned apps must be accessible in `app/list`.
|
||||
|
||||
`codexPlugins` has no effect on OpenClaw-provider runs, ACP conversation
|
||||
bindings, or other harnesses, because those paths never create Codex
|
||||
@@ -86,6 +91,44 @@ config looks like this:
|
||||
}
|
||||
```
|
||||
|
||||
Migration remains limited to `openai-curated`. To use an existing
|
||||
`workspace-directory` plugin, add it manually with the exact
|
||||
marketplace-qualified `summary.id` returned by `plugin/list`. For example, if
|
||||
Codex returns `example-plugin@workspace-directory`, configure that complete
|
||||
value instead of its display name:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
codex: {
|
||||
enabled: true,
|
||||
config: {
|
||||
codexPlugins: {
|
||||
enabled: true,
|
||||
plugins: {
|
||||
"example-plugin": {
|
||||
enabled: true,
|
||||
marketplaceName: "workspace-directory",
|
||||
pluginName: "example-plugin@workspace-directory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw does not call `plugin/install` or start authentication for a
|
||||
`workspace-directory` plugin. Install, enable, and authenticate it in Codex
|
||||
before adding or enabling the OpenClaw policy. OpenClaw keeps apps hidden when
|
||||
the response omits the exact marketplace, plugin ID, detail ID, or app-readiness
|
||||
evidence. If Codex rejects the explicit workspace `plugin/list` request,
|
||||
OpenClaw reports `marketplace_missing` for each enabled workspace plugin and
|
||||
keeps any independently discovered curated plugins available.
|
||||
|
||||
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
|
||||
@@ -112,20 +155,23 @@ from `plugins.entries.codex.config.codexPlugins.plugins`.
|
||||
gateway client with the `operator.admin` scope can run them.
|
||||
|
||||
Enabling a configured plugin also turns on the global `codexPlugins.enabled`
|
||||
switch. If the plugin was written disabled because migration returned
|
||||
switch. If a curated plugin was written disabled because migration returned
|
||||
`auth_required`, reauthorize the app in Codex before enabling it in OpenClaw.
|
||||
For a `workspace-directory` entry, enabling it here changes only OpenClaw
|
||||
policy; the plugin and app must already be active in Codex.
|
||||
|
||||
## How native plugin setup works
|
||||
|
||||
The integration tracks three states:
|
||||
|
||||
| State | Meaning |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Installed | Codex has the local plugin bundle in the target app-server runtime. |
|
||||
| Enabled | OpenClaw config allows the plugin for Codex harness turns. |
|
||||
| Accessible | Codex app-server confirms the plugin's app entries are available for the active account and map to the migrated plugin identity. |
|
||||
| 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. |
|
||||
|
||||
Migration is the durable install/eligibility step:
|
||||
For `openai-curated` plugins, migration is the durable install/eligibility
|
||||
step:
|
||||
|
||||
- During planning, OpenClaw reads source Codex `plugin/read` details and
|
||||
checks that the source Codex app-server account is a ChatGPT subscription
|
||||
@@ -141,10 +187,18 @@ Migration is the durable install/eligibility step:
|
||||
failures then fall through to the source app-inventory gate instead of
|
||||
skipping outright.
|
||||
|
||||
Runtime app inventory is the target-session accessibility check that runs
|
||||
after migration. Codex harness session setup computes a restrictive thread
|
||||
app config from the enabled and accessible plugin apps; it is not
|
||||
recomputed on every turn, so `/codex plugins enable`/`disable` only affect
|
||||
For `workspace-directory` plugins, setup happens outside OpenClaw. OpenClaw
|
||||
queries that marketplace only when at least one enabled workspace entry is
|
||||
configured, resolves each plugin by exact `summary.id`, and reuses the existing
|
||||
`plugin/read` ownership and `app/list` readiness checks. An uninstalled,
|
||||
disabled, inaccessible, or unauthenticated plugin exposes no apps; OpenClaw
|
||||
does not attempt installation or authentication.
|
||||
|
||||
Runtime app inventory is the target-session accessibility check for both
|
||||
migrated curated plugins and manually configured workspace plugins. Codex
|
||||
harness session setup computes a restrictive thread app config from the enabled
|
||||
and accessible plugin apps; it is not recomputed on every turn, so
|
||||
`/codex plugins enable`/`disable` only affect
|
||||
new Codex conversations. Use `/new` or `/reset` to pick up the change in the
|
||||
current conversation.
|
||||
|
||||
@@ -152,6 +206,14 @@ current conversation.
|
||||
|
||||
- Only `openai-curated` plugins already installed in the source Codex
|
||||
app-server inventory are migration-eligible.
|
||||
- Runtime also supports explicit `workspace-directory` entries on app-server
|
||||
builds whose `plugin/list` implements `marketplaceKinds` and returns
|
||||
`remotePluginId` for pathless workspace summaries. These entries must use
|
||||
their exact marketplace-qualified `summary.id` and must already be installed,
|
||||
enabled, and app-accessible. A rejected workspace list request produces the
|
||||
existing per-plugin `marketplace_missing` diagnostic; missing marketplace,
|
||||
plugin, detail, or app evidence exposes no workspace app. Curated inventory
|
||||
from the default list request remains usable.
|
||||
- App-backed source plugins must pass the migration-time subscription gate.
|
||||
`--verify-plugin-apps` adds the source app-inventory gate. Subscription-gated
|
||||
accounts, and in verification mode inaccessible/disabled/missing source
|
||||
@@ -163,9 +225,10 @@ current conversation.
|
||||
- `codexPlugins.enabled` is the only global enablement switch; there is no
|
||||
`plugins["*"]` wildcard or 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, not
|
||||
activated automatically.
|
||||
- Non-curated marketplaces, cached plugin bundles, hooks, and Codex config
|
||||
files are preserved in the migration report for manual review, not activated
|
||||
automatically. Runtime accepts manually configured `workspace-directory`
|
||||
entries; other marketplaces remain unsupported.
|
||||
|
||||
## App inventory and ownership
|
||||
|
||||
@@ -179,11 +242,12 @@ 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 `app/list` traversal for that planning run.
|
||||
- Target runtime setup uses the target agent's Codex app-server identity
|
||||
when building the thread app config. Plugin activation invalidates that
|
||||
- Target runtime setup uses the target agent's Codex app-server identity when
|
||||
building the thread app config. Curated plugin activation invalidates that
|
||||
target cache key, then force-refreshes it after `plugin/install`.
|
||||
`workspace-directory` setup never runs this activation path.
|
||||
|
||||
A plugin app is exposed only when OpenClaw can map it back to the migrated
|
||||
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.
|
||||
@@ -226,7 +290,7 @@ 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 migrated plugins or
|
||||
`_default` is disabled, and only apps owned by enabled configured plugins or
|
||||
accessible account apps admitted by `allow_all_plugins` are enabled.
|
||||
|
||||
`destructive_enabled` on each app comes from the effective global or
|
||||
@@ -244,7 +308,7 @@ controlled by each app's `destructive_enabled` policy.
|
||||
|
||||
## Destructive action policy
|
||||
|
||||
Destructive plugin elicitations are allowed by default for migrated Codex
|
||||
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`.
|
||||
@@ -276,10 +340,31 @@ plugins, while unsafe schemas and ambiguous ownership fail closed:
|
||||
| `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` | 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. |
|
||||
| `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. |
|
||||
|
||||
**Workspace plugin is installed but not visible:** confirm the workspace
|
||||
`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.
|
||||
|
||||
For `plugin_detail_unavailable`, a pathless workspace summary must include
|
||||
`remotePluginId`; OpenClaw keeps owned apps hidden when that selector or the
|
||||
subsequent `plugin/read` result is unavailable. For
|
||||
`plugin_activation_failed`, curated plugins may report a marketplace, auth, or
|
||||
post-install refresh failure. A workspace plugin reports this code when it is
|
||||
not already active; install, enable, and authenticate it outside OpenClaw.
|
||||
|
||||
**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
|
||||
|
||||
Reference in New Issue
Block a user