docs(types): mark legacy aliases deprecated

src/auto-reply/templating.ts

@@ -45,6 +45,8 @@ export type MsgContext = {
     timestamp?: number;
   }>;
   /**
+   * @deprecated Use CommandBody.
+   *
    * Raw message body without structural context (history, sender labels).
    * Legacy alias for CommandBody. Falls back to Body if not set.
    */

src/channels/plugins/types.core.ts

@@ -112,7 +112,7 @@ export type ChannelSetupInput = {
   useEnv?: boolean;
   homeserver?: string;
   dangerouslyAllowPrivateNetwork?: boolean;
-  /** Compatibility alias for legacy setup callers; prefer dangerouslyAllowPrivateNetwork. */
+  /** @deprecated Compatibility alias; prefer dangerouslyAllowPrivateNetwork. */
   allowPrivateNetwork?: boolean;
   proxy?: string;
   userId?: string;
@@ -407,6 +407,8 @@ export type ChannelThreadingAdapter = {
    */
   allowExplicitReplyTagsWhenOff?: boolean;
   /**
+   * @deprecated Use allowExplicitReplyTagsWhenOff.
+   *
    * Deprecated alias for allowExplicitReplyTagsWhenOff.
    * Kept for compatibility with older plugin surfaces.
    */

src/cli/config-set-input.ts

@@ -7,6 +7,7 @@ import {
 
 export type ConfigSetOptions = {
   strictJson?: boolean;
+  /** @deprecated Use strictJson. */
   json?: boolean;
   dryRun?: boolean;
   allowExec?: boolean;

src/cli/gateway-cli/run.ts

@@ -49,6 +49,7 @@ type GatewayRunOpts = {
   force?: boolean;
   verbose?: boolean;
   cliBackendLogs?: boolean;
+  /** @deprecated Use cliBackendLogs. */
   claudeCliLogs?: boolean;
   wsLog?: unknown;
   compact?: boolean;

src/cli/plugins-cli.ts

@@ -42,6 +42,7 @@ export type PluginMarketplaceListOptions = {
 
 export type PluginUninstallOptions = {
   keepFiles?: boolean;
+  /** @deprecated Use keepFiles. */
   keepConfig?: boolean;
   force?: boolean;
   dryRun?: boolean;

src/commands/onboard-types.ts

@@ -8,7 +8,7 @@ export type OnboardMode = "local" | "remote";
  * are normalized elsewhere (for example `oauth` -> `setup-token`).
  */
 export type BuiltInAuthChoice =
-  // Legacy alias for `setup-token` (kept for backwards CLI compatibility).
+  /** @deprecated Use `setup-token`. */
   "oauth" | "setup-token" | "token" | "apiKey" | "custom-api-key" | "skip";
 export type AuthChoice = BuiltInAuthChoice | (string & {});
 
@@ -20,7 +20,7 @@ export type GatewayBind = "loopback" | "lan" | "auto" | "custom" | "tailnet";
 export type TailscaleMode = "off" | "serve" | "funnel";
 export type NodeManagerChoice = "npm" | "pnpm" | "bun";
 export type ChannelChoice = ChannelId;
-// Legacy alias (pre-rename).
+/** @deprecated Use ChannelChoice. */
 export type ProviderChoice = ChannelChoice;
 export type { SecretInputMode } from "../plugins/provider-auth-types.js";
 

src/config/types.base.ts

@@ -195,11 +195,11 @@ export type SessionMaintenanceConfig = {
   mode?: SessionMaintenanceMode;
   /** Remove session entries older than this duration (e.g. "30d", "12h"). Default: "30d". */
   pruneAfter?: string | number;
-  /** Deprecated. Use pruneAfter instead. */
+  /** @deprecated Use pruneAfter instead. */
   pruneDays?: number;
   /** Maximum number of session entries to keep. Default: 500. */
   maxEntries?: number;
-  /** Deprecated and ignored. Run `openclaw doctor --fix` to remove. */
+  /** @deprecated Ignored. Run `openclaw doctor --fix` to remove. */
   rotateBytes?: number | string;
   /**
    * Retention for archived reset transcripts (`*.reset.<timestamp>`).

src/config/types.cron.ts

@@ -35,7 +35,7 @@ export type CronConfig = {
   /** Override default retry policy for one-shot jobs on transient errors. */
   retry?: CronRetryConfig;
   /**
-   * Deprecated legacy fallback webhook URL used only for stored jobs with notify=true.
+   * @deprecated Legacy fallback webhook URL used only for stored jobs with notify=true.
    * Prefer per-job delivery.mode="webhook" with delivery.to.
    */
   webhook?: string;

src/config/types.models.ts

@@ -151,10 +151,24 @@ export type ModelsConfig = {
   mode?: "merge" | "replace";
   providers?: Record<string, ModelProviderConfig>;
   pricing?: ModelPricingConfig;
-  // Deprecated legacy compat aliases. Kept in the runtime type surface so
-  // doctor/runtime fallbacks can read older configs until migration completes.
+  /**
+   * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read
+   * older configs until migration completes.
+   */
   bedrockDiscovery?: BedrockDiscoveryConfig;
+  /**
+   * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read
+   * older configs until migration completes.
+   */
   copilotDiscovery?: DiscoveryToggleConfig;
+  /**
+   * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read
+   * older configs until migration completes.
+   */
   huggingfaceDiscovery?: DiscoveryToggleConfig;
+  /**
+   * @deprecated Legacy compat alias. Kept so doctor/runtime fallbacks can read
+   * older configs until migration completes.
+   */
   ollamaDiscovery?: DiscoveryToggleConfig;
 };

src/extensionAPI.ts

@@ -1,5 +1,8 @@
-// Legacy compat surface for plugins that still import openclaw/extension-api.
-// Keep this file intentionally narrow and forward-only.
+/**
+ * @deprecated Legacy compat surface for plugins that still import
+ * openclaw/extension-api. Use the injected plugin runtime or focused
+ * openclaw/plugin-sdk subpaths instead.
+ */
 
 const shouldWarnExtensionApiImport =
   process.env.VITEST !== "true" &&

src/infra/session-cost-usage.ts

@@ -362,7 +362,8 @@ export function resolveExistingUsageSessionFile(params: {
 export async function loadCostUsageSummary(params?: {
   startMs?: number;
   endMs?: number;
-  days?: number; // Deprecated, for backwards compatibility
+  /** @deprecated Use startMs/endMs. */
+  days?: number;
   config?: OpenClawConfig;
   agentId?: string;
 }): Promise<CostUsageSummary> {

src/plugin-sdk/channel-config-schema-legacy.ts

@@ -1,5 +1,5 @@
 /**
- * @deprecated Deprecated bundled-channel compatibility surface. Compatibility surface for bundled channel schemas.
+ * @deprecated Compatibility surface for bundled channel schemas.
  *
  * OpenClaw-maintained bundled plugins should import
  * openclaw/plugin-sdk/bundled-channel-config-schema. Third-party plugins should

src/plugin-sdk/compat.ts

@@ -1,5 +1,8 @@
-// Legacy compat surface for external plugins that still depend on older
-// broad plugin-sdk imports. Keep this file intentionally small.
+/**
+ * @deprecated Legacy compat surface for external plugins that still depend on
+ * older broad plugin-sdk imports. Use focused openclaw/plugin-sdk subpaths
+ * instead.
+ */
 
 const shouldWarnCompatImport =
   process.env.VITEST !== "true" &&

src/plugin-sdk/ssrf-policy.ts

@@ -23,7 +23,7 @@ export type PrivateNetworkOptInInput =
   | Pick<SsrFPolicy, "allowPrivateNetwork" | "dangerouslyAllowPrivateNetwork">
   | {
       dangerouslyAllowPrivateNetwork?: boolean | null;
-      /** Compatibility alias for legacy callers; prefer dangerouslyAllowPrivateNetwork. */
+      /** @deprecated Compatibility alias; prefer dangerouslyAllowPrivateNetwork. */
       allowPrivateNetwork?: boolean | null;
       network?:
         | Pick<SsrFPolicy, "allowPrivateNetwork" | "dangerouslyAllowPrivateNetwork">

src/plugins/types.ts

@@ -1214,6 +1214,8 @@ export type ProviderPlugin = {
    */
   staticCatalog?: ProviderPluginCatalog;
   /**
+   * @deprecated Use catalog.
+   *
    * Legacy alias for catalog.
    * Kept for compatibility with existing provider plugins.
    */