fix(codex): classify app-server auth refresh failures

vincentkoc · web-flow · commit 3b8ac38ae9ee · 2026-05-14T11:56:18.000+08:00
Classify Codex native/app-server auth refresh logout failures and preserve app-server relogin detail in RPC errors.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - iOS/chat: resize PhotosPicker image attachments to capped JPEGs before staging and sending, stripping source metadata and keeping oversized camera photos under the chat upload budget. Fixes #68524. Thanks @BunsDev.
+- Codex harness: classify native app-server token-refresh logout and relogin failures as authentication refresh errors, so users get re-authentication guidance instead of a raw runtime failure.
 - 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.
 - Agents: preserve source-reply delivery metadata when merging tool-returned media into the final reply, keeping message-tool-only replies deliverable and mirrored. Thanks @pashpashpash and @vincentkoc.
 - macOS/companion: require system TLS trust before pinning a first-use direct `wss://` gateway certificate and honor `gateway.remote.tlsFingerprint` as the explicit pin for remote node-mode sessions, so fresh endpoints fail closed when macOS cannot trust the certificate unless configured out of band. Fixes #50642. Thanks @BunsDev.
diff --git a/extensions/codex/src/app-server/client.test.ts b/extensions/codex/src/app-server/client.test.ts
@@ -127,6 +127,42 @@ describe("CodexAppServerClient", () => {
     await expect(request).rejects.toHaveProperty("message", "Method not found");
   });
 
+  it("surfaces relogin details from Codex app-server RPC errors", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+
+    const request = harness.client.request("thread/start", {});
+    const outbound = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    harness.send({
+      id: outbound.id,
+      error: {
+        code: -32602,
+        message: "failed to load configuration",
+        data: {
+          reason: "cloudRequirements",
+          errorCode: "Auth",
+          action: "relogin",
+          statusCode: 401,
+          detail:
+            "Your authentication session could not be refreshed automatically. Please log out and sign in again.",
+        },
+      },
+    });
+
+    await expect(request).rejects.toHaveProperty(
+      "message",
+      "failed to load configuration: Your authentication session could not be refreshed automatically. Please log out and sign in again.",
+    );
+    await expect(request).rejects.toHaveProperty("data", {
+      reason: "cloudRequirements",
+      errorCode: "Auth",
+      action: "relogin",
+      statusCode: 401,
+      detail:
+        "Your authentication session could not be refreshed automatically. Please log out and sign in again.",
+    });
+  });
+
   it("rejects timed-out requests and ignores late responses", async () => {
     vi.useFakeTimers();
     const harness = createClientHarness();
diff --git a/extensions/codex/src/app-server/client.ts b/extensions/codex/src/app-server/client.ts
@@ -42,13 +42,39 @@ export class CodexAppServerRpcError extends Error {
   readonly data?: JsonValue;
 
   constructor(error: { code?: number; message: string; data?: JsonValue }, method: string) {
-    super(error.message || `${method} failed`);
+    super(formatCodexAppServerRpcErrorMessage(error, method));
     this.name = "CodexAppServerRpcError";
     this.code = error.code;
     this.data = error.data;
   }
 }
 
+function formatCodexAppServerRpcErrorMessage(
+  error: { message: string; data?: JsonValue },
+  method: string,
+): string {
+  const message = error.message || `${method} failed`;
+  const detail = readCodexAppServerRpcReloginDetail(error.data);
+  return detail && !message.includes(detail) ? `${message}: ${detail}` : message;
+}
+
+function readCodexAppServerRpcReloginDetail(data: JsonValue | undefined): string | undefined {
+  const record = isJsonObject(data) ? data : undefined;
+  const nested = isJsonObject(record?.error) ? record.error : record;
+  if (!nested) {
+    return undefined;
+  }
+  const isRelogin =
+    nested.action === "relogin" ||
+    (nested.reason === "cloudRequirements" && nested.errorCode === "Auth");
+  const detail = typeof nested.detail === "string" ? nested.detail.trim() : "";
+  return isRelogin && detail ? detail : undefined;
+}
+
+function isJsonObject(value: unknown): value is { [key: string]: JsonValue } {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
 export function isCodexAppServerConnectionClosedError(error: unknown): boolean {
   if (!(error instanceof Error)) {
     return false;
diff --git a/src/agents/auth-profiles/oauth-refresh-failure.ts b/src/agents/auth-profiles/oauth-refresh-failure.ts
@@ -12,6 +12,15 @@ export type OAuthRefreshFailureReason =
 const OAUTH_REFRESH_FAILURE_PROVIDER_RE = /OAuth token refresh failed for ([^:]+):/i;
 const SAFE_PROVIDER_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
 
+function isOAuthRefreshFailureMessage(message: string): boolean {
+  const lower = message.toLowerCase();
+  return (
+    lower.includes("oauth token refresh failed") ||
+    lower.includes("access token could not be refreshed") ||
+    lower.includes("authentication session could not be refreshed automatically")
+  );
+}
+
 function extractOAuthRefreshFailureProvider(message: string): string | null {
   const provider = message.match(OAUTH_REFRESH_FAILURE_PROVIDER_RE)?.[1]?.trim();
   return provider && provider.length > 0 ? provider : null;
@@ -49,7 +58,7 @@ export function classifyOAuthRefreshFailure(message: string): {
   provider: string | null;
   reason: OAuthRefreshFailureReason | null;
 } | null {
-  if (!/oauth token refresh failed/i.test(message)) {
+  if (!isOAuthRefreshFailureMessage(message)) {
     return null;
   }
   return {
diff --git a/src/agents/pi-embedded-helpers.formatassistanterrortext.test.ts b/src/agents/pi-embedded-helpers.formatassistanterrortext.test.ts
@@ -281,6 +281,15 @@ describe("formatAssistantErrorText", () => {
     );
   });
 
+  it("returns an explicit re-authentication message for Codex app-server refresh failures", () => {
+    const msg = makeAssistantError(
+      "Your access token could not be refreshed because you have since logged out or signed in to another account. Please sign in again.",
+    );
+    expect(formatAssistantErrorText(msg)).toBe(
+      "Authentication refresh failed. Re-authenticate this provider and try again.",
+    );
+  });
+
   it("returns a contention-specific message for OAuth refresh lock timeouts", () => {
     const msg = makeAssistantError("file lock timeout for /tmp/openclaw-oauth-refresh.lock");
     expect(formatAssistantErrorText(msg)).toBe(
diff --git a/src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts b/src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts
@@ -1447,6 +1447,16 @@ describe("classifyProviderRuntimeFailureKind", () => {
         "OAuth token refresh failed for openai-codex: invalid_grant. Please try again or re-authenticate.",
       ),
     ).toBe("auth_refresh");
+    expect(
+      classifyProviderRuntimeFailureKind(
+        "Your access token could not be refreshed because you have since logged out or signed in to another account. Please sign in again.",
+      ),
+    ).toBe("auth_refresh");
+    expect(
+      classifyProviderRuntimeFailureKind(
+        "Your authentication session could not be refreshed automatically. Please log out and sign in again.",
+      ),
+    ).toBe("auth_refresh");
   });
 
   it("classifies OAuth refresh timeouts and lock contention distinctly", () => {
