fix(config): preserve explicit main route bindings

1052326311 · 1052326311 · commit 5373df42a44f · 2026-07-21T02:59:09.000+08:00
diff --git a/src/commands/doctor/shared/legacy-config-binding-repair.ts b/src/commands/doctor/shared/legacy-config-binding-repair.ts
@@ -1,6 +1,6 @@
 // Repairs canonical binding references after agent config migration.
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
-import { normalizeAgentId } from "../../../routing/session-key.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../../routing/session-key.js";
 
 export function pruneBindingsForMissingAgents(
   cfg: OpenClawConfig,
@@ -22,7 +22,11 @@ export function pruneBindingsForMissingAgents(
   const agentIds = new Set(validAgents.map((agent) => normalizeAgentId(agent.id)));
   const nextBindings = bindings.filter((binding) => {
     const agentId = binding && typeof binding === "object" ? binding.agentId : undefined;
-    return typeof agentId !== "string" || agentIds.has(normalizeAgentId(agentId));
+    return (
+      typeof agentId !== "string" ||
+      agentId === DEFAULT_AGENT_ID ||
+      agentIds.has(normalizeAgentId(agentId))
+    );
   });
   const removed = bindings.length - nextBindings.length;
   if (removed === 0) {
diff --git a/src/commands/doctor/shared/legacy-config-migrate.test.ts b/src/commands/doctor/shared/legacy-config-migrate.test.ts
@@ -54,6 +54,22 @@ describe("compatibility binding repair migrate", () => {
     expect(res.changes).toContain("Removed 1 binding that referenced missing agents.list ids.");
   });
 
+  it("preserves exact main bindings because the implicit main agent always exists", () => {
+    const res = repairBindingsForTest({
+      agents: {
+        list: [{ id: "alpha" }],
+      },
+      bindings: [
+        { agentId: "main", match: { channel: "discord" } },
+        { agentId: "MAIN", match: { channel: "discord" } },
+        { agentId: "ghost", match: { channel: "discord" } },
+      ],
+    } as OpenClawConfig);
+
+    expect(res.config.bindings).toEqual([{ agentId: "main", match: { channel: "discord" } }]);
+    expect(res.changes).toContain("Removed 2 bindings that referenced missing agents.list ids.");
+  });
+
   it("leaves bindings untouched when agents.list has malformed entries", () => {
     const cfg = {
       agents: {
diff --git a/src/config/config.schema-regressions.test.ts b/src/config/config.schema-regressions.test.ts
@@ -415,6 +415,43 @@ describe("config schema regressions", () => {
     expect(res.ok).toBe(true);
   });
 
+  it("accepts exact main bindings when agents.list omits the implicit main agent", () => {
+    const res = validateConfigObject({
+      agents: {
+        list: [{ id: "alpha", model: "anthropic/claude-3-5-sonnet" }],
+      },
+      bindings: [
+        {
+          type: "route",
+          agentId: "main",
+          match: { channel: "discord", peer: { kind: "direct", id: "user-1" } },
+        },
+      ],
+    });
+
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects normalized main binding variants when agents.list omits them", () => {
+    const res = validateConfigObject({
+      agents: {
+        list: [{ id: "alpha", model: "anthropic/claude-3-5-sonnet" }],
+      },
+      bindings: [
+        {
+          type: "route",
+          agentId: "MAIN",
+          match: { channel: "discord", peer: { kind: "direct", id: "user-1" } },
+        },
+      ],
+    });
+
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues.some((iss) => iss.message.includes('Unknown agent id "MAIN"'))).toBe(true);
+    }
+  });
+
   it("skips binding agentId check when agents.list is empty (legacy passthrough)", () => {
     const res = validateConfigObject({
       bindings: [
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { normalizeAgentId } from "../routing/session-key.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../routing/session-key.js";
 import { OpenClawSchemaShape } from "./zod-schema.root-shape.js";
 
 // zod@4 ships "sideEffects": false, so bundlers tree-shake the classic entry's
@@ -31,7 +31,11 @@ export const OpenClawSchema = z.strictObject(OpenClawSchemaShape).superRefine((c
         continue;
       }
       const agentId = (binding as { agentId?: unknown }).agentId;
-      if (typeof agentId === "string" && !effectiveAgentIds.has(normalizeAgentId(agentId))) {
+      if (
+        typeof agentId === "string" &&
+        agentId !== DEFAULT_AGENT_ID &&
+        !effectiveAgentIds.has(normalizeAgentId(agentId))
+      ) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ["bindings", idx, "agentId"],
diff --git a/src/routing/resolve-route.test.ts b/src/routing/resolve-route.test.ts
@@ -116,6 +116,35 @@ describe("resolveAgentRoute", () => {
     });
   });
 
+  test("preserves explicit main bindings when agents.list has other agents", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [{ id: "alpha" }],
+      },
+      bindings: [
+        {
+          type: "route",
+          agentId: "main",
+          match: { channel: "discord", accountId: "default" },
+        },
+      ],
+    };
+
+    const route = resolveAgentRoute({
+      cfg,
+      channel: "discord",
+      accountId: "default",
+      peer: { kind: "direct", id: "user-1" },
+    });
+
+    expectResolvedRoute(route, {
+      agentId: "main",
+      sessionKey: "agent:main:main",
+      matchedBy: "binding.account",
+      lastRoutePolicy: "main",
+    });
+  });
+
   test("uses the configured main session key for shared direct routes", () => {
     const route = resolveRoute({
       cfg: { session: { dmScope: "main", mainKey: "work" } },
diff --git a/src/routing/resolve-route.ts b/src/routing/resolve-route.ts
@@ -17,6 +17,7 @@ import {
   buildAgentMainSessionKey,
   buildAgentPeerSessionKey,
   DEFAULT_ACCOUNT_ID,
+  DEFAULT_AGENT_ID,
   DEFAULT_MAIN_KEY,
   normalizeAccountId,
   normalizeAgentId,
@@ -160,6 +161,9 @@ export function pickFirstExistingAgentId(cfg: OpenClawConfig, agentId: string):
     return lookup.fallbackDefaultAgentId;
   }
   const normalized = normalizeAgentId(trimmed);
+  if (normalized === DEFAULT_AGENT_ID) {
+    return DEFAULT_AGENT_ID;
+  }
   if (lookup.byNormalizedId.size === 0) {
     return sanitizeAgentId(trimmed);
   }
