@openclaw/codex 2026.5.1-beta.1

package/src/commands.ts

@@ -0,0 +1,32 @@
+import type {
+  OpenClawPluginCommandDefinition,
+  PluginCommandContext,
+  PluginCommandResult,
+} from "openclaw/plugin-sdk/plugin-entry";
+import type { CodexCommandDeps } from "./command-handlers.js";
+
+export function createCodexCommand(options: {
+  pluginConfig?: unknown;
+  deps?: Partial<CodexCommandDeps>;
+}): OpenClawPluginCommandDefinition {
+  return {
+    name: "codex",
+    description: "Inspect and control the Codex app-server harness",
+    ownership: "reserved",
+    agentPromptGuidance: [
+      "Native Codex app-server plugin is available (`/codex ...`). For Codex bind/control/thread/resume/steer/stop requests, prefer `/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, and `/codex stop` over ACP.",
+      "Use ACP for Codex only when the user explicitly asks for ACP/acpx or wants to test the ACP path.",
+    ],
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: (ctx) => handleCodexCommand(ctx, options),
+  };
+}
+
+export async function handleCodexCommand(
+  ctx: PluginCommandContext,
+  options: { pluginConfig?: unknown; deps?: Partial<CodexCommandDeps> } = {},
+): Promise<PluginCommandResult> {
+  const { handleCodexSubcommand } = await import("./command-handlers.js");
+  return await handleCodexSubcommand(ctx, options);
+}

package/src/conversation-binding-data.ts

@@ -0,0 +1,72 @@
+import process from "node:process";
+import type { PluginConversationBinding } from "openclaw/plugin-sdk/plugin-entry";
+
+const BINDING_DATA_VERSION = 1;
+
+export type CodexConversationBindingData = {
+  kind: "codex-app-server-session";
+  version: 1;
+  sessionFile: string;
+  workspaceDir: string;
+};
+
+export function createCodexConversationBindingData(params: {
+  sessionFile: string;
+  workspaceDir: string;
+}): CodexConversationBindingData {
+  return {
+    kind: "codex-app-server-session",
+    version: BINDING_DATA_VERSION,
+    sessionFile: params.sessionFile,
+    workspaceDir: params.workspaceDir,
+  };
+}
+
+export function readCodexConversationBindingData(
+  binding: PluginConversationBinding | null | undefined,
+): CodexConversationBindingData | undefined {
+  const data = binding?.data;
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return undefined;
+  }
+  return readCodexConversationBindingDataRecord(data);
+}
+
+export function readCodexConversationBindingDataRecord(
+  data: Record<string, unknown>,
+): CodexConversationBindingData | undefined {
+  if (
+    data.kind !== "codex-app-server-session" ||
+    data.version !== BINDING_DATA_VERSION ||
+    typeof data.sessionFile !== "string" ||
+    !data.sessionFile.trim()
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "codex-app-server-session",
+    version: BINDING_DATA_VERSION,
+    sessionFile: data.sessionFile,
+    workspaceDir:
+      typeof data.workspaceDir === "string" && data.workspaceDir.trim()
+        ? data.workspaceDir
+        : process.cwd(),
+  };
+}
+
+export function resolveCodexDefaultWorkspaceDir(pluginConfig: unknown): string {
+  const appServer = readRecord(readRecord(pluginConfig)?.appServer);
+  const configured = readString(appServer, "defaultWorkspaceDir");
+  return configured ?? process.cwd();
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readString(record: Record<string, unknown> | undefined, key: string) {
+  const value = record?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/src/conversation-binding.test.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  handleCodexConversationBindingResolved,
+  handleCodexConversationInboundClaim,
+} from "./conversation-binding.js";
+
+let tempDir: string;
+
+describe("codex conversation binding", () => {
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-binding-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("clears the Codex app-server sidecar when a pending bind is denied", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const sidecar = `${sessionFile}.codex-app-server.json`;
+    await fs.writeFile(sidecar, JSON.stringify({ schemaVersion: 1, threadId: "thread-1" }));
+
+    await handleCodexConversationBindingResolved({
+      status: "denied",
+      decision: "deny",
+      request: {
+        data: {
+          kind: "codex-app-server-session",
+          version: 1,
+          sessionFile,
+          workspaceDir: tempDir,
+        },
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: "channel:1",
+        },
+      },
+    });
+
+    await expect(fs.stat(sidecar)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("consumes inbound bound messages when command authorization is absent", async () => {
+    const result = await handleCodexConversationInboundClaim(
+      {
+        content: "run this",
+        channel: "discord",
+        isGroup: true,
+      },
+      {
+        channelId: "discord",
+        pluginBinding: {
+          bindingId: "binding-1",
+          pluginId: "codex",
+          pluginRoot: tempDir,
+          channel: "discord",
+          accountId: "default",
+          conversationId: "channel-1",
+          boundAt: Date.now(),
+          data: {
+            kind: "codex-app-server-session",
+            version: 1,
+            sessionFile: path.join(tempDir, "session.jsonl"),
+            workspaceDir: tempDir,
+          },
+        },
+      },
+    );
+
+    expect(result).toEqual({ handled: true });
+  });
+});

package/src/conversation-binding.ts

@@ -0,0 +1,351 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type {
+  PluginConversationBindingResolvedEvent,
+  PluginHookInboundClaimContext,
+  PluginHookInboundClaimEvent,
+} from "openclaw/plugin-sdk/plugin-entry";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-payload";
+import { CODEX_CONTROL_METHODS } from "./app-server/capabilities.js";
+import {
+  codexSandboxPolicyForTurn,
+  resolveCodexAppServerRuntimeOptions,
+} from "./app-server/config.js";
+import {
+  type CodexThreadResumeResponse,
+  type CodexThreadStartResponse,
+  type CodexTurnStartResponse,
+  type JsonValue,
+} from "./app-server/protocol.js";
+import {
+  clearCodexAppServerBinding,
+  readCodexAppServerBinding,
+  writeCodexAppServerBinding,
+} from "./app-server/session-binding.js";
+import { getSharedCodexAppServerClient } from "./app-server/shared-client.js";
+import {
+  createCodexConversationBindingData,
+  readCodexConversationBindingData,
+  readCodexConversationBindingDataRecord,
+  resolveCodexDefaultWorkspaceDir,
+  type CodexConversationBindingData,
+} from "./conversation-binding-data.js";
+import { trackCodexConversationActiveTurn } from "./conversation-control.js";
+import { createCodexConversationTurnCollector } from "./conversation-turn-collector.js";
+import { buildCodexConversationTurnInput } from "./conversation-turn-input.js";
+
+const DEFAULT_BOUND_TURN_TIMEOUT_MS = 20 * 60_000;
+
+export {
+  readCodexConversationBindingData,
+  resolveCodexDefaultWorkspaceDir,
+} from "./conversation-binding-data.js";
+
+type CodexConversationRunOptions = {
+  pluginConfig?: unknown;
+  timeoutMs?: number;
+};
+
+type CodexConversationStartParams = {
+  pluginConfig?: unknown;
+  sessionFile: string;
+  workspaceDir?: string;
+  threadId?: string;
+  model?: string;
+  modelProvider?: string;
+};
+
+type BoundTurnResult = {
+  reply: ReplyPayload;
+};
+
+type CodexConversationGlobalState = {
+  queues: Map<string, Promise<void>>;
+};
+
+const CODEX_CONVERSATION_GLOBAL_STATE = Symbol.for("openclaw.codex.conversationBinding");
+
+function getGlobalState(): CodexConversationGlobalState {
+  const globalState = globalThis as typeof globalThis & {
+    [CODEX_CONVERSATION_GLOBAL_STATE]?: CodexConversationGlobalState;
+  };
+  globalState[CODEX_CONVERSATION_GLOBAL_STATE] ??= { queues: new Map() };
+  return globalState[CODEX_CONVERSATION_GLOBAL_STATE];
+}
+
+export async function startCodexConversationThread(
+  params: CodexConversationStartParams,
+): Promise<CodexConversationBindingData> {
+  const workspaceDir =
+    params.workspaceDir?.trim() || resolveCodexDefaultWorkspaceDir(params.pluginConfig);
+  if (params.threadId?.trim()) {
+    await attachExistingThread({
+      pluginConfig: params.pluginConfig,
+      sessionFile: params.sessionFile,
+      threadId: params.threadId.trim(),
+      workspaceDir,
+      model: params.model,
+      modelProvider: params.modelProvider,
+    });
+  } else {
+    await createThread({
+      pluginConfig: params.pluginConfig,
+      sessionFile: params.sessionFile,
+      workspaceDir,
+      model: params.model,
+      modelProvider: params.modelProvider,
+    });
+  }
+  return createCodexConversationBindingData({
+    sessionFile: params.sessionFile,
+    workspaceDir,
+  });
+}
+
+export async function handleCodexConversationInboundClaim(
+  event: PluginHookInboundClaimEvent,
+  ctx: PluginHookInboundClaimContext,
+  options: CodexConversationRunOptions = {},
+): Promise<{ handled: boolean; reply?: ReplyPayload } | undefined> {
+  const data = readCodexConversationBindingData(ctx.pluginBinding);
+  if (!data) {
+    return undefined;
+  }
+  if (event.commandAuthorized !== true) {
+    return { handled: true };
+  }
+  const prompt = (event.bodyForAgent ?? event.content ?? "").trim();
+  if (!prompt) {
+    return { handled: true };
+  }
+  try {
+    const result = await enqueueBoundTurn(data.sessionFile, () =>
+      runBoundTurn({
+        data,
+        prompt,
+        event,
+        pluginConfig: options.pluginConfig,
+        timeoutMs: options.timeoutMs,
+      }),
+    );
+    return { handled: true, reply: result.reply };
+  } catch (error) {
+    return {
+      handled: true,
+      reply: {
+        text: `Codex app-server turn failed: ${formatErrorMessage(error)}`,
+      },
+    };
+  }
+}
+
+export async function handleCodexConversationBindingResolved(
+  event: PluginConversationBindingResolvedEvent,
+): Promise<void> {
+  if (event.status !== "denied") {
+    return;
+  }
+  const data = readCodexConversationBindingDataRecord(event.request.data ?? {});
+  if (!data) {
+    return;
+  }
+  await clearCodexAppServerBinding(data.sessionFile);
+}
+
+async function attachExistingThread(params: {
+  pluginConfig?: unknown;
+  sessionFile: string;
+  threadId: string;
+  workspaceDir: string;
+  model?: string;
+  modelProvider?: string;
+}): Promise<void> {
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+  });
+  const response: CodexThreadResumeResponse = await client.request(
+    CODEX_CONTROL_METHODS.resumeThread,
+    {
+      threadId: params.threadId,
+      ...(params.model ? { model: params.model } : {}),
+      ...(params.modelProvider ? { modelProvider: params.modelProvider } : {}),
+      approvalPolicy: runtime.approvalPolicy,
+      approvalsReviewer: runtime.approvalsReviewer,
+      sandbox: runtime.sandbox,
+      ...(runtime.serviceTier ? { serviceTier: runtime.serviceTier } : {}),
+      persistExtendedHistory: true,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  const thread = response.thread;
+  await writeCodexAppServerBinding(params.sessionFile, {
+    threadId: thread.id,
+    cwd: thread.cwd ?? params.workspaceDir,
+    model: response.model ?? params.model,
+    modelProvider: response.modelProvider ?? params.modelProvider,
+    approvalPolicy: runtime.approvalPolicy,
+    sandbox: runtime.sandbox,
+    serviceTier: runtime.serviceTier,
+  });
+}
+
+async function createThread(params: {
+  pluginConfig?: unknown;
+  sessionFile: string;
+  workspaceDir: string;
+  model?: string;
+  modelProvider?: string;
+}): Promise<void> {
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+  });
+  const response: CodexThreadStartResponse = await client.request(
+    "thread/start",
+    {
+      cwd: params.workspaceDir,
+      ...(params.model ? { model: params.model } : {}),
+      ...(params.modelProvider ? { modelProvider: params.modelProvider } : {}),
+      approvalPolicy: runtime.approvalPolicy,
+      approvalsReviewer: runtime.approvalsReviewer,
+      sandbox: runtime.sandbox,
+      ...(runtime.serviceTier ? { serviceTier: runtime.serviceTier } : {}),
+      developerInstructions:
+        "This Codex thread is bound to an OpenClaw conversation. Answer normally; OpenClaw will deliver your final response back to the conversation.",
+      experimentalRawEvents: true,
+      persistExtendedHistory: true,
+    },
+    { timeoutMs: runtime.requestTimeoutMs },
+  );
+  await writeCodexAppServerBinding(params.sessionFile, {
+    threadId: response.thread.id,
+    cwd: response.thread.cwd ?? params.workspaceDir,
+    model: response.model ?? params.model,
+    modelProvider: response.modelProvider ?? params.modelProvider,
+    approvalPolicy: runtime.approvalPolicy,
+    sandbox: runtime.sandbox,
+    serviceTier: runtime.serviceTier,
+  });
+}
+
+async function runBoundTurn(params: {
+  data: CodexConversationBindingData;
+  prompt: string;
+  event: PluginHookInboundClaimEvent;
+  pluginConfig?: unknown;
+  timeoutMs?: number;
+}): Promise<BoundTurnResult> {
+  const runtime = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const binding = await readCodexAppServerBinding(params.data.sessionFile);
+  const threadId = binding?.threadId;
+  if (!threadId) {
+    throw new Error("bound Codex conversation has no thread binding");
+  }
+
+  const client = await getSharedCodexAppServerClient({
+    startOptions: runtime.start,
+    timeoutMs: runtime.requestTimeoutMs,
+    authProfileId: binding.authProfileId,
+  });
+  const collector = createCodexConversationTurnCollector(threadId);
+  const notificationCleanup = client.addNotificationHandler((notification) =>
+    collector.handleNotification(notification),
+  );
+  const requestCleanup = client.addRequestHandler(
+    async (request): Promise<JsonValue | undefined> => {
+      if (request.method === "item/tool/call") {
+        return {
+          contentItems: [
+            {
+              type: "inputText",
+              text: "OpenClaw native Codex conversation binding does not expose dynamic OpenClaw tools yet.",
+            },
+          ],
+          success: false,
+        };
+      }
+      if (
+        request.method === "item/commandExecution/requestApproval" ||
+        request.method === "item/fileChange/requestApproval"
+      ) {
+        return {
+          decision: "decline",
+          reason:
+            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
+        };
+      }
+      if (request.method === "item/permissions/requestApproval") {
+        return { permissions: {}, scope: "turn" };
+      }
+      if (request.method.includes("requestApproval")) {
+        return {
+          decision: "decline",
+          reason:
+            "OpenClaw native Codex conversation binding cannot route interactive approvals yet; use the Codex harness or explicit /acp spawn codex for that workflow.",
+        };
+      }
+      return undefined;
+    },
+  );
+  try {
+    const response: CodexTurnStartResponse = await client.request(
+      "turn/start",
+      {
+        threadId,
+        input: buildCodexConversationTurnInput({ prompt: params.prompt, event: params.event }),
+        cwd: binding.cwd || params.data.workspaceDir,
+        approvalPolicy: binding.approvalPolicy ?? runtime.approvalPolicy,
+        approvalsReviewer: runtime.approvalsReviewer,
+        sandboxPolicy: codexSandboxPolicyForTurn(
+          binding.sandbox ?? runtime.sandbox,
+          binding.cwd || params.data.workspaceDir,
+        ),
+        ...(binding.model ? { model: binding.model } : {}),
+        ...((binding.serviceTier ?? runtime.serviceTier)
+          ? { serviceTier: binding.serviceTier ?? runtime.serviceTier }
+          : {}),
+      },
+      { timeoutMs: runtime.requestTimeoutMs },
+    );
+    const turnId = response.turn.id;
+    const activeCleanup = trackCodexConversationActiveTurn({
+      sessionFile: params.data.sessionFile,
+      threadId,
+      turnId,
+    });
+    collector.setTurnId(turnId);
+    const completion = await collector
+      .wait({
+        timeoutMs: params.timeoutMs ?? DEFAULT_BOUND_TURN_TIMEOUT_MS,
+      })
+      .finally(activeCleanup);
+    const replyText = completion.replyText.trim();
+    return {
+      reply: {
+        text: replyText || "Codex completed without a text reply.",
+      },
+    };
+  } finally {
+    notificationCleanup();
+    requestCleanup();
+  }
+}
+
+function enqueueBoundTurn<T>(key: string, run: () => Promise<T>): Promise<T> {
+  const state = getGlobalState();
+  const previous = state.queues.get(key) ?? Promise.resolve();
+  const next = previous.then(run, run);
+  const queued = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  state.queues.set(key, queued);
+  void next.finally(() => {
+    if (state.queues.get(key) === queued) {
+      state.queues.delete(key);
+    }
+  });
+  return next;
+}

package/src/conversation-control.test.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  readCodexAppServerBinding,
+  writeCodexAppServerBinding,
+} from "./app-server/session-binding.js";
+import {
+  setCodexConversationFastMode,
+  setCodexConversationPermissions,
+} from "./conversation-control.js";
+
+let tempDir: string;
+
+describe("codex conversation controls", () => {
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-control-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("persists fast mode and permissions for later bound turns", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    await writeCodexAppServerBinding(sessionFile, {
+      threadId: "thread-1",
+      cwd: tempDir,
+      model: "gpt-5.4",
+      modelProvider: "openai",
+      approvalPolicy: "never",
+      sandbox: "danger-full-access",
+    });
+
+    await expect(setCodexConversationFastMode({ sessionFile, enabled: true })).resolves.toBe(
+      "Codex fast mode enabled.",
+    );
+    await expect(setCodexConversationPermissions({ sessionFile, mode: "default" })).resolves.toBe(
+      "Codex permissions set to default.",
+    );
+
+    await expect(readCodexAppServerBinding(sessionFile)).resolves.toMatchObject({
+      threadId: "thread-1",
+      serviceTier: "fast",
+      approvalPolicy: "on-request",
+      sandbox: "workspace-write",
+    });
+  });
+});