mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-12 15:16:07 +00:00
docs: rewrite published docs grounded in current source (#100142)
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
This commit is contained in:
Peter Steinberger
committed by
GitHub
GitHub
parent
e069cb26f7
commit
f7d7148cf0
@@ -9,31 +9,31 @@ read_when:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
OpenClaw does not translate Codex plugins into synthetic `codex_plugin_*`
|
||||
OpenClaw dynamic tools. Plugin calls stay in the native Codex transcript, and
|
||||
Codex app-server owns the app-backed MCP execution.
|
||||
|
||||
Use this page after the base [Codex harness](/plugins/codex-harness) is working.
|
||||
Use this page after the base [Codex harness](/plugins/codex-harness) is
|
||||
working.
|
||||
|
||||
## Requirements
|
||||
|
||||
- The selected OpenClaw agent runtime must be the native Codex harness.
|
||||
- `plugins.entries.codex.enabled` must be true.
|
||||
- `plugins.entries.codex.config.codexPlugins.enabled` must be true.
|
||||
- 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
|
||||
app inventory.
|
||||
- V1 supports only `openai-curated` plugins that migration observed as
|
||||
source-installed in the source Codex home.
|
||||
- The target Codex app-server must be able to see the expected marketplace,
|
||||
plugin, and app inventory.
|
||||
|
||||
`codexPlugins` has no effect on OpenClaw runs, normal OpenAI provider runs, ACP
|
||||
conversation bindings, or other harnesses because those paths do not create
|
||||
Codex app-server threads with native `apps` config.
|
||||
`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 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).
|
||||
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](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
|
||||
for the OpenAI account and admin model.
|
||||
|
||||
## Quickstart
|
||||
|
||||
@@ -43,8 +43,9 @@ Preview migration from the source Codex home:
|
||||
openclaw migrate codex --dry-run
|
||||
```
|
||||
|
||||
Use strict source app verification when you want migration to check source app
|
||||
accessibility before planning native plugin activation:
|
||||
Add `--verify-plugin-apps` to make migration call source `app/list` and
|
||||
require every owned app to be present, enabled, and accessible before
|
||||
planning native activation:
|
||||
|
||||
```bash
|
||||
openclaw migrate codex --dry-run --verify-plugin-apps
|
||||
@@ -56,8 +57,8 @@ 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 typical migrated
|
||||
Migration writes explicit `codexPlugins` entries for eligible plugins and
|
||||
calls Codex app-server `plugin/install` for selected plugins. A migrated
|
||||
config looks like this:
|
||||
|
||||
```json5
|
||||
@@ -85,14 +86,15 @@ config looks like this:
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Manage plugins from chat
|
||||
|
||||
Use `/codex plugins` when you want to inspect or change configured native Codex
|
||||
plugins from the same chat where you operate the Codex harness:
|
||||
`/codex plugins` inspects or changes configured native Codex plugins from the
|
||||
same chat where you operate the Codex harness:
|
||||
|
||||
```text
|
||||
/codex plugins
|
||||
@@ -101,188 +103,156 @@ plugins from the same chat where you operate the Codex harness:
|
||||
/codex plugins enable google-calendar
|
||||
```
|
||||
|
||||
`/codex plugins` is an alias for `/codex plugins list`. The list output shows
|
||||
the configured plugin keys, on/off state, Codex plugin name, and marketplace
|
||||
`/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`.
|
||||
|
||||
`enable` and `disable` write only to OpenClaw config at
|
||||
`~/.openclaw/openclaw.json`; they do not edit `~/.codex/config.toml` or install
|
||||
new Codex plugins. Only the owner or a gateway client with the
|
||||
`operator.admin` scope can change plugin state.
|
||||
`enable`/`disable` write only to `~/.openclaw/openclaw.json`; they never edit
|
||||
`~/.codex/config.toml` or install new Codex plugins. Only the owner or a
|
||||
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 `auth_required`, reauthorize the app in Codex before enabling
|
||||
it in OpenClaw.
|
||||
Enabling a configured plugin also turns on the global `codexPlugins.enabled`
|
||||
switch. If the plugin was written disabled because migration returned
|
||||
`auth_required`, reauthorize the app in Codex before enabling it in OpenClaw.
|
||||
|
||||
## How native plugin setup works
|
||||
|
||||
The integration has three separate states:
|
||||
The integration tracks three states:
|
||||
|
||||
- Installed: Codex has the local plugin bundle in the target app-server runtime.
|
||||
- Enabled: OpenClaw config is willing to make the plugin available to Codex
|
||||
harness turns.
|
||||
- Accessible: Codex app-server confirms the plugin's app entries are available
|
||||
for the active account and can be mapped to the migrated plugin identity.
|
||||
| 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. |
|
||||
|
||||
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 response is a ChatGPT subscription account. Non-ChatGPT or
|
||||
missing account responses skip app-backed plugins with
|
||||
`codex_subscription_required`. By default, migration does not call source
|
||||
`app/list`; app-backed source plugins that pass the account gate are planned
|
||||
without source app accessibility verification, and account lookup transport
|
||||
failures skip with `codex_account_unavailable`. With `--verify-plugin-apps`,
|
||||
migration takes a fresh source `app/list` snapshot and requires every owned app
|
||||
to be present, enabled, and accessible before planning native activation. In
|
||||
that mode, account lookup transport failures fall through to the source
|
||||
app-inventory gate. Runtime app inventory is the target-session accessibility
|
||||
check after migration. Codex harness session setup then computes a restrictive
|
||||
thread app config for the enabled and accessible plugin apps.
|
||||
Migration is the durable install/eligibility step:
|
||||
|
||||
Thread app config is computed when OpenClaw establishes a Codex harness session
|
||||
or replaces a stale Codex thread binding. It is not recomputed on every turn, so
|
||||
`/codex plugins enable` and `/codex plugins disable` affect new Codex
|
||||
conversations. Use `/new` or `/reset` when the current conversation should pick
|
||||
up the updated app set.
|
||||
- During planning, OpenClaw reads source Codex `plugin/read` details and
|
||||
checks that the source Codex app-server account is a ChatGPT subscription
|
||||
account. A non-ChatGPT or missing account response skips app-backed
|
||||
plugins with `codex_subscription_required`.
|
||||
- By default, migration skips the source `app/list` call: app-backed source
|
||||
plugins that pass the account gate are planned without source app
|
||||
accessibility verification, and account-lookup transport failures skip
|
||||
with `codex_account_unavailable`.
|
||||
- With `--verify-plugin-apps`, migration takes a fresh source `app/list`
|
||||
snapshot and requires every owned app to be present, enabled, and
|
||||
accessible before planning native activation. Account-lookup transport
|
||||
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
|
||||
new Codex conversations. Use `/new` or `/reset` to pick up the change in the
|
||||
current conversation.
|
||||
|
||||
## V1 support boundary
|
||||
|
||||
V1 is intentionally narrow:
|
||||
|
||||
- Only `openai-curated` plugins that were already installed in the source Codex
|
||||
- Only `openai-curated` plugins already installed in the source Codex
|
||||
app-server inventory are migration-eligible.
|
||||
- App-backed source plugins must pass the migration-time subscription gate.
|
||||
`--verify-plugin-apps` adds the source app-inventory gate. Subscription-gated
|
||||
accounts plus, in verification mode, inaccessible, disabled, missing source
|
||||
apps or source app-inventory refresh failures are reported as skipped manual
|
||||
items instead of enabled config entries. Unreadable plugin details are skipped
|
||||
before the source app-inventory gate.
|
||||
- Migration writes explicit plugin identities with `marketplaceName` and
|
||||
`pluginName`; it does not write local `marketplacePath` cache paths.
|
||||
- `codexPlugins.enabled` is the global enablement switch.
|
||||
- There is no `plugins["*"]` wildcard and no 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.
|
||||
accounts, and in verification mode inaccessible/disabled/missing source
|
||||
apps or app-inventory refresh failures, are reported as skipped manual
|
||||
items instead of enabled config entries. 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.
|
||||
- Unsupported marketplaces, cached plugin bundles, hooks, and Codex config
|
||||
files are preserved in the migration report for manual review, not
|
||||
activated automatically.
|
||||
|
||||
## App inventory and ownership
|
||||
|
||||
OpenClaw reads Codex app inventory through app-server `app/list`, caches it for
|
||||
one hour, and refreshes stale or missing entries asynchronously. The cache is
|
||||
in memory only; restarting the CLI or gateway drops it, and OpenClaw rebuilds it
|
||||
from the next `app/list` read.
|
||||
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.
|
||||
|
||||
Migration and runtime use separate cache keys:
|
||||
|
||||
- Source migration verification uses the source Codex home and source app-server
|
||||
start options. This runs only when `--verify-plugin-apps` is set, and it
|
||||
forces a fresh source `app/list` traversal for that planning run.
|
||||
- Target runtime setup uses the target agent's Codex app-server identity when it
|
||||
builds the Codex thread app config. Plugin activation invalidates that target
|
||||
cache key and then force-refreshes it after `plugin/install`.
|
||||
- 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 cache key, then force-refreshes it after `plugin/install`.
|
||||
|
||||
A plugin app is exposed only when OpenClaw can map it back to the migrated
|
||||
plugin through stable ownership:
|
||||
|
||||
- exact app id from plugin detail
|
||||
- known MCP server name
|
||||
- unique stable metadata
|
||||
|
||||
Display-name-only or ambiguous ownership is excluded until the next inventory
|
||||
refresh proves ownership.
|
||||
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.
|
||||
|
||||
## 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 are
|
||||
`_default` is disabled, and only apps owned by enabled migrated plugins are
|
||||
enabled.
|
||||
|
||||
OpenClaw sets app-level `destructive_enabled` from the effective global or
|
||||
per-plugin `allow_destructive_actions` policy and lets Codex enforce
|
||||
destructive tool metadata from its native app tool annotations. `true`,
|
||||
`"auto"`, and `"ask"` set `destructive_enabled: true`; `false` sets it
|
||||
false. The `_default` app config is disabled with `open_world_enabled: false`.
|
||||
Enabled plugin apps are emitted with `open_world_enabled: true`; OpenClaw does
|
||||
not expose a separate plugin open-world policy knob and does not maintain
|
||||
per-plugin destructive tool-name deny lists.
|
||||
`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 is automatic by default for plugin apps so non-destructive
|
||||
read tools can run without a same-thread approval UI. Destructive tools remain
|
||||
Tool approval mode defaults to automatic for plugin 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 migrated Codex
|
||||
plugins, while unsafe schemas and ambiguous ownership still fail closed:
|
||||
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.
|
||||
- When policy is `false`, OpenClaw returns a deterministic decline.
|
||||
- When policy is `true`, OpenClaw auto-accepts only safe schemas it can map to
|
||||
an approval response, such as a boolean approve field.
|
||||
- When policy is `"auto"`, OpenClaw exposes destructive plugin actions to
|
||||
Codex but turns ownership-proven MCP approval elicitations into OpenClaw
|
||||
plugin approvals before returning the Codex approval response.
|
||||
- When policy is `"ask"`, OpenClaw uses the same Codex write/destructive
|
||||
gating as `"auto"`, clears durable Codex per-tool approval overrides for the
|
||||
app before the thread starts, and only offers one-shot approval or denial so
|
||||
durable approvals cannot suppress later write-action prompts.
|
||||
- For each admitted app that uses `"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
|
||||
- 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"`, clears durable Codex per-tool approval overrides for the app
|
||||
before the thread starts, and offers only one-shot approval or denial so
|
||||
durable approvals cannot suppress later write-action prompts. 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 turn id, a wrong turn
|
||||
id, or an unsafe elicitation schema declines instead of prompting.
|
||||
- Missing plugin identity, ambiguous ownership, a missing or mismatched
|
||||
turn id, or an unsafe elicitation schema declines instead of prompting.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`auth_required`:** migration installed the plugin, but one of its apps still
|
||||
needs authentication. The explicit plugin entry is written disabled until you
|
||||
reauthorize and enable it.
|
||||
| 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` | 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. |
|
||||
| `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. |
|
||||
|
||||
**`app_inaccessible`, `app_disabled`, or `app_missing`:**
|
||||
migration did not install the plugin because the source Codex app inventory did
|
||||
not show all owned apps as present, enabled, and accessible while
|
||||
`--verify-plugin-apps` was set. Reauthorize or enable the app in Codex, then
|
||||
rerun migration with `--verify-plugin-apps`.
|
||||
|
||||
**`app_inventory_unavailable`:** migration did not install the plugin because
|
||||
strict source app verification was requested and source Codex app inventory
|
||||
refresh failed. Fix source Codex app-server access or retry without
|
||||
`--verify-plugin-apps` if you accept the faster account-gated plan.
|
||||
|
||||
**`codex_subscription_required`:** migration did not install the app-backed
|
||||
plugin because the source Codex app-server account was not logged in with a
|
||||
ChatGPT subscription account. Log in to the Codex app with subscription auth,
|
||||
then rerun migration.
|
||||
|
||||
**`codex_account_unavailable`:** migration did not install the app-backed plugin
|
||||
because the source Codex app-server account could not be read. Fix source Codex
|
||||
app-server auth or rerun with `--verify-plugin-apps` if you want source app
|
||||
inventory to decide eligibility when account lookup fails.
|
||||
|
||||
**`marketplace_missing` or `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.
|
||||
|
||||
**`app_inventory_missing` or `app_inventory_stale`:** app readiness came from an
|
||||
empty or stale cache. OpenClaw schedules an async refresh and excludes plugin
|
||||
apps until ownership and readiness are known.
|
||||
|
||||
**`app_ownership_ambiguous`:** app inventory only matched by display name, so
|
||||
the app is not exposed to the Codex thread.
|
||||
|
||||
**Config changed but the agent cannot see the plugin:** use `/codex plugins
|
||||
list` to confirm the configured state, then use `/new` or `/reset`. Existing
|
||||
**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 when policy is true, `"auto"`, or
|
||||
`"ask"`, unsafe elicitation schemas and ambiguous plugin identity still fail
|
||||
closed.
|
||||
`allow_destructive_actions` values. Even with `true`, `"auto"`, or `"ask"`,
|
||||
unsafe elicitation schemas and ambiguous plugin identity still fail closed.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
Reference in New Issue
Block a user