@openclaw/codex 2026.5.1-beta.1

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@openclaw/codex",
+  "version": "2026.5.1-beta.1",
+  "description": "OpenClaw Codex harness and model provider plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "0.71.1",
+    "@openai/codex": "0.128.0",
+    "ajv": "^8.20.0",
+    "ws": "^8.20.0",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@openclaw/codex",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.5.1-beta.1"
+    },
+    "bundle": {
+      "includeInCore": false
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.1-beta.1"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/prompt-overlay-runtime-contract.test.ts

@@ -0,0 +1,45 @@
+import {
+  codexPromptOverlayContext,
+  GPT5_CONTRACT_MODEL_ID,
+  NON_GPT5_CONTRACT_MODEL_ID,
+  sharedGpt5PersonalityConfig,
+} from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { describe, expect, it } from "vitest";
+import { buildCodexProvider } from "./provider.js";
+
+describe("Codex prompt overlay runtime contract", () => {
+  it("adds the shared GPT-5 behavior contract to Codex GPT-5 provider runs", () => {
+    const provider = buildCodexProvider();
+    const contribution = provider.resolveSystemPromptContribution?.(
+      codexPromptOverlayContext({ modelId: GPT5_CONTRACT_MODEL_ID }),
+    );
+
+    expect(contribution?.stablePrefix).toContain("<persona_latch>");
+    expect(contribution?.sectionOverrides?.interaction_style).toContain(
+      "This is a live chat, not a memo.",
+    );
+  });
+
+  it("respects shared GPT-5 prompt overlay config for Codex runs", () => {
+    const provider = buildCodexProvider();
+    const contribution = provider.resolveSystemPromptContribution?.(
+      codexPromptOverlayContext({
+        modelId: GPT5_CONTRACT_MODEL_ID,
+        config: sharedGpt5PersonalityConfig("off"),
+      }),
+    );
+
+    expect(contribution?.stablePrefix).toContain("<persona_latch>");
+    expect(contribution?.sectionOverrides).toEqual({});
+  });
+
+  it("does not add the shared GPT-5 overlay to non-GPT-5 Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    expect(
+      provider.resolveSystemPromptContribution?.(
+        codexPromptOverlayContext({ modelId: NON_GPT5_CONTRACT_MODEL_ID }),
+      ),
+    ).toBeUndefined();
+  });
+});

package/prompt-overlay.ts

@@ -0,0 +1,19 @@
+import {
+  GPT5_BEHAVIOR_CONTRACT,
+  renderGpt5PromptOverlay,
+  resolveGpt5SystemPromptContribution,
+} from "openclaw/plugin-sdk/provider-model-shared";
+
+export const CODEX_GPT5_BEHAVIOR_CONTRACT = GPT5_BEHAVIOR_CONTRACT;
+
+export function resolveCodexSystemPromptContribution(
+  params: Parameters<typeof resolveGpt5SystemPromptContribution>[0],
+) {
+  return resolveGpt5SystemPromptContribution(params);
+}
+
+export function renderCodexPromptOverlay(
+  params: Parameters<typeof renderGpt5PromptOverlay>[0],
+): string | undefined {
+  return renderGpt5PromptOverlay(params);
+}

package/provider-catalog.ts

@@ -0,0 +1,83 @@
+import type {
+  ModelDefinitionConfig,
+  ModelProviderConfig,
+} from "openclaw/plugin-sdk/provider-model-shared";
+import type { CodexAppServerModel } from "./src/app-server/models.js";
+
+export const CODEX_PROVIDER_ID = "codex";
+export const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+export const CODEX_APP_SERVER_AUTH_MARKER = "codex-app-server";
+
+const DEFAULT_CONTEXT_WINDOW = 272_000;
+const DEFAULT_MAX_TOKENS = 128_000;
+
+export const FALLBACK_CODEX_MODELS = [
+  {
+    id: "gpt-5.5",
+    model: "gpt-5.5",
+    displayName: "gpt-5.5",
+    description: "Latest frontier agentic coding model.",
+    isDefault: true,
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+  {
+    id: "gpt-5.4-mini",
+    model: "gpt-5.4-mini",
+    displayName: "GPT-5.4-Mini",
+    description: "Smaller frontier agentic coding model.",
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+  {
+    id: "gpt-5.2",
+    model: "gpt-5.2",
+    displayName: "gpt-5.2",
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+] satisfies CodexAppServerModel[];
+
+export function buildCodexModelDefinition(model: {
+  id: string;
+  model: string;
+  displayName?: string;
+  inputModalities: string[];
+  supportedReasoningEfforts: string[];
+}): ModelDefinitionConfig {
+  const id = model.id.trim() || model.model.trim();
+  return {
+    id,
+    name: model.displayName?.trim() || id,
+    api: "openai-codex-responses",
+    reasoning: model.supportedReasoningEfforts.length > 0 || shouldDefaultToReasoningModel(id),
+    input: model.inputModalities.includes("image") ? ["text", "image"] : ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: DEFAULT_CONTEXT_WINDOW,
+    maxTokens: DEFAULT_MAX_TOKENS,
+    compat: {
+      supportsReasoningEffort: model.supportedReasoningEfforts.length > 0,
+      supportsUsageInStreaming: true,
+    },
+  };
+}
+
+export function buildCodexProviderConfig(models: CodexAppServerModel[]): ModelProviderConfig {
+  return {
+    baseUrl: CODEX_BASE_URL,
+    apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+    auth: "token",
+    api: "openai-codex-responses",
+    models: models.map(buildCodexModelDefinition),
+  };
+}
+
+function shouldDefaultToReasoningModel(modelId: string): boolean {
+  const lower = modelId.toLowerCase();
+  return (
+    lower.startsWith("gpt-5") ||
+    lower.startsWith("o1") ||
+    lower.startsWith("o3") ||
+    lower.startsWith("o4")
+  );
+}

package/provider-discovery.ts

@@ -0,0 +1,45 @@
+import type { ProviderCatalogContext } from "openclaw/plugin-sdk/provider-catalog-shared";
+import type { ProviderPlugin } from "openclaw/plugin-sdk/provider-model-shared";
+import {
+  buildCodexProviderConfig,
+  CODEX_APP_SERVER_AUTH_MARKER,
+  CODEX_PROVIDER_ID,
+  FALLBACK_CODEX_MODELS,
+} from "./provider-catalog.js";
+
+function resolveCodexPluginConfig(ctx: ProviderCatalogContext): unknown {
+  return (ctx.config.plugins?.entries as Record<string, { config?: unknown } | undefined>)?.codex
+    ?.config;
+}
+
+async function runCodexCatalog(ctx: ProviderCatalogContext) {
+  const { buildCodexProviderCatalog } = await import("./provider.js");
+  return await buildCodexProviderCatalog({
+    env: ctx.env,
+    pluginConfig: resolveCodexPluginConfig(ctx),
+  });
+}
+
+export const codexProviderDiscovery: ProviderPlugin = {
+  id: CODEX_PROVIDER_ID,
+  label: "Codex",
+  docsPath: "/providers/models",
+  auth: [],
+  catalog: {
+    order: "late",
+    run: runCodexCatalog,
+  },
+  staticCatalog: {
+    order: "late",
+    run: async () => ({
+      provider: buildCodexProviderConfig(FALLBACK_CODEX_MODELS),
+    }),
+  },
+  resolveSyntheticAuth: () => ({
+    apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+    source: "codex-app-server",
+    mode: "token",
+  }),
+};
+
+export default codexProviderDiscovery;

package/provider.test.ts

@@ -0,0 +1,350 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CODEX_GPT5_BEHAVIOR_CONTRACT } from "./prompt-overlay.js";
+import { codexProviderDiscovery } from "./provider-discovery.js";
+import { buildCodexProvider, buildCodexProviderCatalog } from "./provider.js";
+import { CodexAppServerClient } from "./src/app-server/client.js";
+import {
+  getSharedCodexAppServerClient,
+  resetSharedCodexAppServerClientForTests,
+} from "./src/app-server/shared-client.js";
+
+afterEach(() => {
+  resetSharedCodexAppServerClientForTests();
+  vi.restoreAllMocks();
+});
+
+function expectStaticFallbackCatalog(
+  result: Awaited<ReturnType<typeof buildCodexProviderCatalog>>,
+) {
+  expect(result.provider.models.map((model) => model.id)).toEqual([
+    "gpt-5.5",
+    "gpt-5.4-mini",
+    "gpt-5.2",
+  ]);
+}
+
+function createFakeCodexClient(): CodexAppServerClient {
+  return {
+    initialize: vi.fn(async () => undefined),
+    request: vi.fn(async () => ({ data: [] })),
+    addCloseHandler: vi.fn(() => () => undefined),
+    close: vi.fn(),
+  } as unknown as CodexAppServerClient;
+}
+
+describe("codex provider", () => {
+  it("maps Codex app-server models to a Codex provider catalog", async () => {
+    const listModels = vi.fn(async () => ({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          displayName: "gpt-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+        },
+        {
+          id: "hidden-model",
+          model: "hidden-model",
+          hidden: true,
+          inputModalities: ["text"],
+          supportedReasoningEfforts: [],
+        },
+      ],
+    }));
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      pluginConfig: { discovery: { timeoutMs: 1234 } },
+    });
+
+    expect(listModels).toHaveBeenCalledWith(
+      expect.objectContaining({ limit: 100, timeoutMs: 1234, sharedClient: false }),
+    );
+    expect(result.provider).toMatchObject({
+      auth: "token",
+      api: "openai-codex-responses",
+      models: [
+        {
+          id: "gpt-5.4",
+          name: "gpt-5.4",
+          reasoning: true,
+          input: ["text", "image"],
+          compat: { supportsReasoningEffort: true },
+        },
+      ],
+    });
+  });
+
+  it("keeps a static fallback catalog when discovery is disabled", async () => {
+    const listModels = vi.fn();
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      pluginConfig: { discovery: { enabled: false } },
+    });
+
+    expect(listModels).not.toHaveBeenCalled();
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("uses live plugin config to re-enable discovery after startup disable", async () => {
+    const listModels = vi.fn(async () => ({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          displayName: "gpt-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+        },
+      ],
+    }));
+    const provider = buildCodexProvider({
+      pluginConfig: { discovery: { enabled: false } },
+      listModels,
+    });
+
+    const result = await provider.catalog?.run({
+      config: {
+        plugins: {
+          entries: {
+            codex: {
+              config: {
+                discovery: {
+                  enabled: true,
+                  timeoutMs: 4321,
+                },
+              },
+            },
+          },
+        },
+      },
+      env: {},
+    } as never);
+
+    expect(listModels).toHaveBeenCalledWith(
+      expect.objectContaining({ limit: 100, timeoutMs: 4321, sharedClient: false }),
+    );
+    expect(result).toMatchObject({
+      provider: {
+        models: [{ id: "gpt-5.4" }],
+      },
+    });
+  });
+
+  it("pages through live discovery before building the provider catalog", async () => {
+    const listModels = vi
+      .fn()
+      .mockResolvedValueOnce({
+        models: [
+          {
+            id: "gpt-5.4",
+            model: "gpt-5.4",
+            hidden: false,
+            inputModalities: ["text", "image"],
+            supportedReasoningEfforts: ["medium"],
+          },
+        ],
+        nextCursor: "page-2",
+      })
+      .mockResolvedValueOnce({
+        models: [
+          {
+            id: "gpt-5.2",
+            model: "gpt-5.2",
+            hidden: false,
+            inputModalities: ["text"],
+            supportedReasoningEfforts: [],
+          },
+        ],
+      });
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+    });
+
+    expect(listModels).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ cursor: undefined, limit: 100, sharedClient: false }),
+    );
+    expect(listModels).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ cursor: "page-2", limit: 100, sharedClient: false }),
+    );
+    expect(result.provider.models.map((model) => model.id)).toEqual(["gpt-5.4", "gpt-5.2"]);
+  });
+
+  it("reports discovery failures before using the fallback catalog", async () => {
+    const error = new Error("app-server down");
+    const onDiscoveryFailure = vi.fn();
+    const listModels = vi.fn(async () => {
+      throw error;
+    });
+
+    const result = await buildCodexProviderCatalog({
+      env: {},
+      listModels,
+      onDiscoveryFailure,
+    });
+
+    expect(onDiscoveryFailure).toHaveBeenCalledWith(error);
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("keeps a static fallback catalog when live discovery is explicitly disabled by env", async () => {
+    const listModels = vi.fn();
+
+    const result = await buildCodexProviderCatalog({
+      env: { OPENCLAW_CODEX_DISCOVERY_LIVE: "0" },
+      listModels,
+    });
+
+    expect(listModels).not.toHaveBeenCalled();
+    expectStaticFallbackCatalog(result);
+  });
+
+  it("closes the transient app-server client after live discovery", async () => {
+    const client = createFakeCodexClient();
+    vi.spyOn(CodexAppServerClient, "start").mockReturnValue(client);
+
+    await buildCodexProviderCatalog({
+      env: { OPENCLAW_CODEX_DISCOVERY_LIVE: "1" },
+    });
+
+    expect(client.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not close an active shared app-server client during live discovery", async () => {
+    const activeClient = createFakeCodexClient();
+    const discoveryClient = createFakeCodexClient();
+    vi.spyOn(CodexAppServerClient, "start")
+      .mockReturnValueOnce(activeClient)
+      .mockReturnValueOnce(discoveryClient);
+
+    await getSharedCodexAppServerClient({ timeoutMs: 1000 });
+    await buildCodexProviderCatalog({
+      env: { OPENCLAW_CODEX_DISCOVERY_LIVE: "1" },
+    });
+
+    expect(activeClient.close).not.toHaveBeenCalled();
+    expect(discoveryClient.close).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves arbitrary Codex app-server model ids as text-only until discovered", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: " custom-model ",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expect(model).toMatchObject({
+      id: "custom-model",
+      provider: "codex",
+      api: "openai-codex-responses",
+      baseUrl: "https://chatgpt.com/backend-api",
+      input: ["text"],
+    });
+  });
+
+  it("keeps fallback Codex app-server models image-capable", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: "gpt-5.5",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expect(model).toMatchObject({
+      id: "gpt-5.5",
+      input: ["text", "image"],
+    });
+  });
+
+  it("treats o4 ids as reasoning-capable Codex models", () => {
+    const provider = buildCodexProvider();
+
+    const model = provider.resolveDynamicModel?.({
+      provider: "codex",
+      modelId: "o4-mini",
+      modelRegistry: { find: () => null },
+    } as never);
+
+    expect(model).toMatchObject({
+      id: "o4-mini",
+      reasoning: true,
+      compat: { supportsReasoningEffort: true },
+    });
+    expect(
+      provider
+        .resolveThinkingProfile?.({ provider: "codex", modelId: "o4-mini" } as never)
+        ?.levels.some((level) => level.id === "xhigh"),
+    ).toBe(true);
+  });
+
+  it("declares synthetic auth because the harness owns Codex credentials", () => {
+    const provider = buildCodexProvider();
+
+    expect(provider.resolveSyntheticAuth?.({ provider: "codex" })).toEqual({
+      apiKey: "codex-app-server",
+      source: "codex-app-server",
+      mode: "token",
+    });
+  });
+
+  it("exposes a lightweight provider-discovery entry for model list/status", async () => {
+    expect(codexProviderDiscovery.id).toBe("codex");
+    expect(codexProviderDiscovery.resolveSyntheticAuth?.({ provider: "codex" })).toEqual({
+      apiKey: "codex-app-server",
+      source: "codex-app-server",
+      mode: "token",
+    });
+
+    const result = await codexProviderDiscovery.staticCatalog?.run({
+      config: {},
+      env: {},
+      agentDir: "/tmp/openclaw-agent",
+    } as never);
+
+    expect(
+      result && "provider" in result ? result.provider.models.map((model) => model.id) : [],
+    ).toEqual(["gpt-5.5", "gpt-5.4-mini", "gpt-5.2"]);
+  });
+
+  it("adds the GPT-5 prompt overlay to Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    expect(
+      provider.resolveSystemPromptContribution?.({
+        provider: "codex",
+        modelId: "gpt-5.4",
+      } as never),
+    ).toEqual({
+      stablePrefix: CODEX_GPT5_BEHAVIOR_CONTRACT,
+      sectionOverrides: {
+        interaction_style: expect.stringContaining(
+          "Quiet monitoring does not satisfy an explicit ongoing-work instruction.",
+        ),
+      },
+    });
+  });
+
+  it("does not add the GPT-5 prompt overlay to non-GPT-5 Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    expect(
+      provider.resolveSystemPromptContribution?.({
+        provider: "codex",
+        modelId: "o4-mini",
+      } as never),
+    ).toBeUndefined();
+  });
+});