feat: declare openai catalog suppressions

extensions/openai/openclaw.plugin.json

@@ -41,6 +41,31 @@
       }
     }
   },
+  "modelCatalog": {
+    "aliases": {
+      "azure-openai-responses": {
+        "provider": "openai",
+        "api": "azure-openai-responses"
+      }
+    },
+    "suppressions": [
+      {
+        "provider": "openai",
+        "model": "gpt-5.3-codex-spark",
+        "reason": "gpt-5.3-codex-spark is no longer exposed by the OpenAI or Codex catalogs. Use openai/gpt-5.5."
+      },
+      {
+        "provider": "azure-openai-responses",
+        "model": "gpt-5.3-codex-spark",
+        "reason": "gpt-5.3-codex-spark is no longer exposed by the OpenAI or Codex catalogs. Use openai/gpt-5.5."
+      },
+      {
+        "provider": "openai-codex",
+        "model": "gpt-5.3-codex-spark",
+        "reason": "gpt-5.3-codex-spark is no longer exposed by the OpenAI or Codex catalogs. Use openai/gpt-5.5."
+      }
+    ]
+  },
   "cliBackends": ["codex-cli"],
   "providerAuthEnvVars": {
     "openai": ["OPENAI_API_KEY"]

src/plugins/provider-runtime.ts

@@ -1102,6 +1102,9 @@ export function resolveProviderBuiltInModelSuppression(params: {
   env?: NodeJS.ProcessEnv;
   context: ProviderBuiltInModelSuppressionContext;
 }) {
+  // Deprecated compatibility fallback. Static suppression rules should live in
+  // manifest modelCatalog.suppressions so list/model resolution can answer
+  // without loading provider runtime.
   for (const plugin of resolveProviderPluginsForCatalogHooks(params)) {
     const result = plugin.suppressBuiltInModel?.(params.context);
     if (result?.suppress) {

src/plugins/types.ts

@@ -966,11 +966,11 @@ export type ProviderBuildUnknownModelHintContext = {
 };
 
 /**
- * Built-in model suppression hook.
+ * Built-in model suppression hook context.
  *
- * Use this when a provider/plugin needs to hide stale upstream catalog rows or
- * replace them with a vendor-specific hint. This hook is consulted by model
- * resolution, model listing, and catalog loading.
+ * @deprecated Use manifest `modelCatalog.suppressions` for static suppression
+ * rules. Runtime suppression hooks remain as compatibility fallback for
+ * plugins that cannot express a rule declaratively yet.
  */
 export type ProviderBuiltInModelSuppressionContext = {
   config?: OpenClawConfig;
@@ -1480,6 +1480,10 @@ export type ProviderPlugin = {
    * Return `{ suppress: true }` to hide a stale upstream row. Include
    * `errorMessage` when OpenClaw should surface a provider-specific hint for
    * direct model resolution failures.
+   *
+   * @deprecated Use manifest `modelCatalog.suppressions` for static suppression
+   * rules. Runtime suppression hooks remain as compatibility fallback for
+   * plugins that cannot express a rule declaratively yet.
    */
   suppressBuiltInModel?: (
     ctx: ProviderBuiltInModelSuppressionContext,