vilvona 1.0.0

package/docs/plugins/codex-native-plugins.md

@@ -0,0 +1,280 @@
+---
+summary: "Configure migrated 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 troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics
+---
+
+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.
+
+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.
+
+## 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.
+- 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.
+
+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:
+
+```bash
+openclaw migrate codex --dry-run
+```
+
+Use strict source app verification when you want migration to check source app
+accessibility before planning native plugin activation:
+
+```bash
+openclaw migrate codex --dry-run --verify-plugin-apps
+```
+
+Apply the migration when the plan looks right:
+
+```bash
+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
+config looks like this:
+
+```json5
+{
+  plugins: {
+    entries: {
+      codex: {
+        enabled: true,
+        config: {
+          codexPlugins: {
+            enabled: true,
+            allow_destructive_actions: true,
+            plugins: {
+              "google-calendar": {
+                enabled: true,
+                marketplaceName: "openai-curated",
+                pluginName: "google-calendar",
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+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.
+
+## 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:
+
+```text
+/codex plugins
+/codex plugins list
+/codex plugins disable google-calendar
+/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
+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.
+
+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:
+
+- 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.
+
+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.
+
+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.
+
+## V1 support boundary
+
+V1 is intentionally narrow:
+
+- Only `openai-curated` plugins that were 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.
+
+## 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.
+
+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`.
+
+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.
+
+## 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
+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. 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.
+
+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
+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:
+
+- 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.
+- Missing plugin identity, ambiguous ownership, a missing turn id, a wrong 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.
+
+**`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
+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, unsafe elicitation
+schemas and ambiguous plugin identity still fail closed.
+
+## Related
+
+- [Codex harness](/plugins/codex-harness)
+- [Codex harness reference](/plugins/codex-harness-reference)
+- [Codex harness runtime](/plugins/codex-harness-runtime)
+- [Configuration reference](/gateway/configuration-reference#codex-harness-plugin-config)
+- [Migrate CLI](/cli/migrate)

package/docs/plugins/community.md

@@ -0,0 +1,77 @@
+---
+summary: "Find and publish community-maintained OpenClaw plugins"
+read_when:
+  - You want to find third-party OpenClaw plugins
+  - You want to publish or list your own plugin on ClawHub
+title: "Community plugins"
+doc-schema-version: 1
+---
+
+Community plugins are third-party packages that extend OpenClaw with channels,
+tools, providers, hooks, or other capabilities. Use [ClawHub](/clawhub) as the
+primary discovery surface for public community plugins.
+
+## Find plugins
+
+Search ClawHub from the CLI:
+
+```bash
+openclaw plugins search "calendar"
+```
+
+Install a ClawHub plugin with an explicit source prefix:
+
+```bash
+openclaw plugins install clawhub:<package-name>
+```
+
+npm remains a supported direct-install path during the launch cutover:
+
+```bash
+openclaw plugins install npm:<package-name>
+```
+
+Use [Manage plugins](/plugins/manage-plugins) for common install, update,
+inspect, and uninstall examples. Use [`openclaw plugins`](/cli/plugins) for the
+full command reference and source-selection rules.
+
+## Publish plugins
+
+Publish public community plugins on ClawHub when you want OpenClaw users to
+discover and install them. ClawHub owns the live package listing, release
+history, scan status, and install hints; the docs do not maintain a static
+third-party plugin catalog.
+
+```bash
+clawhub package publish your-org/your-plugin --dry-run
+clawhub package publish your-org/your-plugin
+```
+
+Before publishing, make sure the plugin has package metadata, a plugin manifest,
+setup docs, and a clear maintenance owner. ClawHub validates owner scope,
+package name, version, file limits, and source metadata before it creates a
+release, then keeps new releases hidden from normal install and download
+surfaces until review and verification finish.
+
+Use this checklist before you publish:
+
+| Requirement          | Why                                                 |
+| -------------------- | --------------------------------------------------- |
+| Published on ClawHub | Users need `openclaw plugins install` hints to work |
+| Public GitHub repo   | Source review, issue tracking, transparency         |
+| Setup and usage docs | Users need to know how to configure it              |
+| Active maintenance   | Recent updates or responsive issue handling         |
+
+Use these pages for the full publishing contract:
+
+- [ClawHub publishing](/clawhub/publishing) explains owners, scopes, releases,
+  review, package validation, and package transfer.
+- [Building plugins](/plugins/building-plugins) shows the plugin package shape
+  and first publish workflow.
+- [Plugin manifest](/plugins/manifest) defines native plugin manifest fields.
+
+## Related
+
+- [Plugins](/tools/plugin) - install, configure, restart, and troubleshoot
+- [Manage plugins](/plugins/manage-plugins) - command examples
+- [ClawHub publishing](/clawhub/publishing) - publish and release rules

package/docs/plugins/compatibility.md

@@ -0,0 +1,198 @@
+---
+summary: "Plugin compatibility contracts, deprecation metadata, and migration expectations"
+title: "Plugin compatibility"
+read_when:
+  - You maintain an OpenClaw plugin
+  - You see a plugin compatibility warning
+  - You are planning a plugin SDK or manifest migration
+---
+
+OpenClaw keeps older plugin contracts wired through named compatibility
+adapters before removing them. This protects existing bundled and external
+plugins while the SDK, manifest, setup, config, and agent runtime contracts
+evolve.
+
+## Compatibility registry
+
+Plugin compatibility contracts are tracked in the core registry at
+`src/plugins/compat/registry.ts`.
+
+Each record has:
+
+- a stable compatibility code
+- status: `active`, `deprecated`, `removal-pending`, or `removed`
+- owner: SDK, config, setup, channel, provider, plugin execution, agent runtime,
+  or core
+- introduction and deprecation dates when applicable
+- replacement guidance
+- docs, diagnostics, and tests that cover the old and new behavior
+
+The registry is the source for maintainer planning and future plugin inspector
+checks. If a plugin-facing behavior changes, add or update the compatibility
+record in the same change that adds the adapter.
+
+Doctor repair and migration compatibility is tracked separately at
+`src/commands/doctor/shared/deprecation-compat.ts`. Those records cover old
+config shapes, install-ledger layouts, and repair shims that may need to stay
+available after the runtime compatibility path is removed.
+
+Release sweeps should check both registries. Do not delete a doctor migration
+just because the matching runtime or config compatibility record expired; first
+verify there is no supported upgrade path that still needs the repair. Also
+revalidate each replacement annotation during release planning because plugin
+ownership and config footprint can change as providers and channels move out of
+core.
+
+## Plugin inspector package
+
+The plugin inspector should live outside the core OpenClaw repo as a separate
+package/repository backed by the versioned compatibility and manifest
+contracts.
+
+The day-one CLI should be:
+
+```sh
+openclaw-plugin-inspector ./my-plugin
+```
+
+It should emit:
+
+- manifest/schema validation
+- the contract compatibility version being checked
+- install/source metadata checks
+- cold-path import checks
+- deprecation and compatibility warnings
+
+Use `--json` for stable machine-readable output in CI annotations. OpenClaw
+core should expose contracts and fixtures the inspector can consume, but should
+not publish the inspector binary from the main `openclaw` package.
+
+### Maintainer acceptance lane
+
+Use Crabbox-backed Blacksmith Testbox for the installable-package acceptance
+lane when validating the external inspector against OpenClaw plugin packages.
+Run it from a clean OpenClaw checkout after the package is built:
+
+```sh
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
+```
+
+Keep this lane opt-in for maintainers because it installs an external npm
+package and may inspect plugin packages cloned outside the repo. The local repo
+guards cover the SDK export map, compatibility registry metadata, deprecated
+SDK-import burn-down, and bundled extension import boundaries; Testbox inspector
+proof covers the package as external plugin authors consume it.
+
+## Deprecation policy
+
+OpenClaw should not remove a documented plugin contract in the same release
+that introduces its replacement.
+
+The migration sequence is:
+
+1. Add the new contract.
+2. Keep the old behavior wired through a named compatibility adapter.
+3. Emit diagnostics or warnings when plugin authors can act.
+4. Document the replacement and timeline.
+5. Test both old and new paths.
+6. Wait through the announced migration window.
+7. Remove only with explicit breaking-release approval.
+
+Deprecated records must include a warning start date, replacement, docs link,
+and final removal date no more than three months after the warning starts. Do
+not add a deprecated compatibility path with an open-ended removal window unless
+maintainers explicitly decide it is permanent compatibility and mark it `active`
+instead.
+
+## Current compatibility areas
+
+Current compatibility records include:
+
+- legacy broad SDK imports such as `openclaw/plugin-sdk/compat`
+- legacy hook-only plugin shapes and `before_agent_start`
+- legacy `api.on("deactivate", ...)` cleanup hook names while plugins migrate to
+  `gateway_stop`
+- legacy `activate(api)` plugin entrypoints while plugins migrate to
+  `register(api)`
+- legacy SDK aliases such as `openclaw/extension-api`,
+  `openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/command-auth`
+  status builders, `openclaw/plugin-sdk/test-utils` (replaced by focused
+  `openclaw/plugin-sdk/*` test subpaths), and the `ClawdbotConfig` /
+  `OpenClawSchemaType` type aliases
+- bundled plugin allowlist and enablement behavior
+- legacy provider/channel env-var manifest metadata
+- legacy provider plugin hooks and type aliases while providers move to
+  explicit catalog, auth, thinking, replay, and transport hooks
+- legacy runtime aliases such as `api.runtime.taskFlow`,
+  `api.runtime.subagent.getSession`, `api.runtime.stt`, and deprecated
+  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
+- WhatsApp `WebInboundMessage` flat callback fields such as `body`, `chatId`,
+  `reply(...)`, and `mediaPath` while callback consumers migrate to the nested
+  `WebInboundCallbackMessage` `event`, `payload`, `quote`, `group`, and
+  `platform` contexts
+- legacy memory-plugin split registration while memory plugins move to
+  `registerMemoryCapability`
+- legacy memory-specific embedding provider registration while embedding
+  providers move to `api.registerEmbeddingProvider(...)` and
+  `contracts.embeddingProviders`
+- legacy channel SDK helpers for native message schemas, mention gating,
+  inbound envelope formatting, and approval capability nesting
+- legacy channel route key and comparable-target helper aliases while plugins
+  move to `openclaw/plugin-sdk/channel-route`
+- activation hints that are being replaced by manifest contribution ownership
+- `setup-api` runtime fallback while setup descriptors move to cold
+  `setup.requiresRuntime: false` metadata
+- provider `discovery` hooks while provider catalog hooks move to
+  `catalog.run(...)`
+- channel `showConfigured` / `showInSetup` metadata while channel packages move
+  to `openclaw.channel.exposure`
+- legacy runtime-policy config keys while doctor migrates operators to
+  `agentRuntime`
+- generated bundled channel config metadata fallback while registry-first
+  `channelConfigs` metadata lands
+- persisted plugin registry disable and install-migration env flags while
+  repair flows migrate operators to `openclaw plugins registry --refresh` and
+  `openclaw doctor --fix`
+- legacy plugin-owned web search, web fetch, and x_search config paths while
+  doctor migrates them to `plugins.entries.<plugin>.config`
+- legacy `plugins.installs` authored config and bundled plugin load-path
+  aliases while install metadata moves into the state-managed plugin ledger
+
+New plugin code should prefer the replacement listed in the registry and in the
+specific migration guide. Existing plugins can keep using a compatibility path
+until the docs, diagnostics, and release notes announce a removal window.
+
+### WhatsApp Inbound Callback Flat Aliases
+
+WhatsApp runtime callbacks deliver `WebInboundMessage`: the canonical nested
+`event`, `payload`, `quote`, `group`, and `platform` contexts plus deprecated
+flat aliases for the shipped callback fields. New callback code should read the
+nested contexts. Code that constructs clean nested callback messages can use
+`WebInboundCallbackMessage`; compatibility listeners that still inject old flat
+test or plugin messages should use `LegacyFlatWebInboundMessage` or
+`WebInboundMessageInput`.
+
+The flat aliases remain available until **2026-08-30**. That removal window
+applies only to flat alias access; the nested callback shape is the canonical
+runtime contract. The TypeScript `@deprecated` annotations on each flat alias
+name its exact nested replacement. Common examples:
+
+- `id`, `timestamp`, and `isBatched` move under `event`.
+- `body`, `mediaPath`, `mediaType`, `mediaFileName`, `mediaUrl`, `location`, and
+  `untrustedStructuredContext` move under `payload`.
+- `to`, `chatId`, sender/self fields, `sendComposing`, `reply(...)`, and
+  `sendMedia(...)` move under `platform`.
+- `replyTo*` fields move under `quote`, and group subject/participant/mention
+  fields move under `group`.
+
+`payload.untrustedStructuredContext` is extracted from inbound provider payloads.
+Plugins should inspect the `label`, `source`, and `type` before treating its
+`payload` as authoritative.
+
+## Release notes
+
+Release notes should include upcoming plugin deprecations with target dates and
+links to migration docs. That warning needs to happen before a compatibility
+path moves to `removal-pending` or `removed`.