fix(agents): fall back to pi when codex harness is unavailable

steipete · steipete · commit 8a994de672c4 · 2026-05-16T11:04:45.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,7 @@ Docs: https://docs.openclaw.ai
 - CLI/context engines: bootstrap and finalize non-legacy context engines for CLI turns while preserving transcript snapshots and deferred maintenance ownership. (#81869) Thanks @sahilsatralkar.
 - Telegram: persist polling updates through restart replay so queued same-topic messages resume in order instead of losing context after a gateway restart. (#82256) Thanks @VACInc.
 - Gateway/Gmail: abort in-flight Gmail watcher startup and hot-reload restarts before shutdown so reloads cannot spawn `gog serve` after the Gateway is closing. Thanks @frankekn.
+- Agents/Codex: fall back to the embedded PI runner when OpenAI's implicit Codex harness preference cannot find a registered Codex plugin, preventing OpenAI-compatible gateway requests from failing with an unregistered harness error. Fixes #82437.
 - MCP plugin tools: forward host MCP `tools/call` `AbortSignal` through `createPluginToolsMcpHandlers().callTool` into plugin `tool.execute`, so host cancellation actually cancels in-flight plugin tool calls instead of letting them run to completion. Fixes #82424. (#82443) Thanks @joshavant.
 - Plugins: accept `api.on("deactivate")` as a compatibility alias for `gateway_stop`, so external plugin cleanup handlers run on Gateway shutdown instead of being ignored as unknown hooks.
 - Media: ignore image MIME and filename hints when bytes sniff as generic containers, so zip/octet-stream payloads mislabeled as images do not become local image media or keep image file extensions when staged.
diff --git a/src/agents/harness/selection.test.ts b/src/agents/harness/selection.test.ts
@@ -210,6 +210,17 @@ describe("runAgentHarnessAttempt", () => {
     expect(piRunAttempt).not.toHaveBeenCalled();
   });
 
+  it("falls back to PI when the implicit OpenAI Codex harness is unavailable", async () => {
+    const result = await runAgentHarnessAttempt({
+      ...createAttemptParams(),
+      provider: "openai",
+      modelId: "gpt-5.4",
+    });
+
+    expect(result.sessionIdUsed).toBe("pi");
+    expect(piRunAttempt).toHaveBeenCalledTimes(1);
+  });
+
   it("honors explicit PI runtime for OpenAI agent model runs", async () => {
     const result = await runAgentHarnessAttempt({
       ...createAttemptParams(providerRuntimeConfig("openai", "pi")),
@@ -402,6 +413,10 @@ describe("selectAgentHarness", () => {
     );
   });
 
+  it("selects PI when the implicit OpenAI Codex harness is unavailable", () => {
+    expect(selectAgentHarness({ provider: "openai", modelId: "gpt-5.4" }).id).toBe("pi");
+  });
+
   it("ignores legacy agentRuntime as a runtime policy source", () => {
     const config = {
       agents: {
diff --git a/src/agents/harness/selection.ts b/src/agents/harness/selection.ts
@@ -33,6 +33,8 @@ type AgentHarnessSelectionDecision = {
   selectedReason:
     | "forced_pi"
     | "forced_plugin"
+    // Implicit Codex preference found no registered Codex harness, so PI handled the run.
+    | "implicit_plugin_unavailable_pi"
     // Auto mode chose a registered plugin harness that supports the provider/model.
     | "auto_plugin"
     // Auto mode found no supporting plugin harness, so PI handled the run.
@@ -109,6 +111,14 @@ function selectAgentHarnessDecision(params: {
         candidates: listHarnessCandidates(pluginHarnesses),
       });
     }
+    if (runtime === "codex" && policy.runtimeSource === "implicit") {
+      return buildSelectionDecision({
+        harness: piHarness,
+        policy,
+        selectedReason: "implicit_plugin_unavailable_pi",
+        candidates: listHarnessCandidates(pluginHarnesses),
+      });
+    }
     throw new Error(`Requested agent harness "${runtime}" is not registered.`);
   }
 
