openclaw - 💡(How to fix) Fix [Beta report] 2026.5.9-beta.1 update findings: Codex OAuth model routing, harness registration, cron model migration, and update/runtime diagnostics

Summary

This is a consolidated beta test report for 2026.5.9-beta.1 after updating an existing macOS OpenClaw installation from the prior beta/stable line. The most important finding is in the Codex/OpenAI model routing path: after upgrade, an instance authenticated to OpenAI through Codex OAuth, not a direct OpenAI API key, ended up in a broken model/harness state where cron jobs and agent runs could fail due to a mix of model allowlist drift, missing Codex harness registration, and direct-OpenAI provider routing.

The system was recovered by routing OpenAI OAuth-backed jobs back through openai-codex/... model names while explicitly pinning the runtime to the working pi harness path. After that change, a fresh smoke test succeeded on provider=openai-codex, model=gpt-5.5, agentHarnessId=pi, with no fallback.

All host/user/IP/account-identifying details have been removed from this report. Paths and hostnames below are sanitized or generic.

Environment

• OpenClaw target version: 2026.5.9-beta.1
• Previous observed version before update: 2026.5.7
• OS: macOS 26.4.1 arm64
• Node: 25.9.0
• Install/update method: global OpenClaw install using the beta channel update flow
• Gateway mode: LaunchAgent service
• Auth mode for OpenAI: Codex OAuth/auth profile, not OPENAI_API_KEY
• Relevant auth profile shape: openai-codex:default [openai-codex/oauth]
• Relevant command used for update: openclaw update --channel beta

High-priority Codex/OpenAI OAuth harness issue

What happened

After upgrading to 2026.5.9-beta.1, the instance had a set of cron jobs and agent defaults that had previously used the Codex/OpenAI model naming family. During troubleshooting, direct openai/gpt-5.5 appeared in the allowlist while openai-codex/gpt-5.5 was rejected in at least one cron path, which made it look like jobs should be migrated to openai/gpt-5.5.

That migration was incorrect for this machine because OpenAI was authenticated through Codex OAuth, not through a direct OpenAI API key. Once cron/default models were pointed at openai/gpt-5.5, OpenClaw routed them as direct OpenAI provider calls and failed with an auth error.

Observed direct-provider failure:

FailoverError: No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth; OpenAI agent model runs use openai/gpt-* through the Codex runtime. Set OPENAI_API_KEY only for direct OpenAI API-key surfaces.

Before that, using the OpenAI/Codex family also exposed a harness registration failure in the beta:

Requested agent harness "codex" is not registered.

A fallback decision showed the primary OpenAI candidate failing on the missing harness and then succeeding on Anthropic:

model_fallback_decision
requestedProvider=openai
requestedModel=gpt-5.4-mini
candidateProvider=anthropic
candidateModel=claude-opus-4-7
fallbackStepFromModel=openai/gpt-5.4-mini
fallbackStepFromFailureDetail="Requested agent harness \"codex\" is not registered."

A separate fallback decision showed direct openai/gpt-5.5 failing because the system only had Codex OAuth, not an OpenAI API key:

model_fallback_decision
requestedProvider=openai
requestedModel=gpt-5.5
candidateProvider=openai
candidateModel=gpt-5.5
reason=auth
status=401
errorPreview="No API key found for provider \"openai\". You are authenticated with OpenAI Codex OAuth..."

Why this is confusing/problematic

There seem to be three model/runtime concepts crossing wires:

1. openai-codex/gpt-5.5 is the correct user-facing/provider route for Codex OAuth-backed OpenAI access.
2. openai/gpt-5.5 is in the allowlist, but on an OAuth-only machine it routes like direct OpenAI provider usage and requires OPENAI_API_KEY.
3. The Codex harness/runtime path appears to be expected for some OpenAI/Codex model usage, but in this beta the harness id codex was not registered, causing Requested agent harness "codex" is not registered.

This creates a recovery trap: the allowlist error encourages moving jobs from openai-codex/gpt-5.5 to openai/gpt-5.5, but that breaks OAuth-only installs. Conversely, staying on the Codex model family can trip the missing codex harness registration path unless the runtime is explicitly pinned to pi.

Initial failures observed

Cron failures included both timeout/fallback and allowlist rejection variants:

Cron job failed: FallbackSummaryError: All models failed (3): openai-codex/gpt-5.5: fetch failed (timeout) | anthropic/claude-opus-4-7: Connection error. (timeout) | anthropic/claude-sonnet-4-6: Connection error. (timeout)

cron payload.model 'openai-codex/gpt-5.5' rejected by agents.defaults.models allowlist: openai-codex/gpt-5.5 is not in [anthropic/..., openai/gpt-5.4-mini, openai/gpt-5.5, ...]

The timeout event may have been transient network/provider behavior, but the allowlist/model-name issue was deterministic once cron jobs fired with the rejected model name.

Effective workaround

The instance was recovered by doing the following:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.5",
        "fallbacks": [
          "anthropic/claude-opus-4-7",
          "anthropic/claude-sonnet-4-6"
        ]
      },
      "models": {
        "openai-codex/gpt-5.5": {
          "agentRuntime": { "id": "pi" }
        },
        "openai-codex/gpt-5.4-mini": {
          "agentRuntime": { "id": "pi" }
        }
      }
    },
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "openai-codex/gpt-5.5",
          "fallbacks": [
            "anthropic/claude-opus-4-7",
            "anthropic/claude-sonnet-4-6"
          ]
        },
        "models": {
          "openai-codex/gpt-5.5": {
            "agentRuntime": { "id": "pi" }
          }
        }
      },
      {
        "id": "cron",
        "model": {
          "primary": "openai-codex/gpt-5.5",
          "fallbacks": ["anthropic/claude-opus-4-7"]
        },
        "models": {
          "openai-codex/gpt-5.5": {
            "agentRuntime": { "id": "pi" }
          }
        }
      },
      {
        "id": "mini-cron",
        "model": {
          "primary": "openai-codex/gpt-5.4-mini",
          "fallbacks": ["github-copilot/claude-sonnet-4.6"]
        },
        "models": {
          "openai-codex/gpt-5.4-mini": {
            "agentRuntime": { "id": "pi" }
          }
        }
      }
    ]
  }
}

All cron jobs that had explicit openai/gpt-5.5 payload models were then migrated back to openai-codex/gpt-5.5.

Post-fix verification:

{
  "status": "ok",
  "provider": "openai-codex",
  "model": "gpt-5.5",
  "agentHarnessId": "pi",
  "executionTrace": {
    "winnerProvider": "openai-codex",
    "winnerModel": "gpt-5.5",
    "fallbackUsed": false
  },
  "requestShaping": {
    "authMode": "auth-profile"
  }
}

The two originally failing cron jobs later showed status=ok, lastError=null, failures=0, with model openai-codex/gpt-5.5.

Suggested fixes / review points for Codex harness owner

• Clarify and enforce the distinction between direct OpenAI API-key models and Codex OAuth-backed OpenAI models. On OAuth-only installs, openai/gpt-* should not be suggested as the fix for openai-codex/gpt-* unless there is a direct API key configured.
• If openai-codex/gpt-* is the right route for Codex OAuth, ensure it remains valid in agents.defaults.models allowlists during upgrade/migration.
• If agentRuntime.id = "codex" is expected to support this route, ensure the codex harness is registered in 2026.5.9-beta.1, or provide an explicit migration to a supported runtime.
• If pi is the intended runtime for OAuth-backed openai-codex/gpt-* in this release, auto-migrate existing configs or surface a targeted warning.
• Avoid fallback behavior that silently lands on Anthropic when the primary failure is a deterministic harness-registration or auth-routing error. The fallback is useful, but the root cause should remain prominent in cron status/UI.
• Add a doctor or config validate --deep check for incompatible combinations:
  • OAuth-only OpenAI auth + openai/gpt-* direct provider model
  • openai-codex/gpt-* model missing from allowlist
  • model configured to use agentRuntime.id=codex when the codex harness is not registered

Other beta update findings

1. Update/restart false-negative or stale status during beta update

During openclaw update --channel beta, restart/status output indicated a non-successful or uncertain restart state even though the LaunchAgent later came up healthy. This creates uncertainty during upgrade validation. A more explicit post-update service probe, with the actual running app version and gateway health, would reduce confusion.

2. WebSocket protocol mismatch during update probe

During the update/probe window, the CLI/client path saw a protocol mismatch similar to:

expected protocol 4, got 3
client=cli probe

This appears consistent with a newly updated CLI probing an older still-running gateway, or the gateway not yet restarted into the matching version. If this is expected during rolling restart, it would be helpful to classify it as transient and print a clear instruction/status rather than surfacing it as an opaque protocol mismatch.

3. Stale version messaging immediately after update

Update/status messaging briefly appeared to report stale version information during the transition. The later status --deep showed the correct beta version and healthy gateway. This may be only a sequencing issue, but it makes beta update validation harder.

4. PATH/install method confusion

The machine had OpenClaw available through a user-local/global install path, and update/status flows depended on the resolved binary path. The beta updater could be clearer about which executable is being updated, which one the LaunchAgent will run, and whether shell PATH resolves to the same binary.

5. Plugin dry-run output included -> unknown

Plugin update/dry-run output showed entries resolving to unknown in at least one path. It was not immediately clear whether this meant unknown current version, unknown target version, or an unresolved package/plugin source. This is likely harmless but confusing during beta validation.

6. Control UI/session history and session file warnings

A fresh explicit agent smoke-test session succeeded, but the lossless/session checkpoint path warned about a missing session file:

afterTurn: bootstrap checkpoint refresh failed ... ENOENT: no such file or directory, stat '<sanitized>/agents/main/sessions/<session>.jsonl'
auto-rotate: phase=runtime action=warn ... reason=session-file-stat-failed error=ENOENT

The agent run itself completed successfully, so this did not block the test. Still, it may be worth checking whether explicit session IDs, session history storage, or Control UI session history can produce delayed/missing .jsonl file creation in this beta.

7. Security audit warning for unpinned plugin specs

status --deep reported a warning for unpinned plugin index install records, for example npm specs without exact versions. That warning is useful. For beta update testing, it would be helpful if the update flow also distinguished between pre-existing plugin pinning hygiene and issues introduced by the update.

8. Channels healthy after recovery

After recovery, deep status showed gateway reachable, event loop healthy, and external channels configured/healthy. The beta did not leave the gateway or channels permanently broken after the model config was corrected.

Final observed good state

After applying the workaround:

• openclaw config validate passed.
• Default model was openai-codex/gpt-5.5.
• Cron/main model was openai-codex/gpt-5.5.
• Mini cron model was openai-codex/gpt-5.4-mini.
• Explicit cron job payloads were no longer using direct openai/gpt-5.5.
• A fresh agent run succeeded with:
  • provider=openai-codex
  • model=gpt-5.5
  • agentHarnessId=pi
  • fallbackUsed=false
  • authMode=auth-profile
• The previously failing named cron jobs reported healthy status with no last error.

Impact

For users with OpenAI via Codex OAuth, this can make scheduled jobs and normal agent runs fail after upgrade, especially if they follow the apparent allowlist direction and migrate from openai-codex/gpt-* to openai/gpt-*. The failure mode is high-impact because many cron jobs may continue to fire and fail independently, while fallback can obscure the original model/harness problem by making some runs appear partially successful on Anthropic.

Requested maintainer review

Please route this to whoever owns the Codex harness / Codex OAuth model routing path. The key question is whether 2026.5.9-beta.1 should support openai-codex/gpt-* through a registered codex harness, or whether OAuth-backed Codex models should be migrated to pi runtime automatically. Right now the beta appears to allow a confusing intermediate state where openai-codex is the correct OAuth provider route, but codex as a harness id is not registered, while openai/gpt-* is allowlisted but fails on OAuth-only machines because it is treated as direct OpenAI API-key routing.