openclaw - 💡(How to fix) Fix [Bug]: agentRuntime.id "codex" at agents.list[] is ignored by the model-prefix resolver — docs-recommended Codex harness setup fails [3 comments, 3 participants]

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

With the codex plugin installed and active, configuring an agent per the documented model: "openai/gpt-5.5" + agentRuntime: { id: "codex" } setup fails because the model resolver routes to the raw openai provider and ignores the agent's runtime override.

Steps to reproduce

1. Install and activate @openclaw/[email protected] (plugins.allow includes codex, plugins.entries.codex.enabled: true); confirm gateway log shows http server listening (3 plugins: codex, discord, webhooks; ...).
2. Set the main agent in agents.list:

   { "id": "main", "model": "openai/gpt-5.5", "agentRuntime": { "id": "codex" } }

3. Restart the gateway.
4. Run openclaw agent --agent main --message "test".

Expected behavior

Per docs.openclaw.ai/plugins/codex-harness, this combination routes the model lookup through the Codex harness and uses the existing openai-codex OAuth profile for auth. The agent should reply.

Actual behavior

The resolver reports requestedProvider: "openai" and queries the raw OpenAI provider, which has no API key. The agentRuntime.id override is not consulted. Error:

FailoverError: No API key found for provider "openai". You are authenticated
with OpenAI Codex OAuth. Use openai-codex/gpt-5.5, or set OPENAI_API_KEY for
direct OpenAI API access.

OpenClaw version

2026.5.2 (8b2a6e5)

Operating system

macOS 26.2 (arm64)

Install method

pnpm (global)

Model

openai/gpt-5.5 (with agentRuntime.id codex)

Provider / routing chain

Intended: openclaw -> codex harness (intercepts openai/* via agentRuntime) -> openai-codex OAuth -> Codex app-server. Observed: openclaw -> openai provider lookup (agentRuntime override bypassed) -> fails on missing API key.

Additional provider/model setup details

Codex plugin manifest declares providers: ["codex"] and activation.onAgentHarnesses: ["codex"]. Existing openai-codex:default OAuth profile has valid accountId, access, and refresh fields. Plugin activation confirmed in gateway log before the test.

Logs, screenshots, and evidence

Trajectory record (runId=7c0c4066-6b50-45f1-94a7-8bcaf938c25e):
{
  "decision":            "candidate_failed",
  "requestedProvider":   "openai",
  "requestedModel":      "gpt-5.5",
  "candidateProvider":   "openai",
  "candidateModel":      "gpt-5.5",
  "reason":              "auth",
  "status":              401,
  "fallbackConfigured":  false,
  "fallbackStepFromModel":          "openai/gpt-5.5",
  "fallbackStepFromFailureReason":  "auth"
}

Plugin activation confirmed before the test:
http server listening (3 plugins: codex, discord, webhooks; 6.2s)

Impact and severity

Affected: any user attempting to enable the Codex harness following the official docs. Severity: High for the codex-harness use case — no working config to enable native Codex routing as documented. Frequency: 4/4 observed attempts (across config edits and gateway restarts). Consequence: The documented setup is unusable; the only routing path that does activate the codex provider is the deprecated codex/gpt-* form, which then hits a separate refresh bug (filed as a separate issue).

Additional information

Either the docs are aspirational and need correcting, or the resolver wiring is missing. If the latter, the fix likely belongs at the point where agents.list[].model is split into {provider, model} for resolver lookup — that path needs to also check the agent's agentRuntime.id and route to the harness when set. NOT_ENOUGH_INFO on which part of the dist is responsible (code is bundled)