openclaw - 💡(How to fix) Fix [Bug]: doctor lint misses disabled codex plugin required by native codex runtime [1 pull requests]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

openclaw doctor --lint does not flag a config where openai/gpt-5.5 is configured to run with native agentRuntime.id: "codex" while the codex plugin is disabled/not loaded; the gateway then fails cron/direct agent turns later with MissingAgentHarnessError.

Steps to reproduce

1. Run OpenClaw 2026.5.31-beta.1 with an agent model config equivalent to:
   • agents.defaults.model.primary: "openai/gpt-5.5"
   • agents.defaults.models["openai/gpt-5.5"].agentRuntime.id: "codex"
   • plugins.entries.codex.enabled: false
2. Run openclaw doctor --lint --json.
3. Start/restart the gateway.
4. Run a no-delivery gateway agent turn, for example:

openclaw agent --session-key agent:main:beta531-smoke-codex-runtime --message 'Beta 5.31 smoke test. Reply exactly: BETA531_AGENT_OK' --json --timeout 120

Expected behavior

doctor --lint should report that the configured native codex agent runtime requires a registered/loaded codex harness, but the codex plugin is disabled or unavailable.

If a repair path is supported, doctor --fix should either enable/repair the required plugin or clearly instruct the user to remove/change the native codex runtime override before gateway agent turns run.

Actual behavior

doctor --lint --json did not flag the runtime/plugin mismatch. The gateway started, but direct gateway agent turns and existing cron jobs failed later with:

MissingAgentHarnessError: Requested agent harness "codex" is not registered.

After enabling the codex plugin and restarting the gateway, the same no-delivery smoke succeeded and reported agentHarnessId: "codex".

OpenClaw version

2026.5.31-beta.1 (ebba638)

Operating system

Linux 6.17.0-1011-oracle arm64

Install method

npm global / systemd user gateway service

Model

openai/gpt-5.5

Provider / routing chain

OpenClaw Gateway -> OpenAI provider/auth profile -> native codex agent runtime

Additional provider/model setup details

The relevant live config had openai/gpt-5.5 mapped to agentRuntime.id: "codex" in both agents.defaults.models and per-agent models, but plugins.entries.codex.enabled was false. openclaw plugins list --json showed the codex plugin disabled/not loaded before the recovery test.

Logs, screenshots, and evidence

# Before enabling codex plugin:
openclaw plugins list --json
# codex plugin record: enabled=false, status=disabled

openclaw status --deep --json
# agents.list/status reported configuredModel=openai/gpt-5.5 and runtime=OpenAI Codex
# health loaded plugins did not include codex

openclaw doctor --lint --json
# did not report the required codex runtime plugin/harness mismatch

openclaw agent --session-key agent:main:beta531-smoke-codex-runtime --message 'Beta 5.31 smoke test. Reply exactly: BETA531_AGENT_OK' --json --timeout 120
GatewayClientRequestError: MissingAgentHarnessError: Requested agent harness "codex" is not registered.

# Existing cron job failure from the same gateway:
2026-05-31T18:30:03Z [diagnostic] message processed: channel=cron ... outcome=error duration=109ms error="MissingAgentHarnessError: Requested agent harness "codex" is not registered."

# After recovery:
openclaw plugins enable codex
openclaw gateway restart

[gateway] http server listening (7 plugins: active-memory, codex, file-transfer, google, memory-core, memory-wiki, telegram; 5.2s)
[gateway] agent runtime plugins pre-warmed in 317ms

openclaw agent --session-key agent:main:beta531-smoke-codex-runtime-after-plugin --message 'Beta 5.31 codex plugin enabled smoke test. Reply exactly: BETA531_AGENT_OK' --json --timeout 120
# status: ok
# finalAssistantVisibleText: BETA531_AGENT_OK
# provider: openai
# model: gpt-5.5
# agentHarnessId: codex

Additional related evidence was also added to #86342: https://github.com/openclaw/openclaw/issues/86342#issuecomment-4587710105

Impact and severity

Affected: users with native codex runtime configured while the codex plugin is disabled or lost during upgrade/config history.

Severity: High for affected users, because direct gateway agent turns and scheduled cron agent jobs fail before model execution.

Frequency: Always observed for this configuration until the codex plugin was enabled and the gateway restarted.

Consequence: Existing scheduled cron work and direct agent turns fail with a runtime harness error, while doctor --lint does not point to the actionable config/plugin mismatch.

Additional information

This is narrower than the broader harness-registry issue in #86342. This issue is specifically about doctor/config validation and repair guidance for a static mismatch: a configured native codex runtime with the required codex plugin disabled/not loaded.

Likely fix surface appears small: add a doctor lint check that resolves effective agent model runtime requirements and verifies required harness/plugin availability. A fix path could either enable/repair the missing plugin or instruct users to remove/switch the agentRuntime.id: "codex" override, depending on the intended product behavior.