feat(openai): add chat-latest model override

vincentkoc · web-flow · commit f2b01bb7b142 · 2026-05-07T03:09:16.000-07:00
Add openai/chat-latest as an explicit direct API-key OpenAI model override, document the moving alias, and normalize unsupported Responses text verbosity for that model.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ Docs: https://docs.openclaw.ai
 - Docs/iMessage: deprecate BlueBubbles for new OpenClaw setups, document the upstream server-release rationale, and point new iMessage deployments toward the native `imsg` path while keeping BlueBubbles as a supported legacy fallback.
 - Discord/voice: make voice capture less choppy by extending the default post-speech silence grace to 2.5s, add `voice.captureSilenceGraceMs` for noisy Discord sessions, and tighten the spoken-output prompt around live STT fragments. Thanks @vincentkoc.
 - Discord/streaming: default Discord replies to progress draft previews so tool/work activity appears in one edited Discord message unless `channels.discord.streaming.mode` is set to `off`.
+- OpenAI: support `openai/chat-latest` as an explicit direct API-key model override for trying the moving ChatGPT Instant API alias without changing the stable default model.
 - Plugins/install: add `npm-pack:<path.tgz>` installs so local npm pack artifacts run through the same managed npm-root install, lockfile verification, dependency scan, and install-record path as registry npm plugins.
 - Codex app-server: disarm the short post-tool completion watchdog after current-turn activity, expose `appServer.turnCompletionIdleTimeoutMs`, and include raw assistant item context in idle-timeout diagnostics so status-only post-tool stalls stop failing as idle. Fixes #77984. Thanks @roseware-dev and @rubencu.
 - Plugin skills/Windows: publish plugin-provided skill directories as junctions on Windows so standard users without Developer Mode can register plugin skills without symlink EPERM failures. Fixes #77958. (#77971) Thanks @hclsys and @jarro.
diff --git a/docs/providers/openai.md b/docs/providers/openai.md
@@ -32,6 +32,7 @@ changing config.
 | ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
 | ChatGPT/Codex subscription with native Codex runtime | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Recommended Codex setup for most users. Sign in with `openai-codex` auth. |
 | Direct API-key billing                               | `openai/gpt-5.5`                                 | Set `OPENAI_API_KEY` or run OpenAI API-key onboarding.                    |
+| Latest ChatGPT Instant API alias                     | `openai/chat-latest`                             | Direct API-key only. Moving alias for experiments, not the default.       |
 | ChatGPT/Codex subscription auth through PI           | `openai-codex/gpt-5.5`                           | Use only when you intentionally want the normal PI runner.                |
 | Image generation or editing                          | `openai/gpt-image-2`                             | Works with either `OPENAI_API_KEY` or OpenAI Codex OAuth.                 |
 | Transparent-background images                        | `openai/gpt-image-1.5`                           | Use `outputFormat=png` or `webp` and `openai.background=transparent`.     |
@@ -165,6 +166,23 @@ Choose your preferred auth method and follow the setup steps.
     }
     ```
 
+    To try ChatGPT's current Instant model from the OpenAI API, set the model
+    to `openai/chat-latest`:
+
+    ```json5
+    {
+      env: { OPENAI_API_KEY: "sk-..." },
+      agents: { defaults: { model: { primary: "openai/chat-latest" } } },
+    }
+    ```
+
+    `chat-latest` is a moving alias. OpenAI documents it as the latest Instant
+    model used in ChatGPT and recommends `gpt-5.5` for production API usage, so
+    keep `openai/gpt-5.5` as the stable default unless you explicitly want that
+    alias behavior. The alias currently accepts only `medium` text verbosity, so
+    OpenClaw normalizes incompatible OpenAI text-verbosity overrides for this
+    model.
+
     <Warning>
     OpenClaw does **not** expose `openai/gpt-5.3-codex-spark`. Live OpenAI API requests reject that model, and the current Codex catalog does not expose it either.
     </Warning>
diff --git a/extensions/openai/openai-provider.live.test.ts b/extensions/openai/openai-provider.live.test.ts
@@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest";
 import { buildOpenAIProvider } from "./openai-provider.js";
 
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
-const DEFAULT_LIVE_MODEL_IDS = ["gpt-5.5", "gpt-5.4-mini", "gpt-5.4-nano"] as const;
+const DEFAULT_LIVE_MODEL_IDS = ["chat-latest", "gpt-5.5", "gpt-5.4-mini", "gpt-5.4-nano"] as const;
 const liveEnabled = OPENAI_API_KEY.trim().length > 0 && process.env.OPENCLAW_LIVE_TEST === "1";
 const describeLive = liveEnabled ? describe : describe.skip;
 
@@ -16,6 +16,8 @@ type LiveModelCase = {
   cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
   contextWindow: number;
   maxTokens: number;
+  reasoning: boolean;
+  textVerbosity: "low" | "medium";
 };
 
 function findOpenAIModel(modelId: string): Model<Api> | null {
@@ -24,6 +26,17 @@ function findOpenAIModel(modelId: string): Model<Api> | null {
 
 function resolveLiveModelCase(modelId: string): LiveModelCase {
   switch (modelId) {
+    case "chat-latest":
+      return {
+        modelId,
+        templateId: "gpt-5.5",
+        templateName: "GPT-5.5",
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+        contextWindow: 400_000,
+        maxTokens: 128_000,
+        reasoning: false,
+        textVerbosity: "medium",
+      };
     case "gpt-5.5":
       return {
         modelId,
@@ -32,6 +45,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 5, output: 30, cacheRead: 0, cacheWrite: 0 },
         contextWindow: 1_000_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     case "gpt-5.5-pro":
       return {
@@ -41,6 +56,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 },
         contextWindow: 1_000_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     case "gpt-5.4":
       return {
@@ -50,6 +67,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 1.75, output: 14, cacheRead: 0.175, cacheWrite: 0 },
         contextWindow: 400_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     case "gpt-5.4-pro":
       return {
@@ -59,6 +78,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 21, output: 168, cacheRead: 0, cacheWrite: 0 },
         contextWindow: 400_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     case "gpt-5.4-mini":
       return {
@@ -68,6 +89,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 0.25, output: 2, cacheRead: 0.025, cacheWrite: 0 },
         contextWindow: 400_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     case "gpt-5.4-nano":
       return {
@@ -77,6 +100,8 @@ function resolveLiveModelCase(modelId: string): LiveModelCase {
         cost: { input: 0.05, output: 0.4, cacheRead: 0.005, cacheWrite: 0 },
         contextWindow: 400_000,
         maxTokens: 128_000,
+        reasoning: true,
+        textVerbosity: "low",
       };
     default:
       throw new Error(`Unsupported live OpenAI model: ${modelId}`);
@@ -113,7 +138,7 @@ describeLive("buildOpenAIProvider live", () => {
               provider: "openai",
               api: "openai-completions",
               baseUrl: "https://api.openai.com/v1",
-              reasoning: true,
+              reasoning: liveCase.reasoning,
               input: ["text", "image"],
               cost: liveCase.cost,
               contextWindow: liveCase.contextWindow,
@@ -146,6 +171,7 @@ describeLive("buildOpenAIProvider live", () => {
         id: liveCase.modelId,
         api: "openai-responses",
         baseUrl: "https://api.openai.com/v1",
+        reasoning: liveCase.reasoning,
       });
 
       const client = new OpenAI({
@@ -158,8 +184,8 @@ describeLive("buildOpenAIProvider live", () => {
         instructions: "Return exactly OK and no other text.",
         input: "Return exactly OK.",
         max_output_tokens: 64,
-        reasoning: { effort: "none" },
-        text: { verbosity: "low" },
+        ...(liveCase.reasoning ? { reasoning: { effort: "none" as const } } : {}),
+        text: { verbosity: liveCase.textVerbosity },
       });
 
       expect(response.output_text.trim()).toMatch(/^OK[.!]?$/);
diff --git a/extensions/openai/openai-provider.test.ts b/extensions/openai/openai-provider.test.ts
@@ -282,6 +282,60 @@ describe("buildOpenAIProvider", () => {
     });
   });
 
+  it("resolves chat-latest as an explicit direct API model override", () => {
+    const provider = buildOpenAIProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "openai",
+      modelId: "chat-latest",
+      modelRegistry: {
+        find: (_provider: string, id: string) =>
+          id === "gpt-5.5"
+            ? {
+                id,
+                name: "GPT-5.5",
+                provider: "openai",
+                api: "openai-responses",
+                baseUrl: "https://api.openai.com/v1",
+                reasoning: true,
+                input: ["text", "image"],
+                cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+                contextWindow: 1_050_000,
+                maxTokens: 128_000,
+              }
+            : null,
+      } as never,
+    });
+
+    expect(model).toMatchObject({
+      provider: "openai",
+      id: "chat-latest",
+      api: "openai-responses",
+      baseUrl: "https://api.openai.com/v1",
+      reasoning: false,
+      input: ["text", "image"],
+      contextWindow: 400_000,
+      maxTokens: 128_000,
+      cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    });
+
+    const fallback = provider.resolveDynamicModel?.({
+      provider: "openai",
+      modelId: "chat-latest",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expect(fallback).toMatchObject({
+      provider: "openai",
+      id: "chat-latest",
+      api: "openai-responses",
+      reasoning: false,
+      contextWindow: 400_000,
+      maxTokens: 128_000,
+      cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+    });
+  });
+
   it("leaves gpt-5.5 to Pi and resolves gpt-5.5-pro locally", () => {
     const provider = buildOpenAIProvider();
 
@@ -340,7 +394,7 @@ describe("buildOpenAIProvider", () => {
     });
   });
 
-  it("surfaces gpt-5.5 in xhigh without synthetic catalog metadata", () => {
+  it("keeps chat-latest and gpt-5.5 out of synthetic catalog metadata", () => {
     const provider = buildOpenAIProvider();
 
     expect(
@@ -363,6 +417,12 @@ describe("buildOpenAIProvider", () => {
         id: "gpt-5.5",
       }),
     );
+    expect(entries).not.toContainEqual(
+      expect.objectContaining({
+        provider: "openai",
+        id: "chat-latest",
+      }),
+    );
   });
 
   it("keeps modern live selection on OpenAI 5.2+ and current Codex models", () => {
@@ -387,6 +447,12 @@ describe("buildOpenAIProvider", () => {
         modelId: "gpt-5.4",
       } as never),
     ).toBe(true);
+    expect(
+      provider.isModernModelRef?.({
+        provider: "openai",
+        modelId: "chat-latest",
+      } as never),
+    ).toBe(true);
     expect(
       provider.isModernModelRef?.({
         provider: "openai",
@@ -521,6 +587,40 @@ describe("buildOpenAIProvider", () => {
     expect(result.payload.tools).toEqual([{ type: "web_search" }]);
   });
 
+  it("clamps chat-latest text verbosity to the only live-supported value", () => {
+    const provider = buildOpenAIProvider();
+    const wrap = provider.wrapStreamFn;
+    expect(wrap).toBeTypeOf("function");
+    if (!wrap) {
+      throw new Error("expected OpenAI wrapper");
+    }
+    const extraParams = provider.prepareExtraParams?.({
+      provider: "openai",
+      modelId: "chat-latest",
+      extraParams: {
+        textVerbosity: "low",
+      },
+    } as never);
+    const result = runWrappedPayloadCase({
+      wrap,
+      provider: "openai",
+      modelId: "chat-latest",
+      extraParams: extraParams ?? undefined,
+      model: {
+        api: "openai-responses",
+        provider: "openai",
+        id: "chat-latest",
+        baseUrl: "https://api.openai.com/v1",
+        contextWindow: 400_000,
+      } as Model<"openai-responses">,
+      payload: {
+        text: { verbosity: "high" },
+      },
+    });
+
+    expect(result.payload.text).toEqual({ verbosity: "medium" });
+  });
+
   it("uses native OpenAI web search instead of the managed web_search function", () => {
     const provider = buildOpenAIProvider();
     const wrap = provider.wrapStreamFn;
diff --git a/extensions/openai/openai-provider.ts b/extensions/openai/openai-provider.ts
@@ -23,6 +23,7 @@ import {
 import { resolveOpenAIThinkingProfile } from "./thinking-policy.js";
 
 const PROVIDER_ID = "openai";
+const OPENAI_CHAT_LATEST_MODEL_ID = "chat-latest";
 const OPENAI_GPT_55_MODEL_ID = "gpt-5.5";
 const OPENAI_GPT_55_PRO_MODEL_ID = "gpt-5.5-pro";
 const OPENAI_GPT_54_MODEL_ID = "gpt-5.4";
@@ -35,6 +36,7 @@ const OPENAI_GPT_54_PRO_CONTEXT_TOKENS = 1_050_000;
 const OPENAI_GPT_54_MINI_CONTEXT_TOKENS = 400_000;
 const OPENAI_GPT_54_NANO_CONTEXT_TOKENS = 400_000;
 const OPENAI_GPT_54_MAX_TOKENS = 128_000;
+const OPENAI_CHAT_LATEST_COST = { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 } as const;
 const OPENAI_GPT_55_PRO_COST = { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 } as const;
 const OPENAI_GPT_54_COST = { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 } as const;
 const OPENAI_GPT_54_PRO_COST = { input: 30, output: 180, cacheRead: 0, cacheWrite: 0 } as const;
@@ -60,7 +62,13 @@ const OPENAI_GPT_54_TEMPLATE_MODEL_IDS = ["gpt-5.2"] as const;
 const OPENAI_GPT_54_PRO_TEMPLATE_MODEL_IDS = ["gpt-5.2-pro", "gpt-5.2"] as const;
 const OPENAI_GPT_54_MINI_TEMPLATE_MODEL_IDS = ["gpt-5-mini"] as const;
 const OPENAI_GPT_54_NANO_TEMPLATE_MODEL_IDS = ["gpt-5-nano", "gpt-5-mini"] as const;
+const OPENAI_CHAT_LATEST_TEMPLATE_MODEL_IDS = [
+  OPENAI_GPT_55_MODEL_ID,
+  OPENAI_GPT_54_MODEL_ID,
+  "gpt-5.2",
+] as const;
 const OPENAI_MODERN_MODEL_IDS = [
+  OPENAI_CHAT_LATEST_MODEL_ID,
   OPENAI_GPT_55_MODEL_ID,
   OPENAI_GPT_55_PRO_MODEL_ID,
   OPENAI_GPT_54_MODEL_ID,
@@ -69,6 +77,7 @@ const OPENAI_MODERN_MODEL_IDS = [
   OPENAI_GPT_54_NANO_MODEL_ID,
   "gpt-5.2",
 ] as const;
+
 function shouldUseOpenAIResponsesTransport(params: {
   provider: string;
   api?: string | null;
@@ -106,7 +115,19 @@ function resolveOpenAIGptForwardCompatModel(ctx: ProviderResolveDynamicModelCont
   const lower = normalizeLowercaseStringOrEmpty(trimmedModelId);
   let templateIds: readonly string[];
   let patch: Partial<ProviderRuntimeModel>;
-  if (lower === OPENAI_GPT_55_PRO_MODEL_ID) {
+  if (lower === OPENAI_CHAT_LATEST_MODEL_ID) {
+    templateIds = OPENAI_CHAT_LATEST_TEMPLATE_MODEL_IDS;
+    patch = {
+      api: "openai-responses",
+      provider: PROVIDER_ID,
+      baseUrl: "https://api.openai.com/v1",
+      reasoning: false,
+      input: ["text", "image"],
+      cost: OPENAI_CHAT_LATEST_COST,
+      contextWindow: 400_000,
+      maxTokens: OPENAI_GPT_54_MAX_TOKENS,
+    };
+  } else if (lower === OPENAI_GPT_55_PRO_MODEL_ID) {
     templateIds = OPENAI_GPT_55_PRO_TEMPLATE_MODEL_IDS;
     patch = {
       api: "openai-responses",
@@ -182,7 +203,7 @@ function resolveOpenAIGptForwardCompatModel(ctx: ProviderResolveDynamicModelCont
       id: trimmedModelId,
       name: trimmedModelId,
       ...patch,
-      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      cost: patch.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
       contextWindow: patch.contextWindow ?? DEFAULT_CONTEXT_TOKENS,
       maxTokens: patch.maxTokens ?? DEFAULT_CONTEXT_TOKENS,
     } as ProviderRuntimeModel)
diff --git a/src/agents/pi-embedded-runner/openai-stream-wrappers.ts b/src/agents/pi-embedded-runner/openai-stream-wrappers.ts
