fix(agents): inherit default agent model catalog for secondary agents

thinhkhang97 · thinhkhang97 · commit 5ddb7faae44a · 2026-06-08T11:44:11.000+07:00
Model discovery only runs for the default/main agent at gateway startup, so
generated plugin model catalogs (e.g. plugins/google/catalog.json) are only
populated under the default agent dir. A secondary agent created with
`openclaw agents add` gets an apiKey-only google catalog with no models, so a
Google/Gemini model authenticated via GEMINI_API_KEY fails at runtime with
`FailoverError: Unknown model: google/gemini-2.5-flash`. The default agent works.

Add read-through inheritance for generated plugin model catalogs, mirroring the
existing auth-profile read-through (`inheritedAuthDir`).

Implementation is local-first with a per-provider gap-fill gate:

- The agent's OWN catalogs (root models.json + local plugin catalogs) load first
  and establish its full local state.
- Inheritance is gated per provider: a provider the local agent already has any
  model for is excluded from the inherited load entirely — it contributes no
  provider request config, no per-model headers, and no models for that provider.
  So "local always wins" never depends on write order, and an inherited catalog
  can neither read nor overwrite the local agent's request config/headers.
- Only providers the secondary agent does not configure at all are inherited
  (config + headers + models), which is exactly the agent that is living on
  inheritance. apiKey values in catalogs are env refs (e.g. GEMINI_API_KEY)
  resolved per-agent, so no secret material crosses the agent boundary.
- A broken/invalid inherited catalog is skipped, never breaking the local agent.

`discoverModels` threads `inheritedAgentDir` through to the registry;
`discoverCachedAgentStores` passes the resolved default agent dir and folds the
inherited catalog files into the discovery-cache fingerprint so changes to the
default agent's catalog invalidate the secondary agent's cached snapshot. The
default agent never inherits from itself (path-equality guard).
diff --git a/src/agents/agent-model-discovery.ts b/src/agents/agent-model-discovery.ts
@@ -38,6 +38,11 @@ type DiscoverModelsOptions = {
   pluginMetadataSnapshot?: PluginModelCatalogMetadataSnapshot;
   workspaceDir?: string;
   normalizeModels?: boolean;
+  /**
+   * Default/main agent directory used as a read-through fallback for a secondary agent's
+   * generated plugin model catalogs. See `ModelRegistry` `inheritedAgentDir`.
+   */
+  inheritedAgentDir?: string;
 };
 
 /** Applies plugin model normalization and transport hooks to discovered agent models. */
@@ -102,7 +107,10 @@ function createOpenClawModelRegistry(
     allowWorkspaceScopedCurrent: options?.workspaceDir === undefined,
     useRuntimeConfig: options?.config === undefined,
   });
-  const registryOptions = pluginMetadataSnapshot ? { pluginMetadataSnapshot } : {};
+  const registryOptions = {
+    ...(pluginMetadataSnapshot ? { pluginMetadataSnapshot } : {}),
+    ...(options?.inheritedAgentDir ? { inheritedAgentDir: options.inheritedAgentDir } : {}),
+  };
   const registry = ModelRegistry.create(authStorage, modelsJsonPath, registryOptions);
   const getAll = registry.getAll.bind(registry);
   const getAvailable = registry.getAvailable.bind(registry);
diff --git a/src/agents/embedded-agent-runner/model-discovery-cache.ts b/src/agents/embedded-agent-runner/model-discovery-cache.ts
@@ -91,6 +91,11 @@ function discoveryFingerprint(
     modelsJson: fileFingerprint(path.join(params.agentDir, "models.json")),
     pluginMetadata: pluginMetadataFingerprint(params.pluginMetadataSnapshot),
     pluginModelCatalogs: pluginModelCatalogFingerprint(params.agentDir),
+    // Secondary agents read through to the default agent's plugin catalogs, so changes to
+    // those inherited catalogs must invalidate this agent's cached discovery snapshot.
+    inheritedPluginModelCatalogs: inheritedAuthDir
+      ? pluginModelCatalogFingerprint(inheritedAuthDir)
+      : undefined,
   });
 }
 
@@ -137,12 +142,20 @@ function discoverFreshAgentStores(
   agentDir: string,
   options: Pick<DiscoverCachedAgentStoresOptions, "config" | "workspaceDir">,
   pluginMetadataSnapshot: PluginMetadataSnapshot | undefined,
+  inheritedAgentDir: string | undefined,
 ): DiscoveryStores {
   const authStorage = discoverAuthStorage(agentDir);
+  // Only inherit when the default agent dir is genuinely distinct, so the default agent
+  // never reads through to itself.
+  const inheritDir =
+    inheritedAgentDir && path.resolve(inheritedAgentDir) !== path.resolve(agentDir)
+      ? inheritedAgentDir
+      : undefined;
   const modelRegistry = discoverModels(authStorage, agentDir, {
     ...(options.config ? { config: options.config } : {}),
     ...(pluginMetadataSnapshot ? { pluginMetadataSnapshot } : {}),
     ...(options.workspaceDir ? { workspaceDir: options.workspaceDir } : {}),
+    ...(inheritDir ? { inheritedAgentDir: inheritDir } : {}),
   });
   return { authStorage, modelRegistry };
 }
@@ -162,6 +175,7 @@ export function discoverCachedAgentStores(
       agentDir,
       options,
       resolvePluginMetadataSnapshotForDiscovery(options),
+      inheritedAuthDir,
     );
   }
   const pluginMetadataSnapshot = resolvePluginMetadataSnapshotForDiscovery(options);
@@ -177,7 +191,12 @@ export function discoverCachedAgentStores(
     };
   }
 
-  const stores = discoverFreshAgentStores(agentDir, options, pluginMetadataSnapshot);
+  const stores = discoverFreshAgentStores(
+    agentDir,
+    options,
+    pluginMetadataSnapshot,
+    inheritedAuthDir,
+  );
   DISCOVERY_STORE_CACHE.set(cacheKey, {
     authStorage: stores.authStorage,
     fingerprint,
diff --git a/src/agents/sessions/model-registry.test.ts b/src/agents/sessions/model-registry.test.ts
@@ -226,3 +226,257 @@ describe("ModelRegistry models.json auth", () => {
     expect(registry.find("zai", "glm-5.1")).toBeUndefined();
   });
 });
+
+describe("ModelRegistry default-agent catalog inheritance", () => {
+  // Model discovery only runs for the default agent at gateway startup, so a freshly
+  // created secondary agent has an apiKey-only google catalog with no models. Without
+  // read-through inheritance it fails at runtime with "Unknown model: google/...".
+  function writeGoogleCatalogAgentDir(params: { withModels: boolean; modelName?: string }): string {
+    return writeModelsJsonWithPluginCatalog({
+      root: { providers: {} },
+      pluginRelativePath: join("plugins", "google", PLUGIN_MODEL_CATALOG_FILE),
+      pluginCatalog: {
+        generatedBy: PLUGIN_MODEL_CATALOG_GENERATED_BY,
+        providers: {
+          google: params.withModels
+            ? {
+                baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+                api: "openai-responses",
+                apiKey: "GEMINI_API_KEY",
+                models: [
+                  { id: "gemini-2.5-flash", name: params.modelName ?? "Gemini 2.5 Flash" },
+                ],
+              }
+            : { apiKey: "GEMINI_API_KEY" },
+        },
+      },
+    });
+  }
+
+  it("inherits the default agent's generated catalog models for a secondary agent", () => {
+    const defaultAgentDir = dirname(writeGoogleCatalogAgentDir({ withModels: true }));
+    const secondaryModelsPath = writeGoogleCatalogAgentDir({ withModels: false });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      {
+        pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google"),
+        inheritedAgentDir: defaultAgentDir,
+      },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+    expect(registry.find("google", "gemini-2.5-flash")?.name).toBe("Gemini 2.5 Flash");
+  });
+
+  it("does not inherit without an inheritedAgentDir (reproduces the bug)", () => {
+    const secondaryModelsPath = writeGoogleCatalogAgentDir({ withModels: false });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      { pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google") },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+    expect(registry.find("google", "gemini-2.5-flash")).toBeUndefined();
+  });
+
+  it("prefers the secondary agent's own catalog over inherited models", () => {
+    const defaultAgentDir = dirname(
+      writeGoogleCatalogAgentDir({ withModels: true, modelName: "Gemini 2.5 Flash (default)" }),
+    );
+    const secondaryModelsPath = writeGoogleCatalogAgentDir({
+      withModels: true,
+      modelName: "Gemini 2.5 Flash (local)",
+    });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      {
+        pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google"),
+        inheritedAgentDir: defaultAgentDir,
+      },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+    expect(registry.find("google", "gemini-2.5-flash")?.name).toBe("Gemini 2.5 Flash (local)");
+  });
+
+  it("does not let an inherited catalog override a local provider's config/headers or leak sibling models", async () => {
+    // Regression: a provider the secondary agent defines in its own models.json must keep
+    // its local request config (headers/auth) and must NOT gain sibling models from the
+    // default agent's catalog — otherwise a local model would run with the default agent's
+    // credentials/transport (a cross-agent boundary violation), and inheritance would no
+    // longer be "local always wins".
+    const defaultAgentDir = dirname(
+      writeModelsJsonWithPluginCatalog({
+        root: { providers: {} },
+        pluginRelativePath: join("plugins", "google", PLUGIN_MODEL_CATALOG_FILE),
+        pluginCatalog: {
+          generatedBy: PLUGIN_MODEL_CATALOG_GENERATED_BY,
+          providers: {
+            google: {
+              baseUrl: "https://default.example/v1beta",
+              api: "openai-responses",
+              apiKey: "GEMINI_API_KEY",
+              headers: { "x-source": "default" },
+              models: [
+                { id: "gemini-2.5-flash", name: "Flash (default)" },
+                { id: "gemini-3-flash-preview", name: "3 Flash (default)" },
+              ],
+            },
+          },
+        },
+      }),
+    );
+
+    // Secondary agent owns google via its OWN models.json (not a plugin catalog).
+    const secondaryModelsPath = writeModelsJson({
+      providers: {
+        google: {
+          baseUrl: "https://local.example/v1beta",
+          api: "openai-responses",
+          apiKey: "GEMINI_API_KEY",
+          headers: { "x-source": "local" },
+          models: [{ id: "gemini-2.5-flash", name: "Flash (local)" }],
+        },
+      },
+    });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      {
+        pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google"),
+        inheritedAgentDir: defaultAgentDir,
+      },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+
+    const local = registry.find("google", "gemini-2.5-flash");
+    expect(local?.name).toBe("Flash (local)");
+    // Per-provider gating: the default agent's sibling model must not leak in.
+    expect(registry.find("google", "gemini-3-flash-preview")).toBeUndefined();
+
+    // Local provider request config (headers) must survive inherited loading.
+    const resolved = await registry.getApiKeyAndHeaders(local!);
+    if (!resolved.ok) {
+      throw new Error(`expected resolved auth, got error: ${resolved.error}`);
+    }
+    expect(resolved.headers?.["x-source"]).toBe("local");
+  });
+
+  it("resolves local request config when the local provider comes from a local plugin catalog", async () => {
+    // Same guarantee as above, but the local provider is owned via a local plugin catalog
+    // (not root models.json) — covers the other registration path end-to-end.
+    const defaultAgentDir = dirname(
+      writeModelsJsonWithPluginCatalog({
+        root: { providers: {} },
+        pluginRelativePath: join("plugins", "google", PLUGIN_MODEL_CATALOG_FILE),
+        pluginCatalog: {
+          generatedBy: PLUGIN_MODEL_CATALOG_GENERATED_BY,
+          providers: {
+            google: {
+              baseUrl: "https://default.example/v1beta",
+              api: "openai-responses",
+              apiKey: "GEMINI_API_KEY",
+              headers: { "x-source": "default" },
+              models: [
+                { id: "gemini-2.5-flash", name: "Flash (default)" },
+                { id: "gemini-3-flash-preview", name: "3 Flash (default)" },
+              ],
+            },
+          },
+        },
+      }),
+    );
+
+    const secondaryModelsPath = writeModelsJsonWithPluginCatalog({
+      root: { providers: {} },
+      pluginRelativePath: join("plugins", "google", PLUGIN_MODEL_CATALOG_FILE),
+      pluginCatalog: {
+        generatedBy: PLUGIN_MODEL_CATALOG_GENERATED_BY,
+        providers: {
+          google: {
+            baseUrl: "https://local.example/v1beta",
+            api: "openai-responses",
+            apiKey: "GEMINI_API_KEY",
+            headers: { "x-source": "local" },
+            models: [{ id: "gemini-2.5-flash", name: "Flash (local)" }],
+          },
+        },
+      },
+    });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      {
+        pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google"),
+        inheritedAgentDir: defaultAgentDir,
+      },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+
+    const local = registry.find("google", "gemini-2.5-flash");
+    expect(local?.name).toBe("Flash (local)");
+    expect(registry.find("google", "gemini-3-flash-preview")).toBeUndefined();
+
+    const resolved = await registry.getApiKeyAndHeaders(local!);
+    if (!resolved.ok) {
+      throw new Error(`expected resolved auth, got error: ${resolved.error}`);
+    }
+    expect(resolved.headers?.["x-source"]).toBe("local");
+  });
+
+  it("resolves an inherited-only provider with the inherited baseUrl and headers", async () => {
+    // For a provider the secondary agent does not configure at all, inheritance must supply
+    // the default agent's baseUrl/api and request headers so the model is actually usable.
+    const defaultAgentDir = dirname(
+      writeModelsJsonWithPluginCatalog({
+        root: { providers: {} },
+        pluginRelativePath: join("plugins", "google", PLUGIN_MODEL_CATALOG_FILE),
+        pluginCatalog: {
+          generatedBy: PLUGIN_MODEL_CATALOG_GENERATED_BY,
+          providers: {
+            google: {
+              baseUrl: "https://inherited.example/v1beta",
+              api: "openai-responses",
+              apiKey: "GEMINI_API_KEY",
+              headers: { "x-source": "inherited" },
+              models: [{ id: "gemini-2.5-flash", name: "Flash (inherited)" }],
+            },
+          },
+        },
+      }),
+    );
+
+    // Secondary agent configures no provider of its own (lives on inheritance).
+    const secondaryModelsPath = writeModelsJson({ providers: {} });
+
+    const registry = ModelRegistry.create(
+      AuthStorage.inMemory({ google: { type: "api_key", key: "sk-test" } }),
+      secondaryModelsPath,
+      {
+        pluginMetadataSnapshot: pluginOwnerSnapshot("google", "google"),
+        inheritedAgentDir: defaultAgentDir,
+      },
+    );
+
+    expect(registry.getError()).toBeUndefined();
+
+    const model = registry.find("google", "gemini-2.5-flash");
+    expect(model?.baseUrl).toBe("https://inherited.example/v1beta");
+
+    const resolved = await registry.getApiKeyAndHeaders(model!);
+    if (!resolved.ok) {
+      throw new Error(`expected resolved auth, got error: ${resolved.error}`);
+    }
+    expect(resolved.headers?.["x-source"]).toBe("inherited");
+  });
+});
diff --git a/src/agents/sessions/model-registry.ts b/src/agents/sessions/model-registry.ts
