feat(plugins): read setup provider env vars (#71226)

* feat(plugins): read setup provider env vars

* fix(plugins): mark provider env compat deprecation

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.
 

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<string, string[]>`       | Cheap provider-auth env metadata that OpenClaw can inspect without loading plugin code.                                                                                                                                           |
+| `providerAuthEnvVars`                | No       | `Record<string, string[]>`       | 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<string, string>`         | 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<string, string[]>`       | 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 <package>`).