diff --git a/docs/docs_map.md b/docs/docs_map.md
index 6e0bde3b7eaf..01ca6ca232e5 100644
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -7566,6 +7566,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H3: Why
   - H2: Compatibility policy
   - H3: Channel setup input field compatibility
+  - H4: Verifying readers
   - H2: How to migrate
   - H2: Import path reference
   - H2: Removed compatibility surfaces
diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md
index ecd6d4030403..5bb056ce2db8 100644
--- a/docs/plugins/building-plugins.md
+++ b/docs/plugins/building-plugins.md
@@ -347,6 +347,12 @@ routes that declare `contracts.gatewayMethodDispatch: ["authenticated-request"]`
 
 For the full import map, see [Plugin SDK overview](/plugins/sdk-overview).
 
+OpenClaw SDK compatibility fields carry TypeScript `@deprecated` annotations,
+which editors surface as migration warnings. To enforce them at build time,
+enable a type-aware rule such as
+[`@typescript-eslint/no-deprecated`](https://typescript-eslint.io/rules/no-deprecated/).
+Oxlint is not type-aware, so it cannot enforce these annotations.
+
 ## Pre-submission checklist
 
 <Check>**package.json** has correct `openclaw` metadata</Check>
diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md
index 9ecbbb00c6be..bef413512c33 100644
--- a/docs/plugins/sdk-migration.md
+++ b/docs/plugins/sdk-migration.md
@@ -119,6 +119,13 @@ policy. Declare `singleAccountKeysToMove`, including an empty array when the
 plugin needs no extra promotion keys, so the shared fallback can be retired one
 key at a time.
 
+#### Verifying readers
+
+1. Page through `https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100` with each `nextCursor`, and keep packages whose `categories` include `channels`.
+2. Add npm candidates from `npm search --json --searchlimit=1000 "openclaw channel plugin"`. Add source-only candidates from GitHub code searches for `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup`, and `openclaw/plugin-sdk/core`.
+3. Resolve each candidate's latest published version. Run `npm pack <package>@<version> --json --pack-destination <temp-dir>`, unpack it, and inspect shipped `dist` JavaScript and declarations for direct or destructured field reads. Download the ClawHub artifact when a package has no npm release.
+4. Record package, version, field or promotion key, and matching file. A field or key is deletable only when no published plugin artifact reads it. Keep the reader names in the code comments beside the retained field and key lists synchronized with the sweep.
+
 This is a source/type compatibility record only. It has no runtime adapter or
 compatibility-registry entry because runtime setup input objects and setup
 behavior are unchanged.
diff --git a/docs/plugins/tool-plugins.md b/docs/plugins/tool-plugins.md
index ff13edb16a88..104d0ce504d5 100644
--- a/docs/plugins/tool-plugins.md
+++ b/docs/plugins/tool-plugins.md
@@ -358,6 +358,13 @@ openclaw plugins validate --entry ./dist/index.js
 npm test
 ```
 
+OpenClaw SDK compatibility fields carry TypeScript `@deprecated` annotations,
+which editors surface as migration warnings. To enforce them in CI, enable a
+type-aware rule such as
+[`@typescript-eslint/no-deprecated`](https://typescript-eslint.io/rules/no-deprecated/).
+Oxlint is not type-aware, so it cannot enforce these annotations. The generated
+`plugins init` scaffold therefore does not add a deprecation lint config.
+
 `plugins validate` checks that:
 
 - `openclaw.plugin.json` exists and passes the normal manifest loader.
diff --git a/src/channels/plugins/types.core.ts b/src/channels/plugins/types.core.ts
index 33b93a34062c..575b73a76aa8 100644
--- a/src/channels/plugins/types.core.ts
+++ b/src/channels/plugins/types.core.ts
@@ -109,49 +109,49 @@ type ChannelSetupEnvelope = {
  * Each field is deleted as soon as no published plugin reads it; no version boundary is needed.
  */
 type DeprecatedChannelSetupFields = {
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   privateKey?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   secret?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   botToken?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   appToken?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   signingSecret?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   mode?: "socket" | "http" | "relay";
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   cliPath?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   authDir?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   httpUrl?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   httpPort?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   webhookPath?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   webhookUrl?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   userId?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   accessToken?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   password?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   deviceName?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   url?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   baseUrl?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   code?: string;
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   groupChannels?: string[];
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   dmAllowlist?: string[];
-  /** @deprecated Declare this field in the owning plugin's setup input type. */
+  /** @deprecated Declare this field in the owning plugin's setup input type: https://docs.openclaw.ai/plugins/sdk-setup#channel-owned-setup-input-fields. Removed once no published plugin reads it. */
   autoDiscoverChannels?: boolean;
 };