openclaw - 💡(How to fix) Fix agentHarnessId session pinning blocks post-hoc codex harness binding on pre-plugin agents [1 comments, 2 participants]

Summary

A pre-existing default main agent can remain pinned to its stored agentHarnessId=pi session route even after its config is changed to use the Codex harness (agentRuntime.id=codex) and the gateway is restarted.

The Codex harness itself is functional: a freshly-created staging agent with agentRuntime.id=codex answers successfully with agentHarnessId=codex. The failure appears specific to a pre-plugin/pre-existing agent whose session store already contains a matching session entry with agentHarnessId=pi.

Environment

• OpenClaw main package: v2026.5.6
• Codex plugin package: @openclaw/[email protected]
• Existing production agent: main
• Fresh staging agent: staging-native-codex
• OAuth profile values, session IDs, emails, and chat IDs are redacted below.

Observed behavior

1. Existing main agent was configured to match the working staging shape:
   • agents.list[0].model = openai/gpt-5.5
   • agents.list[0].agentRuntime.id = codex
2. openclaw config validate passed.
3. Gateway restart completed cleanly.
4. A direct non-delivery probe through main did not bind the Codex harness. It fell through to the direct OpenAI API path and failed with quota text.
5. A control probe through staging-native-codex succeeded with:
   • agentHarnessId=codex
   • model=gpt-5.5
   • response text OK
6. Session-store metadata showed the key difference:
   • existing main direct session: agentHarnessId=pi
   • staging direct session: agentHarnessId=codex

Source-level finding

Installed OpenClaw source appears to prefer a matching session entry's stored harness before consulting configured runtime policy. In the installed package, the relevant logic is equivalent to:

function resolveSessionPinnedAgentHarnessId(params) {
  if (params.sessionEntry?.sessionId !== params.sessionId) return resolveConfiguredAgentHarnessId(params);
  if (params.sessionEntry.agentHarnessId) return params.sessionEntry.agentHarnessId;
  const configuredAgentHarnessId = resolveConfiguredAgentHarnessId(params);
  if (configuredAgentHarnessId) return configuredAgentHarnessId;
  if (!params.sessionHasHistory) return;
  return "pi";
}

That makes the existing session's agentHarnessId=pi win over the newly configured agentRuntime.id=codex, even after config validation and gateway restart.

Expected behavior

One of these should be true:

1. A configured agentRuntime.id should override a stale session-stored agentHarnessId on the next new/direct session creation when the config has intentionally changed; or
2. OpenClaw should expose an explicit migration or repair command for pre-existing agents whose sessions pin an older harness; or
3. The CLI should fail with an actionable diagnostic that says the session store is pinning a different harness and names the safe repair path.

Actual behavior

The config and status surfaces can show the desired model/runtime direction, while the direct main session still routes through the PI harness because a matching persisted session entry keeps agentHarnessId=pi.

This is easy to miss unless callers assert the returned agentHarnessId, not just the model name.

Sanitized reproduction shape

1. Start with an existing default agent that has historical direct-session state pinned to PI.
2. Install/enable @openclaw/[email protected].
3. Create a fresh staging agent with agentRuntime.id=codex; verify it returns agentHarnessId=codex.
4. Change the existing default agent config to model=openai/gpt-5.5 and agentRuntime.id=codex.
5. Restart the gateway.
6. Run a direct probe against the default agent.
7. Observe that the fresh staging agent binds codex, while the existing default agent remains pinned to pi via session metadata.

Why this matters

This blocks a low-risk migration path from a legacy PI/OAuth default route to the native Codex harness for existing long-lived agents. The current workaround is to manually repair session route state or create a fresh replacement agent, both of which carry more operator risk than a first-class migration command.