v2026.5.12 regression: /v1/chat/completions returns 500 after selecting unregistered codex harness

Summary

After upgrading a canary gateway from a known-working OpenClaw image digest to v2026.5.12, the gateway starts successfully and passes readiness, but OpenAI-compatible requests to:

POST /v1/chat/completions

fail with HTTP 500.

The gateway log shows:

[diagnostic] lane task error: lane=main ... error="Error: Requested agent harness "codex" is not registered."
[openai-compat] chat completion failed: Error: Requested agent harness "codex" is not registered.

This blocks a downstream integration that uses the OpenAI-compatible chat-completions endpoint.

Regression / Images Tested

A prior pinned digest in the same deployment serves the same request successfully. I can share the exact known-good digest privately if useful.

Failing candidate digest:

ghcr.io/openclaw/openclaw@sha256:e2482a66682de6f540dcfd9921e410c23fd060dcd441382ff952247ee911a672

The v2026.5.12 digest starts, passes readiness, then fails the same request with the codex harness registration error.

Request

{
  "model": "openclaw:main",
  "messages": [
    {
      "role": "user",
      "content": "Reply with the single word OK."
    }
  ],
  "max_tokens": 10
}

The request includes:

Authorization: Bearer <gateway token>
Content-Type: application/json
x-openclaw-agent-id: main

Expected Behavior

One of the following should happen:

1. If openai/* agent models are intended to route through the bundled Codex app-server harness by default, the gateway should ensure the codex harness is installed, activated, and registered before readiness succeeds.
2. If the deployment is configured to use PI/direct OpenAI API routing, /v1/chat/completions should not select the codex harness.
3. If the configuration is invalid or incomplete, startup/readiness should fail clearly instead of allowing readiness to pass and returning a generic HTTP 500 at request time.

Actual Behavior

Readiness passes, but the first OpenAI-compatible chat completion fails:

HTTP/1.1 500

{
  "error": {
    "message": "internal error",
    "type": "api_error"
  }
}

Gateway log:

[diagnostic] lane task error: lane=main ... error="Error: Requested agent harness "codex" is not registered."
[openai-compat] chat completion failed: Error: Requested agent harness "codex" is not registered.

Readiness Detail

The canary passed local /healthz, local /readyz, external /readyz, and orchestration-level readiness before the chat-completions probe ran.

The same HTTP 500 occurred for both:

• the minimal request shown above, and
• a downstream-contract probe that asks for strict JSON content from choices[0].message.content.

Baseline Config

Minimal config used token auth and enabled the OpenAI-compatible chat-completions endpoint. Secret values and deployment-specific network details are omitted.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.2"
      }
    }
  },
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

Configs Attempted

1. Explicit Codex Plugin Enabled

Because current docs indicate openai/gpt-* agent turns normally use the Codex runtime and require the bundled codex plugin, I tried explicitly enabling the plugin:

{
  "plugins": {
    "entries": {
      "codex": {
        "enabled": true
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.2"
      }
    }
  }
}

Result: gateway still passed readiness, but /v1/chat/completions failed with the same error:

Requested agent harness "codex" is not registered.

If this deployment also requires plugins.allow, please confirm the required shape. The current docs say codex must be included in plugins.allow when an allowlist is used.

2. Whole-Agent / Env-Level PI Attempts

I also tried:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.2"
      },
      "agentRuntime": {
        "id": "pi"
      }
    }
  }
}

and:

OPENCLAW_AGENT_RUNTIME=pi

Both passed readiness and still failed with the same codex harness error.

However, I now see from the current runtime docs that whole-agent runtime pins and OPENCLAW_AGENT_RUNTIME are ignored, so these may not be valid override attempts in v2026.5.12. I am including them only as context, not as evidence that provider/model-scoped PI routing is broken.

Questions

What is the correct openclaw.json configuration for v2026.5.12 to serve:

POST /v1/chat/completions

with:

{
  "model": "openclaw:main"
}

without failing on:

Requested agent harness "codex" is not registered.

Specifically:

1. If openai/gpt-5.2 should route through Codex by default, what config is required to ensure the bundled codex harness is registered in the container image?
2. If we want to force PI/direct OpenAI API routing instead, what is the correct provider/model-scoped agentRuntime.id: "pi" config shape for v2026.5.12?
3. Should gateway readiness fail when the selected runtime harness is unavailable?
4. Is this related to the earlier Codex harness startup/activation issue where plugin diagnostics could make Codex look available even though the live runtime harness was not registered?

Repro Command

curl -i -sS -X POST "$OPENCLAW_GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $OPENCLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-openclaw-agent-id: main" \
  -d '{
    "model": "openclaw:main",
    "messages": [
      {
        "role": "user",
        "content": "Reply with the single word OK."
      }
    ],
    "max_tokens": 10
  }'

Notes

I can provide sanitized canary summaries and logs if useful. The important comparison is that a prior pinned digest succeeds with the same OpenAI-compatible request, while v2026.5.12 passes readiness but fails at request time with the unregistered codex harness error.