From 9b7a7c5bfebef8a68104f80d292a92cdbadb1ac5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Fri, 24 Apr 2026 20:01:26 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@7536993397c69742facb1b2405f7743aa750924c --- .openclaw-sync/source.json | 4 ++-- docs/plugins/architecture-internals.md | 20 ++++++++++++-------- docs/plugins/manifest.md | 10 ++++++++-- 3 files changed, 22 insertions(+), 12 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 2b1f3eb83..cb27e3f61 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "0e23107ffbabc5303ee50f656015eccf5723915e", - "syncedAt": "2026-04-24T19:53:37.345Z" + "sha": "7536993397c69742facb1b2405f7743aa750924c", + "syncedAt": "2026-04-24T19:59:57.863Z" } diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index 3bbc2294a..25be33818 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -166,7 +166,8 @@ conversation, and it runs after core approval handling finishes. Provider plugins have three layers: -- **Manifest metadata** for cheap pre-runtime lookup: `providerAuthEnvVars`, +- **Manifest metadata** for cheap pre-runtime lookup: + `setup.providers[].envVars`, deprecated compatibility `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices`, and `channelEnvVars`. - **Config-time hooks**: `catalog` (legacy `discovery`) plus `applyConfigDefaults`. @@ -178,13 +179,16 @@ OpenClaw still owns the generic agent loop, failover, transcript handling, and tool policy. These hooks are the extension surface for provider-specific behavior without needing a whole custom inference transport. -Use manifest `providerAuthEnvVars` when the provider has env-based credentials -that generic auth/status/model-picker paths should see without loading plugin -runtime. Use manifest `providerAuthAliases` when one provider id should reuse -another provider id's env vars, auth profiles, config-backed auth, and API-key -onboarding choice. Use manifest `providerAuthChoices` when onboarding/auth-choice -CLI surfaces should know the provider's choice id, group labels, and simple -one-flag auth wiring without loading provider runtime. Keep provider runtime +Use manifest `setup.providers[].envVars` when the provider has env-based +credentials that generic auth/status/model-picker paths should see without +loading plugin runtime. Deprecated `providerAuthEnvVars` is still read by the +compatibility adapter during the deprecation window, and non-bundled plugins +that use it receive a manifest diagnostic. Use manifest `providerAuthAliases` +when one provider id should reuse another provider id's env vars, auth profiles, +config-backed auth, and API-key onboarding choice. Use manifest +`providerAuthChoices` when onboarding/auth-choice CLI surfaces should know the +provider's choice id, group labels, and simple one-flag auth wiring without +loading provider runtime. Keep provider runtime `envVars` for operator-facing hints such as onboarding labels or OAuth client-id/client-secret setup vars. diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index 7aa849067..1dcca6c6b 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -148,7 +148,7 @@ or npm install metadata. Those belong in your plugin code and `package.json`. | `syntheticAuthRefs` | No | `string[]` | Provider or CLI backend refs whose plugin-owned synthetic auth hook should be probed during cold model discovery before runtime loads. | | `nonSecretAuthMarkers` | No | `string[]` | Bundled-plugin-owned placeholder API key values that represent non-secret local, OAuth, or ambient credential state. | | `commandAliases` | No | `object[]` | Command names owned by this plugin that should produce plugin-aware config and CLI diagnostics before runtime loads. | -| `providerAuthEnvVars` | No | `Record` | Cheap provider-auth env metadata that OpenClaw can inspect without loading plugin code. | +| `providerAuthEnvVars` | No | `Record` | Deprecated compatibility env metadata for provider auth/status lookup. Prefer `setup.providers[].envVars` for new plugins; OpenClaw still reads this during the deprecation window. | | `providerAuthAliases` | No | `Record` | Provider ids that should reuse another provider id for auth lookup, for example a coding provider that shares the base provider API key and auth profiles. | | `channelEnvVars` | No | `Record` | Cheap channel env metadata that OpenClaw can inspect without loading plugin code. Use this for env-driven channel setup or auth surfaces that generic startup/config helpers should see. | | `providerAuthChoices` | No | `object[]` | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring. | @@ -327,6 +327,12 @@ narrows the candidate plugin and setup still needs richer setup-time runtime hooks, set `requiresRuntime: true` and keep `setup-api` in place as the fallback execution path. +OpenClaw also includes `setup.providers[].envVars` in generic provider auth and +env-var lookups. `providerAuthEnvVars` remains supported through a compatibility +adapter during the deprecation window, but non-bundled plugins that still use it +receive a manifest diagnostic. New plugins should put setup/status env metadata +on `setup.providers[].envVars`. + Set `requiresRuntime: false` only when those descriptors are sufficient for the setup surface. OpenClaw treats explicit `false` as a descriptor-only contract and will not execute `setup-api` for setup lookup. Omitted `requiresRuntime` @@ -725,7 +731,7 @@ See [Configuration reference](/gateway/configuration) for the full `plugins.*` s - `channels`, `providers`, `cliBackends`, and `skills` can all be omitted when a plugin does not need them. - `providerDiscoveryEntry` must stay lightweight and should not import broad runtime code; use it for static provider catalog metadata or narrow discovery descriptors, not request-time execution. - Exclusive plugin kinds are selected through `plugins.slots.*`: `kind: "memory"` via `plugins.slots.memory`, `kind: "context-engine"` via `plugins.slots.contextEngine` (default `legacy`). -- Env-var metadata (`providerAuthEnvVars`, `channelEnvVars`) is declarative only. Status, audit, cron delivery validation, and other read-only surfaces still apply plugin trust and effective activation policy before treating an env var as configured. +- Env-var metadata (`setup.providers[].envVars`, deprecated `providerAuthEnvVars`, and `channelEnvVars`) is declarative only. Status, audit, cron delivery validation, and other read-only surfaces still apply plugin trust and effective activation policy before treating an env var as configured. - For runtime wizard metadata that requires provider code, see [Provider runtime hooks](/plugins/architecture-internals#provider-runtime-hooks). - If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm `allow-build-scripts` + `pnpm rebuild `).