openclaw - 💡(How to fix) Fix [Beta report] 2026.5.12-beta.1 upgrade: Codex runtime module resolution and OpenAI tool schema failures

Summary

Sanitized beta upgrade report for 2026.5.12-beta.1, tested on a macOS arm64 OpenClaw host using OpenAI via Codex OAuth only. This was a follow-up to the prior 2026.5.10-beta.1 model-routing report where openai-codex/gpt-* was rewritten to openai/gpt-* without a working OAuth route.

Upgrade result: package update succeeded from 2026.5.10-beta.1 to 2026.5.12-beta.1, gateway restarted on the new version, external channels were connected, and representative cron jobs remained recoverable. However, the OpenAI/Codex primary path is still not clean. The new migrated openai/gpt-5.5 + codex runtime fails with a module resolution error, and the fallback openai-codex/gpt-5.5 route currently fails OpenAI request validation because an injected tool schema is invalid. In both cases, the run succeeds only because Anthropic fallback catches it.

Severity-ranked findings

High: migrated openai/gpt-* Codex runtime fails with MODULE_NOT_FOUND

After the upgrade, doctor/update migrated the primary model to openai/gpt-5.5 and added model entries that route openai/gpt-* through the new codex agent runtime. A direct smoke test against the main agent returned status: ok, but only after falling back to Anthropic.

Sanitized fallback attempt:

provider: openai
model: gpt-5.5
code: MODULE_NOT_FOUND
error: Cannot find module '<global-openclaw>/dist/plugin-sdk/root-alias.cjs/codex-native-task-runtime'
Require stack:
- <state>/npm/node_modules/@openclaw/codex/dist/run-attempt-*.js

The installed package snapshot showed:

@openclaw/codex version: 2026.5.12-beta.1
peerDependency: openclaw >=2026.5.12-beta.1

Relevant file layout on disk:

<global-openclaw>/dist/plugin-sdk/root-alias.cjs
<global-openclaw>/dist/plugin-sdk/codex-native-task-runtime.js
<global-openclaw>/dist/plugin-sdk/codex-native-task-runtime.d.ts

So the runtime appears to be resolving root-alias.cjs/codex-native-task-runtime as though root-alias.cjs were a directory, but it is a file. This looks like a packaging/import-path regression in @openclaw/codex or the plugin SDK root-alias export shape.

Expected: the migrated openai/gpt-* route should run through the Codex OAuth runtime without falling back.

Actual: the primary route fails before model execution with MODULE_NOT_FOUND; the agent succeeds only through Anthropic fallback.

High: legacy openai-codex/gpt-* workaround now hits OpenAI tool-schema validation

To keep the host usable, the model config and cron payloads were restored to the previously working openai-codex/gpt-* route using the pi runtime. After restart, a direct smoke test again returned status: ok, but still only via Anthropic fallback.

Sanitized fallback attempt:

provider: openai-codex
model: gpt-5.5
status: 400
reason: format
error: Invalid schema for function '<memory-plugin-tool>': In context=('properties', 'entity_hints'), array schema missing items.

This suggests OpenAI-compatible tool schema validation is now catching a generated/injected tool definition with an array property that lacks items. The problem may be in the tool schema generator, the memory/GBrain plugin schema, or the OpenAI/Codex request-shaping layer. Either way, it blocks GPT primary execution on this install even after reverting to the prior model IDs.

Expected: all OpenAI-facing tool schemas should include valid JSON Schema for arrays, including items.

Actual: openai-codex/gpt-5.5 rejects the request before completion; fallback provider completes the run.

Medium: update still emits stale-binary warning during service restart

The package update itself completed successfully:

Before: 2026.5.10-beta.1
After: 2026.5.12-beta.1

During restart, the updater printed a stale-binary warning indicating that config was written by 2026.5.12-beta.1 while the command was still running 2026.5.10-beta.1. It then reported that the gateway already showed the updated version and skipped a redundant restart.

This did not prevent the gateway from coming up on 2026.5.12-beta.1, but it remains confusing in the update path and makes it harder for beta testers to know whether CLI, global install, and managed service are aligned.

Medium: update auto-installed @openclaw/codex, but config/doctor state is confusing

The updater installed missing configured plugin @openclaw/codex@beta and doctor reported:

codex agent runtime configured, enabled automatically.

However, the sanitized config inspection did not show a normal plugins.entries.codex entry, and plugins.allow was still restrictive without an explicit codex entry. Despite that, runtime routing attempted to use codex, so the actual activation path is not obvious from config alone.

This may be intended, but it makes the new runtime harder to debug. A clearer doctor/config explanation would help: whether codex is a special runtime plugin, whether it should appear in plugins.entries, and how allowlist restrictions apply to it.

Medium/Low: cron run --expect-final still appears to return before final completion

As observed in the previous beta report, manual cron verification remains awkward. Running a representative cron with --expect-final --timeout 180000 returned an enqueue-style response rather than a clear final agent completion. This makes beta testing cron model routing less deterministic.

Expected: --expect-final should either wait for the final run result or document that it only waits for enqueue/acceptance in some cases.

Low: plugin/update diagnostics remain noisy

The npm plugin update still prints repeated peer dependency relink lines. The Brave plugin still reports a manifest/package-name mismatch warning. plugins doctor reports no plugin issues but still emits:

plugin runtime config.loadConfig() is deprecated (runtime-config-load-write); use config.current().

These did not block the upgrade, but they add noise around the more serious runtime failures.

Low / not attributed to this beta

Post-upgrade diagnostics still include pre-existing/local hygiene items: restrictive plugin allowlist compatibility warning, message-tool allowlist warnings for routed channels, Telegram first-time setup policy warning, unavailable SecretRef in the doctor command path, orphan transcript files, bootstrap size near configured limit, and task audit warnings. These were observed during validation but are not clearly caused by 2026.5.12-beta.1.

Reproduction outline

1. Start from a macOS arm64 OpenClaw host on 2026.5.10-beta.1, using OpenAI through Codex OAuth only, with no direct OpenAI API key.
2. Run openclaw update --channel beta to install 2026.5.12-beta.1.
3. Observe successful package update and gateway restart on 2026.5.12-beta.1.
4. Inspect model routing: primary model is migrated to openai/gpt-5.5, with the new codex runtime selected for openai/gpt-* entries.
5. Run a direct agent smoke test such as openclaw agent --agent main --session-id <fresh> --message "Reply exactly: ..." --timeout 120 --json.
6. Observe the openai/gpt-5.5 primary route fail with MODULE_NOT_FOUND for <global-openclaw>/dist/plugin-sdk/root-alias.cjs/codex-native-task-runtime, then fallback provider succeeds.
7. Restore prior openai-codex/gpt-* model IDs and cron payloads as a workaround, restart gateway, and rerun the smoke test.
8. Observe the openai-codex/gpt-5.5 primary route fail with OpenAI 400 invalid tool schema: array property entity_hints missing items, then fallback provider succeeds.

Final tested state after local workaround

• Installed version: 2026.5.12-beta.1.
• Gateway: reachable and managed by LaunchAgent.
• External channels: connected in status checks.
• Representative cron jobs: ok, with payloads restored to openai-codex/gpt-5.5.
• Direct agent smoke: returns the expected text, but only after Anthropic fallback.
• GPT/OpenAI primary path: not healthy yet due to the two failures above.

Expected maintainer-facing fix direction

1. Fix the @openclaw/codex import/packaging path so openai/gpt-* can load codex-native-task-runtime correctly through the new Codex runtime.
2. Validate/sanitize OpenAI-facing tool schemas before dispatch. Array schemas should always include items, even for optional or loosely typed arrays.
3. Consider improving doctor output for the new codex runtime so users can tell whether openai/gpt-* is using Codex OAuth or direct OpenAI API-key auth, and whether fallback masked a primary-route failure.