fix: load Codex for selectable OpenAI agent models

pashpashpash · web-flow · commit 3ce922437fb6 · 2026-05-14T09:51:15.000+08:00
Treat selectable configured OpenAI agent models as Codex runtime requirements during plugin auto-enable, startup planning, and doctor install repair.\n\nPR: #81591
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Codex startup: treat selectable configured OpenAI agent models as Codex runtime requirements during plugin auto-enable, startup planning, and doctor install repair, so Anthropic-primary configs can still switch to OpenAI/Codex cleanly.
 - Sessions/status: classify ACP spawn-child sessions as `kind: "spawn-child"` instead of `"direct"` in `openclaw sessions` and status output; extract the duplicated session-kind classifier into a shared helper (`src/sessions/classify-session-kind.ts`) so both surfaces stay in sync. Fixes catalog #19. (#79544)
 - Telegram: delete tool-progress-only draft bubbles before rotating to the real answer, preventing orphaned progress messages in streamed replies.
 - Codex app-server: keep per-agent `CODEX_HOME` isolation without rewriting `HOME` by default, so Codex-run subprocesses can still find normal user-home config, tokens, and CLI state unless the launch explicitly overrides `HOME`. Thanks @pashpashpash.
diff --git a/src/agents/harness-runtimes.test.ts b/src/agents/harness-runtimes.test.ts
@@ -3,6 +3,86 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { collectConfiguredAgentHarnessRuntimes } from "./harness-runtimes.js";
 
 describe("collectConfiguredAgentHarnessRuntimes", () => {
+  it("requires Codex for selectable default OpenAI agent models", () => {
+    const config = {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-sonnet-4-6" },
+          models: {
+            "openai/gpt-5.5": {},
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(collectConfiguredAgentHarnessRuntimes(config, {}, { includeEnvRuntime: false })).toEqual(
+      ["codex"],
+    );
+  });
+
+  it("requires Codex for selectable per-agent OpenAI models", () => {
+    const config = {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-sonnet-4-6" },
+        },
+        list: [
+          {
+            id: "worker",
+            models: {
+              "openai/gpt-5.5": {},
+            },
+          },
+        ],
+      },
+    } as OpenClawConfig;
+
+    expect(collectConfiguredAgentHarnessRuntimes(config, {}, { includeEnvRuntime: false })).toEqual(
+      ["codex"],
+    );
+  });
+
+  it("respects explicit Pi runtime policy on selectable OpenAI agent models", () => {
+    const config = {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-sonnet-4-6" },
+          models: {
+            "openai/gpt-5.5": { agentRuntime: { id: "pi" } },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(collectConfiguredAgentHarnessRuntimes(config, {}, { includeEnvRuntime: false })).toEqual(
+      [],
+    );
+  });
+
+  it("does not infer Codex for custom OpenAI-compatible base URLs", () => {
+    const config = {
+      models: {
+        providers: {
+          openai: {
+            baseUrl: "https://openai-compatible.example.test/v1",
+            models: [],
+          },
+        },
+      },
+      agents: {
+        defaults: {
+          models: {
+            "openai/gpt-5.5": {},
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    expect(collectConfiguredAgentHarnessRuntimes(config, {}, { includeEnvRuntime: false })).toEqual(
+      [],
+    );
+  });
+
   it("ignores malformed agents.list while scanning best-effort config", () => {
     const config = {
       agents: {
diff --git a/src/agents/harness-runtimes.ts b/src/agents/harness-runtimes.ts
@@ -1,8 +1,7 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { normalizeOptionalLowercaseString } from "../shared/string-coerce.js";
 import { isRecord } from "../utils.js";
-import { resolveModelRuntimePolicy } from "./model-runtime-policy.js";
-import { modelSelectionShouldEnsureCodexPlugin } from "./openai-codex-routing.js";
+import { resolveAgentHarnessPolicy } from "./harness/policy.js";
 import { normalizeEmbeddedAgentRuntime } from "./pi-embedded-runner/runtime.js";
 import { normalizeProviderId } from "./provider-id.js";
 
@@ -38,6 +37,12 @@ function listAgentModelRefs(value: unknown): string[] {
   return refs;
 }
 
+function pushAgentModelRefs(refs: string[], value: unknown): void {
+  for (const ref of listAgentModelRefs(value)) {
+    refs.push(ref);
+  }
+}
+
 function parseConfiguredModelRef(
   value: unknown,
 ): { provider: string; modelId: string } | undefined {
@@ -55,21 +60,23 @@ function parseConfiguredModelRef(
   };
 }
 
-function hasOpenAIModelRef(config: OpenClawConfig, value: unknown, agentId?: string): boolean {
-  return listAgentModelRefs(value).some((ref) => {
-    if (!modelSelectionShouldEnsureCodexPlugin({ model: ref, config })) {
-      return false;
-    }
-    const parsed = parseConfiguredModelRef(ref);
-    const policy = resolveModelRuntimePolicy({
-      config,
-      provider: parsed?.provider,
-      modelId: parsed?.modelId,
-      agentId,
-    });
-    const runtime = normalizeRuntimeId(policy.policy?.id);
-    return !runtime || runtime === "auto" || runtime === "codex";
+function resolveConfiguredModelHarnessRuntime(params: {
+  config: OpenClawConfig;
+  modelRef: string;
+  agentId?: string;
+}): string | undefined {
+  const parsed = parseConfiguredModelRef(params.modelRef);
+  if (!parsed) {
+    return undefined;
+  }
+  const policy = resolveAgentHarnessPolicy({
+    config: params.config,
+    provider: parsed.provider,
+    modelId: parsed.modelId,
+    agentId: params.agentId,
   });
+  const runtime = normalizeRuntimeId(policy.runtime);
+  return runtime && runtime !== "auto" && runtime !== "pi" ? runtime : undefined;
 }
 
 function pushConfiguredModelRuntimeIds(config: OpenClawConfig, runtimes: Set<string>): void {
@@ -104,7 +111,44 @@ function pushConfiguredModelRuntimeIds(config: OpenClawConfig, runtimes: Set<str
   pushModelMapRuntimeIds(config.agents?.defaults?.models);
   const agents = Array.isArray(config.agents?.list) ? config.agents.list : [];
   for (const agent of agents) {
-    pushModelMapRuntimeIds(agent.models);
+    pushModelMapRuntimeIds(isRecord(agent) ? agent.models : undefined);
+  }
+}
+
+function pushConfiguredAgentModelRuntimeIds(config: OpenClawConfig, runtimes: Set<string>): void {
+  const pushModelRefs = (modelRefs: string[], agentId?: string) => {
+    for (const modelRef of modelRefs) {
+      const runtime = resolveConfiguredModelHarnessRuntime({ config, modelRef, agentId });
+      if (runtime) {
+        runtimes.add(runtime);
+      }
+    }
+  };
+  const pushModelMapRefs = (models: unknown, agentId?: string) => {
+    if (!isRecord(models)) {
+      return;
+    }
+    pushModelRefs(Object.keys(models), agentId);
+  };
+
+  const defaultsModel = config.agents?.defaults?.model;
+  const defaultsModelRefs: string[] = [];
+  pushAgentModelRefs(defaultsModelRefs, defaultsModel);
+  pushModelRefs(defaultsModelRefs);
+  pushModelMapRefs(config.agents?.defaults?.models);
+
+  if (!Array.isArray(config.agents?.list)) {
+    return;
+  }
+  for (const agent of config.agents.list) {
+    if (!isRecord(agent)) {
+      continue;
+    }
+    const agentId = typeof agent.id === "string" ? agent.id : undefined;
+    const selectedModelRefs: string[] = [];
+    pushAgentModelRefs(selectedModelRefs, agent.model ?? defaultsModel);
+    pushModelRefs(selectedModelRefs, agentId);
+    pushModelMapRefs(agent.models, agentId);
   }
 }
 
@@ -136,11 +180,6 @@ export function collectConfiguredAgentHarnessRuntimes(
   const runtimes = new Set<string>();
   const includeEnvRuntime = options.includeEnvRuntime ?? true;
   const includeLegacyAgentRuntimes = options.includeLegacyAgentRuntimes ?? true;
-  const pushCodexForOpenAIModel = (model: unknown, agentId?: string) => {
-    if (hasOpenAIModelRef(config, model, agentId)) {
-      runtimes.add("codex");
-    }
-  };
 
   if (includeEnvRuntime) {
     const envRuntime = normalizeRuntimeId(env.OPENCLAW_AGENT_RUNTIME);
@@ -152,19 +191,7 @@ export function collectConfiguredAgentHarnessRuntimes(
   if (includeLegacyAgentRuntimes) {
     pushLegacyAgentRuntimeIds(config, runtimes);
   }
-  const defaultsModel = config.agents?.defaults?.model;
-  pushCodexForOpenAIModel(defaultsModel);
-  if (Array.isArray(config.agents?.list)) {
-    for (const agent of config.agents.list) {
-      if (!isRecord(agent)) {
-        continue;
-      }
-      pushCodexForOpenAIModel(
-        agent.model ?? defaultsModel,
-        typeof agent.id === "string" ? agent.id : undefined,
-      );
-    }
-  }
+  pushConfiguredAgentModelRuntimeIds(config, runtimes);
 
   return [...runtimes].toSorted((left, right) => left.localeCompare(right));
 }
diff --git a/src/commands/doctor/shared/missing-configured-plugin-install.test.ts b/src/commands/doctor/shared/missing-configured-plugin-install.test.ts
@@ -1288,6 +1288,20 @@ describe("repairMissingConfiguredPluginInstalls", () => {
       },
       {},
     ],
+    [
+      "default selectable OpenAI agent model",
+      {
+        agents: {
+          defaults: {
+            model: { primary: "anthropic/claude-sonnet-4-6" },
+            models: {
+              "openai/gpt-5.5": {},
+            },
+          },
+        },
+      },
+      {},
+    ],
     [
       "agent model runtime policy",
       {
diff --git a/src/commands/doctor/shared/release-configured-plugin-installs.test.ts b/src/commands/doctor/shared/release-configured-plugin-installs.test.ts
@@ -202,6 +202,27 @@ describe("configured plugin install release step", () => {
     expect(result.channelIds).toStrictEqual([]);
   });
 
+  it("collects Codex from selectable OpenAI agent models even without integration discovery", async () => {
+    const { collectReleaseConfiguredPluginIds } =
+      await import("./release-configured-plugin-installs.js");
+    const result = collectReleaseConfiguredPluginIds({
+      cfg: {
+        agents: {
+          defaults: {
+            model: { primary: "anthropic/claude-sonnet-4-6" },
+            models: {
+              "openai/gpt-5.5": {},
+            },
+          },
+        },
+      },
+      env: {},
+    });
+
+    expect(result.pluginIds).toEqual(["codex"]);
+    expect(result.channelIds).toStrictEqual([]);
+  });
+
   it("collects external web search and ACP runtime plugins from config-only usage", async () => {
     const { collectReleaseConfiguredPluginIds } =
       await import("./release-configured-plugin-installs.js");
diff --git a/src/config/plugin-auto-enable.core.test.ts b/src/config/plugin-auto-enable.core.test.ts
@@ -675,6 +675,41 @@ describe("applyPluginAutoEnable core", () => {
     ]);
   });
 
+  it("auto-enables Codex when OpenAI is a selectable default agent model", () => {
+    const result = applyPluginAutoEnable({
+      config: {
+        agents: {
+          defaults: {
+            model: { primary: "anthropic/claude-sonnet-4-6" },
+            models: {
+              "openai/gpt-5.5": {},
+            },
+          },
+        },
+        plugins: {
+          allow: ["openai"],
+          entries: {
+            openai: { enabled: true },
+          },
+        },
+      },
+      env,
+      manifestRegistry: makeRegistry([
+        { id: "openai", channels: [], providers: ["openai", "openai-codex"] },
+        {
+          id: "codex",
+          channels: [],
+          providers: ["codex"],
+          activation: { onAgentHarnesses: ["codex"] },
+        },
+      ]),
+    });
+
+    expect(result.config.plugins?.entries?.codex?.enabled).toBe(true);
+    expect(result.config.plugins?.allow).toEqual(["openai", "codex"]);
+    expect(result.changes).toEqual(["codex agent runtime configured, enabled automatically."]);
+  });
+
   it("auto-enables an opt-in plugin when a provider runtime is configured", () => {
     const result = applyPluginAutoEnable({
       config: {
diff --git a/src/plugins/channel-plugin-ids.test.ts b/src/plugins/channel-plugin-ids.test.ts
@@ -1445,6 +1445,22 @@ describe("resolveGatewayStartupPluginIds", () => {
     });
   });
 
+  it("includes Codex when OpenAI is a selectable default agent model", () => {
+    expectStartupPluginIdsCase({
+      config: {
+        agents: {
+          defaults: {
+            model: { primary: "anthropic/claude-sonnet-4-6" },
+            models: {
+              "openai/gpt-5.5": {},
+            },
+          },
+        },
+      } as OpenClawConfig,
+      expected: ["demo-channel", "browser", "codex", "memory-core"],
+    });
+  });
+
   it("does not include Codex when an OpenAI model is manually pinned to PI", () => {
     expectStartupPluginIdsCase({
       config: {
