docs: cover cron_changed plugin hook and legacy env-var deprecation

vincentkoc · vincentkoc · commit c478aeca5a7f · 2026-04-28T04:40:38.000-07:00
- docs/plugins/hooks.md: add `cron_changed` to the Lifecycle hook catalog and a Gateway lifecycle paragraph describing its typed event payload, run status, delivery status, and removed-event job snapshot, so plugin authors picking up f155a5f (#72773) have a canonical reference beyond the sdk-overview bullet that already shipped in the same SHA. - docs/help/environment.md: add a "Legacy environment variables" section for aa1834a so users see that `CLAWDBOT_*` and `MOLTBOT_*` prefixes are now ignored and trigger an `OPENCLAW_LEGACY_ENV_VARS` deprecation warning, with a rename example to `OPENCLAW_*`.
diff --git a/docs/help/environment.md b/docs/help/environment.md
@@ -156,6 +156,18 @@ openclaw gateway run
 Do not rely on writing only to `~/.openclaw/.env` for this variable; Node reads
 `NODE_EXTRA_CA_CERTS` at process startup.
 
+## Legacy environment variables
+
+OpenClaw only reads `OPENCLAW_*` environment variables. The legacy
+`CLAWDBOT_*` and `MOLTBOT_*` prefixes from earlier releases are silently
+ignored.
+
+If any are still set on the Gateway process at startup, OpenClaw emits a
+single Node deprecation warning (`OPENCLAW_LEGACY_ENV_VARS`) listing the
+detected prefixes and the total count. Rename each value by replacing the
+legacy prefix with `OPENCLAW_` (for example `CLAWDBOT_GATEWAY_TOKEN` →
+`OPENCLAW_GATEWAY_TOKEN`); the old names take no effect.
+
 ## Related
 
 - [Gateway configuration](/gateway/configuration)
diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md
@@ -109,6 +109,7 @@ observation-only.
 **Lifecycle**
 
 - `gateway_start` / `gateway_stop` — start or stop plugin-owned services with the Gateway
+- `cron_changed` — observe gateway-owned cron lifecycle changes (added, updated, removed, started, finished, scheduled)
 - **`before_install`** — inspect skill or plugin install scans and optionally block
 
 ## Tool call policy
@@ -313,6 +314,17 @@ resources.
 Do not rely on the internal `gateway:startup` hook for plugin-owned runtime
 services.
 
+`cron_changed` fires for gateway-owned cron lifecycle events with a typed
+event payload covering `added`, `updated`, `removed`, `started`, `finished`,
+and `scheduled` reasons. The event carries a `PluginHookGatewayCronJob`
+snapshot (including `state.nextRunAtMs`, `state.lastRunStatus`, and
+`state.lastError` when present) plus a `PluginHookGatewayCronDeliveryStatus`
+of `not-requested` | `delivered` | `not-delivered` | `unknown`. Removed
+events still carry the deleted job snapshot so external schedulers can
+reconcile state. Use `ctx.getCron?.()` and `ctx.config` from the runtime
+context when syncing external wake schedulers, and keep OpenClaw as the
+source of truth for due checks and execution.
+
 ## Upcoming deprecations
 
 A few hook-adjacent surfaces are deprecated but still supported. Migrate
