[codex] harden clawhub plugin publishing and install (#56870)

* fix: harden clawhub plugin publishing and install

* fix(process): preserve windows shim exit success

docs/plugins/building-plugins.md

@@ -52,7 +52,15 @@ and provider plugins have dedicated guides linked above.
       "version": "1.0.0",
       "type": "module",
       "openclaw": {
-        "extensions": ["./index.ts"]
+        "extensions": ["./index.ts"],
+        "compat": {
+          "pluginApi": ">=2026.3.24-beta.2",
+          "minGatewayVersion": "2026.3.24-beta.2"
+        },
+        "build": {
+          "openclawVersion": "2026.3.24-beta.2",
+          "pluginSdkVersion": "2026.3.24-beta.2"
+        }
       }
     }
     ```
@@ -71,7 +79,8 @@ and provider plugins have dedicated guides linked above.
     </CodeGroup>
 
     Every plugin needs a manifest, even with no config. See
-    [Manifest](/plugins/manifest) for the full schema.
+    [Manifest](/plugins/manifest) for the full schema. The canonical ClawHub
+    publish snippets live in `docs/snippets/plugin-publish/`.
 
   </Step>
 
@@ -107,13 +116,16 @@ and provider plugins have dedicated guides linked above.
 
   <Step title="Test and publish">
 
-    **External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install:
+    **External plugins:** validate and publish with ClawHub, then install:
 
     ```bash
-    openclaw plugins install @myorg/openclaw-my-plugin
+    clawhub package publish your-org/your-plugin --dry-run
+    clawhub package publish your-org/your-plugin
+    openclaw plugins install clawhub:@myorg/openclaw-my-plugin
     ```
 
-    OpenClaw checks ClawHub first, then falls back to npm.
+    OpenClaw also checks ClawHub before npm for bare package specs like
+    `@myorg/openclaw-my-plugin`.
 
     **In-repo plugins:** place under the bundled plugin workspace tree — automatically discovered.
 

docs/plugins/sdk-provider-plugins.md

@@ -32,7 +32,15 @@ API key auth, and dynamic model resolution.
       "type": "module",
       "openclaw": {
         "extensions": ["./index.ts"],
-        "providers": ["acme-ai"]
+        "providers": ["acme-ai"],
+        "compat": {
+          "pluginApi": ">=2026.3.24-beta.2",
+          "minGatewayVersion": "2026.3.24-beta.2"
+        },
+        "build": {
+          "openclawVersion": "2026.3.24-beta.2",
+          "pluginSdkVersion": "2026.3.24-beta.2"
+        }
       }
     }
     ```
@@ -68,7 +76,9 @@ API key auth, and dynamic model resolution.
     </CodeGroup>
 
     The manifest declares `providerAuthEnvVars` so OpenClaw can detect
-    credentials without loading your plugin runtime.
+    credentials without loading your plugin runtime. If you publish the
+    provider on ClawHub, those `openclaw.compat` and `openclaw.build` fields
+    are required in `package.json`.
 
   </Step>
 
@@ -383,6 +393,18 @@ API key auth, and dynamic model resolution.
   </Step>
 </Steps>
 
+## Publish to ClawHub
+
+Provider plugins publish the same way as any other external code plugin:
+
+```bash
+clawhub package publish your-org/your-plugin --dry-run
+clawhub package publish your-org/your-plugin
+```
+
+Do not use the legacy skill-only publish alias here; plugin packages should use
+`clawhub package publish`.
+
 ## File structure
 
 ```

docs/plugins/sdk-setup.md

@@ -43,20 +43,31 @@ your plugin provides:
 }
 ```
 
-**Provider plugin:**
+**Provider plugin / ClawHub publish baseline:**
 
-```json
+```json openclaw-clawhub-package.json
 {
-  "name": "@myorg/openclaw-my-provider",
+  "name": "@myorg/openclaw-my-plugin",
   "version": "1.0.0",
   "type": "module",
   "openclaw": {
     "extensions": ["./index.ts"],
-    "providers": ["my-provider"]
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
   }
 }
 ```
 
+If you publish the plugin externally on ClawHub, those `compat` and `build`
+fields are required. The canonical publish snippets live in
+`docs/snippets/plugin-publish/`.
+
 ### `openclaw` fields
 
 | Field        | Type       | Description                                                                                |
@@ -147,6 +158,18 @@ Even plugins with no config must ship a schema. An empty schema is valid:
 
 See [Plugin Manifest](/plugins/manifest) for the full schema reference.
 
+## ClawHub publishing
+
+For plugin packages, use the package-specific ClawHub command:
+
+```bash
+clawhub package publish your-org/your-plugin --dry-run
+clawhub package publish your-org/your-plugin
+```
+
+The legacy skill-only publish alias is for skills. Plugin packages should
+always use `clawhub package publish`.
+
 ## Setup entry
 
 The `setup-entry.ts` file is a lightweight alternative to `index.ts` that