fix(talk): diagnose invalid OpenAI realtime auth

BSG2000 · Copilot · BSG2000 · commit 95de98617524 · 2026-07-22T00:37:25.000+02:00
Detect keys that cannot be direct OpenAI Platform keys (Azure model keys, OpenAI-compatible proxy keys) before minting api.openai.com Realtime client secrets or opening direct Realtime websockets, and surface an actionable auth diagnostic. Preserves proxy-looking keys for custom OpenAI-compatible Realtime endpoints (azureEndpoint), Azure deployment auth failures, and the existing post-request client-secret rejection message. Adds OPENCLAW_OPENAI_REALTIME_ALLOW_UNVALIDATED_KEY escape hatch and docs.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/docs/nodes/talk.md b/docs/nodes/talk.md
@@ -117,6 +117,8 @@ Supported keys: `voice` / `voice_id` / `voiceId`, `model` / `model_id` / `modelI
 | `realtime.consultRouting`                | -                                          | `provider-direct` preserves the provider's direct reply when it skips `openclaw_agent_consult`; `force-agent-consult` routes finalized user transcripts through OpenClaw instead.                                                                                          |
 | `realtime.instructions`                  | -                                          | Appends provider-facing system instructions to OpenClaw's built-in realtime prompt (voice style/tone); the default `openclaw_agent_consult` guidance stays.                                                                                                                |
 
+`realtime.providers.openai.apiKey` must be a direct OpenAI Platform key for OpenAI Realtime against `api.openai.com`, not an Azure AI Foundry / Azure OpenAI model key or OpenAI-compatible proxy key. Use `gateway-relay` with `azureEndpoint` + `azureDeployment` for Azure Realtime, or an endpoint-only `azureEndpoint` for a custom OpenAI-compatible Realtime proxy. `OPENCLAW_OPENAI_REALTIME_ALLOW_UNVALIDATED_KEY` is an emergency override for unusual direct OpenAI Platform key formats that are incorrectly rejected before an `api.openai.com` Realtime request; prefer fixing the configured auth path instead of leaving this enabled.
+
 `talk.catalog` exposes canonical provider ids and registry aliases, each provider's valid modes/transports/brain strategies/realtime audio formats/capability flags, and the runtime-selected readiness result. First-party Talk clients should read that catalog instead of maintaining provider aliases locally; treat an older Gateway that omits group readiness as unverified rather than definitively unconfigured. Streaming transcription providers are discovered through `talk.catalog.transcription`; the current Gateway relay uses the Voice Call streaming provider config until a dedicated Talk transcription config surface ships.
 
 ## macOS UI
diff --git a/docs/providers/openai.md b/docs/providers/openai.md
@@ -792,6 +792,20 @@ compatibility fallback when the shared
 
     ```json5
     {
+    <Note>
+    OpenAI Realtime Talk auth is not shared with Azure AI Foundry or Azure
+    OpenAI model providers. Browser WebRTC sessions and native OpenAI backend
+    bridges need a direct OpenAI Platform API key; OpenAI-compatible proxy keys are not valid for the
+    `api.openai.com` Realtime client-secret flow. Azure Realtime voice uses the
+    backend `gateway-relay` path with `azureEndpoint` and `azureDeployment`.
+    Endpoint-only `azureEndpoint` configs remain available for custom
+    OpenAI-compatible Realtime proxies. If an unusual direct OpenAI Platform key
+    format is incorrectly rejected before an `api.openai.com` Realtime request,
+    `OPENCLAW_OPENAI_REALTIME_ALLOW_UNVALIDATED_KEY=1` bypasses the local key
+    shape check; prefer fixing the configured auth path instead of leaving that
+    override enabled.
+    </Note>
+
       tools: {
         media: {
           audio: {
diff --git a/extensions/openai/realtime-voice-provider.test.ts b/extensions/openai/realtime-voice-provider.test.ts
@@ -232,6 +232,35 @@ function requireFetchJsonBody(callIndex = 0): Record<string, unknown> {
   return requireRecord(JSON.parse(body as string), "fetch JSON body");
 }
 
+function expectDirectOpenAIRealtimeAuthMessage(error: unknown, unexpectedSecret?: string): void {
+  const message = error instanceof Error ? error.message : String(error);
+  expect(message).toContain(
+    "OpenAI Realtime voice provider 'openai' requires a direct OpenAI Platform API key",
+  );
+  expect(message).toContain("Azure AI Foundry / Azure OpenAI model credentials");
+  expect(message).toContain("OpenAI-compatible proxy keys");
+  expect(message).toContain("surface-specific provider apiKey");
+  if (unexpectedSecret) {
+    expect(message).not.toContain(unexpectedSecret);
+  }
+  if (error instanceof Error) {
+    expect(error.cause).toBeUndefined();
+  }
+}
+
+async function expectRejectsDirectOpenAIRealtimeAuth(
+  promise: Promise<unknown>,
+  unexpectedSecret?: string,
+): Promise<void> {
+  try {
+    await promise;
+  } catch (error) {
+    expectDirectOpenAIRealtimeAuthMessage(error, unexpectedSecret);
+    return;
+  }
+  throw new Error("Expected OpenAI Realtime direct auth diagnostic");
+}
+
 function requireSession(socket: FakeWebSocketInstance, index = 0): Record<string, unknown> {
   return requireRecord(parseSent(socket)[index]?.session, "session");
 }
@@ -490,6 +519,52 @@ describe("buildOpenAIRealtimeVoiceProvider", () => {
     expect(FakeWebSocket.instances).toHaveLength(0);
   });
 
+  it("preserves configured proxy-looking keys for custom realtime endpoints", () => {
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    const bridge = provider.createBridge({
+      providerConfig: {
+        apiKey: "sk-litellm-custom-endpoint-key", // pragma: allowlist secret
+        azureEndpoint: "https://realtime-proxy.example.com",
+        model: "gpt-realtime-2",
+      },
+      onAudio: vi.fn(),
+      onClearAudio: vi.fn(),
+    });
+
+    void bridge.connect();
+    bridge.close();
+
+    const socket = FakeWebSocket.instances[0];
+    expect(socket?.args[0]).toBe(
+      "wss://realtime-proxy.example.com/v1/realtime?model=gpt-realtime-2",
+    );
+    const options = socket?.args[1] as { headers?: Record<string, string> } | undefined;
+    expect(options?.headers?.Authorization).toBe("Bearer sk-litellm-custom-endpoint-key");
+  });
+
+  it("preserves env proxy-looking keys for custom realtime endpoints", () => {
+    vi.stubEnv("OPENAI_API_KEY", "sk-or-custom-endpoint-key"); // pragma: allowlist secret
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    const bridge = provider.createBridge({
+      providerConfig: {
+        azureEndpoint: "https://realtime-proxy.example.com",
+        model: "gpt-realtime-2",
+      },
+      onAudio: vi.fn(),
+      onClearAudio: vi.fn(),
+    });
+
+    void bridge.connect();
+    bridge.close();
+
+    const socket = FakeWebSocket.instances[0];
+    expect(socket?.args[0]).toBe(
+      "wss://realtime-proxy.example.com/v1/realtime?model=gpt-realtime-2",
+    );
+    const options = socket?.args[1] as { headers?: Record<string, string> } | undefined;
+    expect(options?.headers?.Authorization).toBe("Bearer sk-or-custom-endpoint-key");
+  });
+
   it("returns browser-safe OpenClaw attribution headers for native WebRTC offers", async () => {
     vi.stubEnv("OPENCLAW_VERSION", "2026.3.22");
     fetchWithSsrFGuardMock.mockResolvedValueOnce({
@@ -775,6 +850,119 @@ describe("buildOpenAIRealtimeVoiceProvider", () => {
     });
   });
 
+  it("rejects obvious proxy API keys before minting browser realtime client secrets", async () => {
+    const proxyKey = "sk-litellm-realtime-proxy-key"; // pragma: allowlist secret
+    vi.stubEnv("OPENAI_API_KEY", proxyKey);
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    if (!provider.createBrowserSession) {
+      throw new Error("expected OpenAI realtime provider to support browser sessions");
+    }
+
+    await expectRejectsDirectOpenAIRealtimeAuth(
+      provider.createBrowserSession({
+        cfg: {
+          models: {
+            providers: {
+              "azure-openai-responses": {
+                baseUrl: "https://example.services.ai.azure.com/models",
+                models: [],
+              },
+            },
+          },
+        } as never,
+        providerConfig: {},
+        instructions: "Be concise.",
+      }),
+      proxyKey,
+    );
+
+    expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects Azure-looking API keys before browser realtime client secret requests", async () => {
+    const azureKey = "0123456789abcdef0123456789abcdef"; // pragma: allowlist secret
+    vi.stubEnv("OPENAI_API_KEY", azureKey);
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    if (!provider.createBrowserSession) {
+      throw new Error("expected OpenAI realtime provider to support browser sessions");
+    }
+
+    await expectRejectsDirectOpenAIRealtimeAuth(
+      provider.createBrowserSession({
+        providerConfig: {},
+        instructions: "Be concise.",
+      }),
+      azureKey,
+    );
+
+    expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects configured proxy API keys before browser realtime client secret requests", async () => {
+    const configuredProxyKey = "sk-litel-configured-proxy-key"; // pragma: allowlist secret
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    if (!provider.createBrowserSession) {
+      throw new Error("expected OpenAI realtime provider to support browser sessions");
+    }
+
+    await expectRejectsDirectOpenAIRealtimeAuth(
+      provider.createBrowserSession({
+        providerConfig: { apiKey: configuredProxyKey },
+        instructions: "Be concise.",
+      }),
+      configuredProxyKey,
+    );
+
+    expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects keychain-resolved proxy API keys before browser realtime client secret requests", async () => {
+    const resolvedProxyKey = "sk-litellm-keychain-proxy-key"; // pragma: allowlist secret
+    vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_PROXY_TEST");
+    execFileSyncMock.mockReturnValueOnce(`${resolvedProxyKey}\n`);
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    if (!provider.createBrowserSession) {
+      throw new Error("expected OpenAI realtime provider to support browser sessions");
+    }
+
+    await expectRejectsDirectOpenAIRealtimeAuth(
+      provider.createBrowserSession({
+        providerConfig: {},
+        instructions: "Be concise.",
+      }),
+      resolvedProxyKey,
+    );
+
+    expect(fetchWithSsrFGuardMock).not.toHaveBeenCalled();
+  });
+
+  it("preserves non-auth 403 responses from realtime client secret requests", async () => {
+    const directLookingKey = "sk-test-direct-looking-valid-key"; // pragma: allowlist secret
+    fetchWithSsrFGuardMock.mockResolvedValueOnce({
+      response: createJsonResponse(
+        {
+          error: {
+            code: "model_access_denied",
+            message: "Project does not have access to the requested Realtime model.",
+          },
+        },
+        { status: 403 },
+      ),
+      release: vi.fn(async () => undefined),
+    });
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    if (!provider.createBrowserSession) {
+      throw new Error("expected OpenAI realtime provider to support browser sessions");
+    }
+
+    await expect(
+      provider.createBrowserSession({
+        providerConfig: { apiKey: directLookingKey },
+        instructions: "Be concise.",
+      }),
+    ).rejects.toThrow("OpenAI Realtime client secret failed (403)");
+  });
+
   it("fails closed when keychain refs cannot be resolved", async () => {
     vi.stubEnv("OPENAI_API_KEY", "keychain:openclaw:OPENAI_REALTIME_MISSING_TEST");
     resolveProviderAuthProfileApiKeyMock.mockResolvedValueOnce(undefined);
@@ -1243,6 +1431,38 @@ describe("buildOpenAIRealtimeVoiceProvider", () => {
     });
   });
 
+  it("preserves Azure deployment startup auth failures", async () => {
+    const provider = buildOpenAIRealtimeVoiceProvider();
+    const bridge = provider.createBridge({
+      providerConfig: {
+        apiKey: "sk-test", // pragma: allowlist secret
+        azureEndpoint: "https://example.openai.azure.com/",
+        azureDeployment: "realtime-prod",
+      },
+      onAudio: vi.fn(),
+      onClearAudio: vi.fn(),
+    });
+    const connecting = bridge.connect();
+    const socket = FakeWebSocket.instances[0];
+    if (!socket) {
+      throw new Error("expected bridge to create a websocket");
+    }
+
+    socket.emit("error", new Error("Unexpected server response: 401"));
+
+    try {
+      await connecting;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      expect(message).toContain("Unexpected server response: 401");
+      expect(message).not.toContain(
+        "OpenAI Realtime voice provider 'openai' requires a direct OpenAI Platform API key",
+      );
+      return;
+    }
+    throw new Error("Expected Azure realtime startup auth failure");
+  });
+
   it("rejects connection when session configuration fails before readiness", async () => {
     const provider = buildOpenAIRealtimeVoiceProvider();
     const bridge = provider.createBridge({
@@ -1310,7 +1530,7 @@ describe("buildOpenAIRealtimeVoiceProvider", () => {
       ),
     );
 
-    await expect(connecting).rejects.toThrow("Incorrect API key provided");
+    await expectRejectsDirectOpenAIRealtimeAuth(connecting);
     expect(onError).not.toHaveBeenCalled();
     expect(onClose).not.toHaveBeenCalled();
     expect(socket.closed).toBe(true);
@@ -1345,7 +1565,7 @@ describe("buildOpenAIRealtimeVoiceProvider", () => {
       ),
     );
 
-    await expect(failedConnect).rejects.toThrow("Incorrect API key provided");
+    await expectRejectsDirectOpenAIRealtimeAuth(failedConnect);
     expect(failedSocket.deferredClose).toBeDefined();
 
     const retryConnect = bridge.connect();
diff --git a/extensions/openai/realtime-voice-provider.ts b/extensions/openai/realtime-voice-provider.ts
