openclaw - 💡(How to fix) Fix [Bug]: `agentRuntime.id=codex` can be configured without the Codex plugin installed, causing harness-not-registered failures [3 comments, 3 participants]

Bug type

Behavior bug / configuration validation gap

Summary

On OpenClaw 2026.5.7, my install ended up with defaults pointing at the Codex agent runtime, but the Codex plugin was not installed or enabled. The gateway stayed up, plugins doctor did not flag the missing runtime dependency, and every OpenAI/Codex agent turn failed before reply with:

Requested agent harness "codex" is not registered.

Manually installing the official Codex plugin fixed the system immediately:

openclaw plugins install clawhub:@openclaw/codex

After that, plugins inspect codex reported Status: loaded, plugins doctor reported no plugin issues, and a direct openclaw agent --agent main --message ... --json smoke test returned successfully with agentHarnessId: "codex".

Environment

• OpenClaw: 2026.5.7 (eeef486)
• OS: macOS 26.3.1 (a) / build 25D771280a
• Node: v22.22.0
• Install method: npm global through nvm (~/.nvm/.../bin/openclaw)
• Gateway: local managed gateway
• Primary model: openai/gpt-5.5

Relevant config state before recovery

The defaults selected the Codex runtime:

{
  "agents": {
    "defaults": {
      "agentRuntime": { "id": "codex" },
      "model": { "primary": "openai/gpt-5.5" }
    }
  }
}

But the Codex plugin was absent from plugins.entries, absent from plugins list, and openclaw plugins inspect codex failed with Plugin not found: codex.

Actual behavior

Agent turns and channel-routed work failed before reply. Representative sanitized logs:

[diagnostic] lane task error: lane=main durationMs=2 error="Error: Requested agent harness "codex" is not registered."
[model-fallback/decision] model fallback decision: decision=candidate_failed requested=openai/gpt-5.5 candidate=openai/gpt-5.5 reason=unknown next=openai/gpt-5.4 detail=Requested agent harness "codex" is not registered.
Embedded agent failed before reply: Requested agent harness "codex" is not registered.

This also affected cron/fallback paths that attempted openai-codex/* or openai/* candidates under the same missing Codex harness state.

Expected behavior

If config selects agentRuntime.id = "codex", OpenClaw should do at least one of the following before user traffic reaches a failing runtime state:

1. install/enable the official @openclaw/codex plugin automatically, similar to other missing configured plugin recovery paths;
2. have openclaw doctor / plugins doctor produce a clear error such as agentRuntime.id=codex requires @openclaw/codex to be installed and enabled;
3. block or repair startup/config validation so a strict Codex runtime cannot remain active without a registered codex agent harness.

Recovery that worked

openclaw plugins install clawhub:@openclaw/codex
openclaw plugins inspect codex
openclaw plugins doctor
openclaw agent --agent main --message "Reply with exactly: OK" --timeout 90 --json

Post-recovery state:

Codex plugin: Status: loaded
Source: ~/.openclaw/extensions/codex/dist/index.js
Origin: global
Version: 2026.5.7
Install source: clawhub:@openclaw/codex
Agent smoke: OK, agentHarnessId="codex"

Related but not exact duplicates

• #66260 is conceptually close, but it is closed as a startup activation issue where the Codex harness owner plugin can be skipped. My case was a stable 2026.5.7 install where the configured runtime plugin was not installed at all.
• #81194 / #81196 cover beta @openclaw/codex module-resolution failures after the plugin is installed. My failure happened before that: codex was missing, and installing the stable ClawHub plugin fixed it.
• #81295 is about deferred loading of non-bundled plugins. In my case other non-bundled plugins were discoverable; the codex plugin specifically was absent while agentRuntime.id=codex remained configured.

Impact

The failure is hard to self-diagnose from the user-facing error because the model configuration looks valid (openai/gpt-5.5 + Codex runtime), but the real fix is to install the runtime owner plugin. A doctor/config validation check would have made this a one-command repair instead of repeated Agent failed before reply failures.