@openclaw/codex 2026.7.1 → 2026.7.2-beta.2

package/README.md

@@ -1,11 +1,35 @@
 # OpenClaw Codex
 
-Official OpenClaw provider and harness plugin for OpenAI Codex app-server integration. It exposes the Codex-managed GPT model catalog and the Codex runtime surfaces used by OpenClaw agents.
+Official OpenClaw plugin for OpenAI Codex app-server integration. It exposes the Codex-managed GPT model catalog, the Codex runtime surfaces used by OpenClaw agents, and opt-in supervision of native Codex sessions.
 
 Install from OpenClaw:
 
 ```bash
-openclaw plugin add @openclaw/codex
+openclaw plugins install @openclaw/codex
 ```
 
-Use this plugin when you want OpenClaw to run Codex-backed model turns, media understanding, and prompt overlays through the Codex app-server harness.
+Use this plugin when you want OpenClaw to run Codex-backed model turns, media understanding, and prompt overlays through the Codex app-server harness, or to browse non-archived Codex CLI, VS Code, Atlas, and ChatGPT sessions and paginated transcripts across paired computers.
+
+Guided onboarding attempts to install and enable supervision after it detects a native Codex installation and the selected inference backend passes its live check; Codex does not need to be the primary backend. Supervision activates when that opportunistic plugin setup succeeds. App Server availability is checked when supervision connects. An explicit Codex plugin disable, plugin-policy block, or `supervision.enabled: false` prevents opportunistic enablement. Manual setups enable `plugins.entries.codex.config.supervision.enabled`. Without explicit App Server connection settings, supervision uses a managed user-home stdio connection; explicit `appServer` settings are honored.
+
+The Gateway-backed operator CLI is:
+
+```bash
+openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
+openclaw codex continue <thread-id> [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
+openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]
+```
+
+The catalog never includes archived threads and has no archived or include-archived option. Rows appear in the normal Control UI sessions sidebar and open in the normal Chat pane. Transcript history requires a recent Codex App Server with `thread/turns/list` and is fetched 20 full-item turns at a time through opaque cursors; OpenClaw does not fall back to an unbounded `thread/read`, and rejects a serialized transcript page above 20 MiB before transport. `--limit` defaults to 50 sessions per host, `--cursor` requires `--host`, and the sessions Gateway timeout defaults to 75,000 ms so cold paired-node catalogs can complete. Continue and archive retain the shared 30,000 ms default. All operator surfaces require `operator.write`. Paired-node rows can be listed and read; continue and archive operate only on the Gateway-local host, and archive requires the no-other-runner confirmation. Catalog registration does not require `supervision.enabled`; that setting gates agent-facing supervision tools.
+
+A supervised OpenClaw Chat cannot be deleted while its model-selection lock protects the native binding. Before native archive, OpenClaw checks the exact target and every non-archived spawned descendant reported by Codex; any active OpenClaw binding blocks the operation. Descendant pagination errors, cycles, and safety-limit exhaustion also fail closed. Codex still does not expose a conditional archive operation or cross-process runner lease, so the confirmation covers unknown native clients and the race between the status read and archive request.
+
+Disabling or uninstalling the plugin leaves supervised Chats locked and unavailable rather than rerouting them. Reinstall or re-enable the same plugin and restart the Gateway to resume those Chats.
+
+These shell commands differ from the in-chat `/codex` runtime commands. In particular, `/codex sessions --host <node>` lists Codex CLI session files on one node, `/codex threads` uses the current conversation's App Server connection, and `/codex resume` or `/codex bind` changes that conversation's binding. There is no `/codex archive` runtime command.
+
+For a supervised branch, Codex App Server selects the snapshot fork's model and provider from its current native configuration. OpenClaw starts the canonical harness thread with exactly that returned pair. Codex persists the canonical thread's native selection, and later resumes preserve it because OpenClaw omits model and provider overrides. OpenClaw cannot substitute its outer runtime, model, or fallback. The returned initial pair can differ from the source's last recorded model.
+
+The visible-history mirror keeps at most 200 user or assistant messages, 512 KiB total, and 64 KiB per message. Image inputs become `[Image attachment]`; image data and local paths are not copied.
+
+See the [Codex harness](https://docs.openclaw.ai/plugins/codex-harness) and [Codex supervision](https://docs.openclaw.ai/plugins/codex-supervision) guides.

package/dist/app-server-policy-Scc-Wevo.js

@@ -0,0 +1,49 @@
+import { p as canUseCodexModelBackedApprovalsReviewerForModel } from "./session-binding-h1mmCGnl.js";
+//#region extensions/codex/src/app-server/app-server-policy.ts
+/**
+* Policy promotion for Codex app-server runs that can safely use OpenClaw tool
+* approvals.
+*/
+/**
+* Promotes implicit `never` approval policy to `untrusted` only when runtime
+* requirements allow OpenClaw to handle tool approvals.
+*/
+function resolveCodexAppServerForOpenClawToolPolicy(params) {
+	if (!params.shouldPromote || !params.canUseUntrustedApprovalPolicy || params.appServer.approvalPolicy !== "never") return params.appServer;
+	const explicitMode = params.execPolicy?.mode === "full" || params.pluginConfig.appServer?.mode !== void 0 || isCodexAppServerPolicyMode(params.env.OPENCLAW_CODEX_APP_SERVER_MODE);
+	const explicitApprovalPolicy = params.pluginConfig.appServer?.approvalPolicy !== void 0 || isConfiguredCodexAppServerApprovalPolicy(params.env.OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY) || params.appServer.approvalPolicySource === "requirements";
+	if (explicitMode || explicitApprovalPolicy) return params.appServer;
+	return {
+		...params.appServer,
+		approvalPolicy: "untrusted"
+	};
+}
+function resolveCodexAppServerForModelProvider(params) {
+	const explicitProvider = normalizeModelBackedReviewerProvider(params.provider);
+	if (!isCodexModelBackedApprovalsReviewer(params.appServer.approvalsReviewer) || canUseCodexModelBackedApprovalsReviewerForModel({
+		modelProvider: explicitProvider,
+		model: params.model,
+		config: params.config,
+		env: params.env,
+		agentDir: params.agentDir,
+		codexConfigToml: params.codexConfigToml
+	})) return params.appServer;
+	return {
+		...params.appServer,
+		approvalsReviewer: "user"
+	};
+}
+function isCodexAppServerPolicyMode(value) {
+	return value === "guardian" || value === "yolo";
+}
+function isConfiguredCodexAppServerApprovalPolicy(value) {
+	return value === "never" || value === "on-request" || value === "on-failure" || value === "untrusted";
+}
+function isCodexModelBackedApprovalsReviewer(value) {
+	return value === "auto_review" || value === "guardian_subagent";
+}
+function normalizeModelBackedReviewerProvider(provider) {
+	return provider?.trim().toLowerCase() || void 0;
+}
+//#endregion
+export { resolveCodexAppServerForOpenClawToolPolicy as n, resolveCodexAppServerForModelProvider as t };

package/dist/{attempt-notifications-BGsEIIDI.js → attempt-notifications-BFmNhqFl.js}

@@ -1,4 +1,4 @@
-import { r as isJsonObject } from "./protocol-2POPqAY4.js";
+import { Z as isJsonObject } from "./shared-client-JiAnW6pc.js";
 import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
 //#region extensions/codex/src/app-server/attempt-notifications.ts
 /**
@@ -6,8 +6,6 @@ import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
 */
 const CODEX_TURN_ABORT_MARKER_START = "<turn_aborted>";
 const CODEX_TURN_ABORT_MARKER_END = "</turn_aborted>";
-const CODEX_INTERRUPTED_USER_GUIDANCE = "The user interrupted the previous turn on purpose. Any running unified exec processes may still be running in the background. If any tools/commands were aborted, they may have partially executed.";
-const CODEX_INTERRUPTED_DEVELOPER_GUIDANCE = "The previous turn was interrupted on purpose. Any running unified exec processes may still be running in the background. If any tools/commands were aborted, they may have partially executed.";
 /** Builds compact activity metadata for watchdog and diagnostic updates. */
 function describeNotificationActivity(notification) {
 	if (!isJsonObject(notification.params)) return { lastNotificationMethod: notification.method };
@@ -182,12 +180,11 @@ function isCodexTurnAbortMarkerNotification(notification, options = {}) {
 	if (notification.method !== "rawResponseItem/completed" || !isJsonObject(notification.params)) return false;
 	const item = notification.params.item;
 	const role = isJsonObject(item) ? readString(item, "role") : void 0;
-	if (!isJsonObject(item) || role !== "user" && role !== "developer") return false;
+	if (!isJsonObject(item) || readString(item, "type") !== "message" || role !== "user" && role !== "developer") return false;
 	const text = extractRawResponseItemText(item).trim();
 	const currentPromptTexts = [options.currentPromptText, ...options.currentPromptTexts ?? []].filter(isNonEmptyString).map((prompt) => prompt.trim());
 	if (role === "user" && currentPromptTexts.includes(text)) return false;
-	const markerBody = readCodexTurnAbortMarkerBody(text);
-	return markerBody === CODEX_INTERRUPTED_USER_GUIDANCE || markerBody === CODEX_INTERRUPTED_DEVELOPER_GUIDANCE;
+	return readCodexTurnAbortMarkerBody(text) !== void 0;
 }
 function readCodexTurnAbortMarkerBody(text) {
 	if (!text.startsWith(CODEX_TURN_ABORT_MARKER_START) || !text.endsWith(CODEX_TURN_ABORT_MARKER_END)) return;

package/dist/auth-binding-C1czuHPA.js

@@ -0,0 +1,62 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { resolveApiKeyForProfile } from "openclaw/plugin-sdk/agent-runtime";
+import { fingerprintResolvedAuthProfileCredential } from "openclaw/plugin-sdk/agent-harness-runtime";
+//#region extensions/codex/src/app-server/auth-binding.ts
+var auth_binding_exports = /* @__PURE__ */ __exportAll({
+	fingerprintCodexAppServerAuthBinding: () => fingerprintCodexAppServerAuthBinding,
+	prepareCodexAppServerAuthBinding: () => prepareCodexAppServerAuthBinding
+});
+function withMaterializedCredential(params) {
+	const store = structuredClone(params.store);
+	if (params.credential.type === "api_key") {
+		const { keyRef: _keyRef, ...credential } = params.credential;
+		store.profiles[params.profileId] = {
+			...credential,
+			key: params.value
+		};
+	} else if (params.credential.type === "token") {
+		const { tokenRef: _tokenRef, ...credential } = params.credential;
+		store.profiles[params.profileId] = {
+			...credential,
+			token: params.value
+		};
+	}
+	return store;
+}
+/** Resolves one forwarded profile once so attestation and execution share exact material. */
+async function prepareCodexAppServerAuthBinding(params) {
+	const credential = params.authProfileStore.profiles[params.authProfileId];
+	if (!credential || credential.type === "oauth") return;
+	const resolved = await resolveApiKeyForProfile({
+		cfg: params.config,
+		store: params.authProfileStore,
+		profileId: params.authProfileId,
+		agentDir: params.agentDir
+	});
+	if (!resolved?.apiKey) throw new Error(`Codex could not resolve auth profile "${params.authProfileId}".`);
+	const fingerprint = fingerprintResolvedAuthProfileCredential({
+		profileId: params.authProfileId,
+		credential,
+		resolvedAuth: {
+			apiKey: resolved.apiKey,
+			profileId: params.authProfileId,
+			source: `profile:${params.authProfileId}`,
+			mode: credential.type === "api_key" ? "api-key" : "token"
+		}
+	});
+	if (!fingerprint) throw new Error(`Codex could not attest auth profile "${params.authProfileId}".`);
+	return {
+		fingerprint,
+		authProfileStore: withMaterializedCredential({
+			store: params.authProfileStore,
+			profileId: params.authProfileId,
+			credential,
+			value: resolved.apiKey
+		})
+	};
+}
+async function fingerprintCodexAppServerAuthBinding(params) {
+	return (await prepareCodexAppServerAuthBinding(params))?.fingerprint;
+}
+//#endregion
+export { prepareCodexAppServerAuthBinding as n, auth_binding_exports as t };

package/dist/cli-metadata.js

@@ -0,0 +1,20 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+//#region extensions/codex/cli-metadata.ts
+function registerCodexCliMetadata(api) {
+	api.registerCli(async ({ program }) => {
+		const { registerCodexSessionCli } = await import("./session-cli-XsEuWb_C.js");
+		registerCodexSessionCli(program);
+	}, { descriptors: [{
+		name: "codex",
+		description: "Inspect and branch from Codex sessions through the Gateway",
+		hasSubcommands: true
+	}] });
+}
+var cli_metadata_default = definePluginEntry({
+	id: "codex",
+	name: "Codex",
+	description: "Codex app-server harness and native session supervision.",
+	register: registerCodexCliMetadata
+});
+//#endregion
+export { cli_metadata_default as default, registerCodexCliMetadata };

package/dist/{app-server-policy-C968Kgin.js → command-formatters-Dq9InZUK.js}

@@ -1,6 +1,36 @@
-import { r as isJsonObject } from "./protocol-2POPqAY4.js";
-import { n as canUseCodexModelBackedApprovalsReviewerForModel } from "./config-CYEDnLJ2.js";
-import { f as summarizeCodexAccountRateLimits, l as hasCodexRateLimitSnapshots, m as summarizeCodexRateLimits } from "./provider-zjPfx5Fs.js";
+import { R as CodexAppServerRpcError, Z as isJsonObject } from "./shared-client-JiAnW6pc.js";
+import { c as summarizeCodexRateLimits, o as summarizeCodexAccountRateLimits, r as hasCodexRateLimitSnapshots } from "./rate-limits-DyXaYAxU.js";
+//#region extensions/codex/src/app-server/capabilities.ts
+/**
+* Capability helpers for optional Codex app-server control-plane methods.
+*/
+/** Known app-server methods used by OpenClaw control surfaces. */
+const CODEX_CONTROL_METHODS = {
+	account: "account/read",
+	compact: "thread/compact/start",
+	feedback: "feedback/upload",
+	forkThread: "thread/fork",
+	listMcpServers: "mcpServerStatus/list",
+	listSkills: "skills/list",
+	listThreads: "thread/list",
+	listThreadTurns: "thread/turns/list",
+	readThread: "thread/read",
+	rateLimits: "account/rateLimits/read",
+	archiveThread: "thread/archive",
+	renameThread: "thread/name/set",
+	resumeThread: "thread/resume",
+	review: "review/start",
+	unarchiveThread: "thread/unarchive"
+};
+/** Formats unsupported control calls differently from ordinary RPC failures. */
+function describeControlFailure(error) {
+	if (isUnsupportedControlError(error)) return "unsupported by this Codex app-server";
+	return error instanceof Error ? error.message : String(error);
+}
+function isUnsupportedControlError(error) {
+	return error instanceof CodexAppServerRpcError && error.code === -32601;
+}
+//#endregion
 //#region extensions/codex/src/command-formatters.ts
 /** Formats the combined `/codex status` probe result. */
 function formatCodexStatus(probes) {
@@ -65,9 +95,14 @@ function formatAuthRowStatus(row) {
 function formatComputerUseStatus(status) {
 	const lines = [`Computer Use: ${status.ready ? "ready" : status.enabled ? "not ready" : "disabled"}`];
 	lines.push(`Plugin: ${formatCodexDisplayText(status.pluginName)} (${computerUsePluginState(status)})`);
+	lines.push(`Installation: ${formatCodexDisplayText(status.installation.status)} (${status.installation.ok ? "ok" : "not ok"})`);
 	lines.push(`MCP server: ${formatCodexDisplayText(status.mcpServerName)}${status.mcpServerAvailable ? ` (${status.tools.length} tools)` : " (unavailable)"}`);
+	lines.push(`Exposure: ${formatCodexDisplayText(status.exposure.status)} (${status.exposure.ok ? "ok" : "not ok"})`);
+	lines.push(`Live test: ${formatCodexDisplayText(status.liveTest.status)} (${status.liveTest.attempted ? `${status.liveTest.attempts} attempt${status.liveTest.attempts === 1 ? "" : "s"}, ${status.liveTest.timeoutMs}ms` : "not run"})`);
+	if (status.liveTest.retried || status.liveTest.repaired) lines.push(`Live test recovery: retried=${status.liveTest.retried ? "yes" : "no"}, repaired=${status.liveTest.repaired ? "yes" : "no"}`);
 	if (status.marketplaceName) lines.push(`Marketplace: ${formatCodexDisplayText(status.marketplaceName)}`);
 	if (status.tools.length > 0) lines.push(`Tools: ${status.tools.slice(0, 8).map(formatCodexDisplayText).join(", ")}`);
+	for (const warning of status.warnings) lines.push(`Warning: ${formatCodexDisplayText(warning)}`);
 	lines.push(formatCodexDisplayText(status.message));
 	return lines.join("\n");
 }
@@ -273,51 +308,4 @@ function readString(record, key) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
 //#endregion
-//#region extensions/codex/src/app-server/app-server-policy.ts
-/**
-* Policy promotion for Codex app-server runs that can safely use OpenClaw tool
-* approvals.
-*/
-/**
-* Promotes implicit `never` approval policy to `untrusted` only when runtime
-* requirements allow OpenClaw to handle tool approvals.
-*/
-function resolveCodexAppServerForOpenClawToolPolicy(params) {
-	if (!params.shouldPromote || !params.canUseUntrustedApprovalPolicy || params.appServer.approvalPolicy !== "never") return params.appServer;
-	const explicitMode = params.execPolicy?.mode === "full" || params.pluginConfig.appServer?.mode !== void 0 || isCodexAppServerPolicyMode(params.env.OPENCLAW_CODEX_APP_SERVER_MODE);
-	const explicitApprovalPolicy = params.pluginConfig.appServer?.approvalPolicy !== void 0 || isConfiguredCodexAppServerApprovalPolicy(params.env.OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY) || params.appServer.approvalPolicySource === "requirements";
-	if (explicitMode || explicitApprovalPolicy) return params.appServer;
-	return {
-		...params.appServer,
-		approvalPolicy: "untrusted"
-	};
-}
-function resolveCodexAppServerForModelProvider(params) {
-	const explicitProvider = normalizeModelBackedReviewerProvider(params.provider);
-	if (!isCodexModelBackedApprovalsReviewer(params.appServer.approvalsReviewer) || canUseCodexModelBackedApprovalsReviewerForModel({
-		modelProvider: explicitProvider,
-		model: params.model,
-		config: params.config,
-		env: params.env,
-		agentDir: params.agentDir,
-		codexConfigToml: params.codexConfigToml
-	})) return params.appServer;
-	return {
-		...params.appServer,
-		approvalsReviewer: "user"
-	};
-}
-function isCodexAppServerPolicyMode(value) {
-	return value === "guardian" || value === "yolo";
-}
-function isConfiguredCodexAppServerApprovalPolicy(value) {
-	return value === "never" || value === "on-request" || value === "on-failure" || value === "untrusted";
-}
-function isCodexModelBackedApprovalsReviewer(value) {
-	return value === "auto_review" || value === "guardian_subagent";
-}
-function normalizeModelBackedReviewerProvider(provider) {
-	return provider?.trim().toLowerCase() || void 0;
-}
-//#endregion
-export { formatCodexDisplayText as a, formatList as c, formatThreads as d, readString as f, formatAccount as i, formatModels as l, resolveCodexAppServerForOpenClawToolPolicy as n, formatCodexStatus as o, buildHelp as r, formatComputerUseStatus as s, resolveCodexAppServerForModelProvider as t, formatSkills as u };
+export { formatComputerUseStatus as a, formatSkills as c, CODEX_CONTROL_METHODS as d, describeControlFailure as f, formatCodexStatus as i, formatThreads as l, formatAccount as n, formatList as o, formatCodexDisplayText as r, formatModels as s, buildHelp as t, readString as u };