openclaw - 💡(How to fix) Fix [Bug]: Codex Harness Startup Failures on Windows (OpenClaw 2026.5.18) [2 comments, 2 participants]

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

Summary

OpenClaw on Windows entered a broken state where Codex chats would never respond and the Codex harness repeatedly failed to start. The issue appeared related to a combination of:

invalid/legacy model config shape fragile Codex appServer.command override handling on Windows confusing plugin validation behavior misleading recovery guidance from error messages

Eventually the issue was resolved by removing the custom appServer.command override entirely and allowing OpenClaw to use the managed Codex app-server startup path.

Steps to reproduce

Environment OS: Windows 11 OpenClaw version: 2026.5.18 Provider: openai/gpt-5.5 Runtime: codex Install method: npm/global + .openclaw\npm nested packages

Install OpenClaw 2026.5.18 on Windows 11 using npm.

Enable the Codex plugin and configure:

"model": "openai/gpt-5.5"

Attempt to manually configure Codex app-server startup using:

"plugins": { "entries": { "codex": { "config": { "appServer": { "command": "node C:\Users\<user>\.openclaw\npm\node_modules\@openai\codex\bin\codex.js" } } } } }

Restart OpenClaw:

openclaw gateway restart Start a Codex chat session.

Observe repeated startup failures:

Codex agent harness failed codex app-server connection closed during startup Cannot find module 'C:\WINDOWS\system32\node C:...codex.js'

Attempting array syntax:

"command": [ "node", "C:\path\codex.js" ]

causes validation failure:

appServer.command: must be string

Expected behavior

Expected Behavior

• OpenClaw should successfully launch the managed Codex app-server on Windows when the Codex plugin is enabled.

• If appServer.command is misconfigured, OpenClaw should provide a clear validation error explaining the expected format instead of attempting startup with an invalid path.

• openclaw doctor should detect and warn about:

  • invalid model config shapes
  • malformed Windows appServer.command values
  • incompatible Codex overrides

• If array syntax for commands is unsupported, the configuration schema and documentation should explicitly state this.

• Manual appServer.command overrides should not result in Node attempting to load:

  C:\WINDOWS\system32\node C:\path\to\codex.js

• OpenClaw should either:

  • correctly split executable + arguments on Windows, or
  • reject invalid command strings before runtime.

• Default managed Codex startup should work without requiring manual app-server overrides.

Actual behavior

Actual Behavior

• OpenClaw failed to start Codex chat sessions on Windows despite successful authentication and plugin installation.

• Chat requests would hang indefinitely or terminate before any response was generated.

• Logs repeatedly showed:

  Codex agent harness failed; not falling back to embedded PI backend

• After adding a manual appServer.command override, OpenClaw attempted to launch an invalid module path:

  C:\WINDOWS\system32\node C:\Users\<user>\.openclaw\npm\node_modules\@openai\codex\bin\codex.js

• This caused repeated startup crashes:

  codex app-server connection closed during startup
  retries exhausted

• Using array syntax for the command:

  "command": [
    "node",
    "C:\\path\\codex.js"
  ]

  failed schema validation with:

  appServer.command: must be string

• openclaw doctor initially reported no critical configuration errors despite the runtime being unusable.

• Recovery guidance in error messages suggested manually configuring appServer.command, but this worsened the issue on Windows.

• The issue was only resolved after:

  • removing the custom appServer.command override entirely
  • restoring a plain-string model config
  • allowing OpenClaw to use the managed Codex startup path

OpenClaw version

2026 5.18 2026 5.12

Operating system

Windows 11 version 25

Install method

Installed globally via npm on Windows 11.

Model

Open AI 5.5 codex

Provider / routing chain

Provider / Routing Chain Environment observed during failures: text provider=openai-codex/gpt-5.5 harness=codex configured=unspecified OpenClaw routing chain: text User Request → OpenClaw Gateway → Embedded Agent Runtime → Codex Harness → Managed Codex App-Server → OpenAI Provider (GPT-5.5) Relevant plugins enabled: json { "plugins": { "allow": [ "openai", "codex", "memory-core" ] } } Final stable provider configuration: json "model": "openai/gpt-5.5" with: json "agentRuntime": { "id": "codex" } attached under: json agents.defaults.models["openai/gpt-5.5"]

Additional provider/model setup details

Provider / Routing Chain

Environment observed during failures:

provider=openai-codex/gpt-5.5
harness=codex
configured=unspecified

OpenClaw routing chain:

User Request
→ OpenClaw Gateway
→ Embedded Agent Runtime
→ Codex Harness
→ Managed Codex App-Server
→ OpenAI Provider (GPT-5.5)

Relevant plugins enabled:

{
  "plugins": {
    "allow": [
      "openai",
      "codex",
      "memory-core"
    ]
  }
}

Final stable provider configuration:

"model": "openai/gpt-5.5"

with:

"agentRuntime": {
  "id": "codex"
}

attached under:

agents.defaults.models["openai/gpt-5.5"]

Logs, screenshots, and evidence

## Logs, Screenshots, and Evidence

### Representative startup failure logs

 id="7r25eh"
[agent/embedded] strict-agentic execution contract active:
provider=openai-codex/gpt-5.5
harness=codex
configured=unspecified


 id="n8w9xj"
[agents/harness] Codex agent harness failed;
not falling back to embedded PI backend


 id="j6v3wh"
Managed Codex app-server binary was not found for @openai/codex


---

### Invalid `appServer.command` handling

After manually setting:

 id="h4g2vf"
"command": "node C:\\Users\\<user>\\.openclaw\\npm\\node_modules\\@openai\\codex\\bin\\codex.js"


runtime failures became:

 id="8blsji"
codex app-server connection closed during startup;
restarting app-server and retrying


followed by:

 id="59b9n9"
Cannot find module
'C:\WINDOWS\system32\node C:\Users\<user>\.openclaw\npm\node_modules\@openai\codex\bin\codex.js'


This indicates the entire command string was treated as a single module path.

---

### Validation conflict

Attempting safer array syntax:

 id="1bby1h"
"command": [
  "node",
  "C:\\path\\codex.js"
]


produced:

 id="gvklc9"
codex invalid config:
appServer.command: must be string


---

### Runtime behavior

Observed during failures:

* Chat sessions never returned responses
* Gateway stayed online
* WebSocket connections remained healthy
* Codex startup loop repeatedly crashed/retried
* Embedded fallback runtime was not used

---

### Doctor findings

Later deep scans reported:

* no active critical errors
* managed Codex runtime healthy
* custom app-server override removed
* configuration valid again

Final working state confirmed after:

* removing custom `appServer.command`
* restoring plain-string model config
* using managed Codex startup only

---

### Additional evidence

Representative gateway output:

 id="4i8y1j"
[gateway] agent model: openai/gpt-5.5


 id="3pq4hn"
[gateway] http server listening
(2 plugins: codex, memory-core)


 id="gt9r5m"
[gateway] ready


while Codex runtime still failed internally until overrides were removed.

Impact and severity

Openclaw does not respond in chat. ## Impact and Severity

Impact

• Codex-backed chat sessions were unusable on Windows.
• Requests either hung indefinitely or failed before generating any response.
• The gateway remained online, making the failure appear intermittent or internal rather than a clear startup/configuration issue.
• Recovery guidance led to additional invalid configurations that worsened startup behavior on Windows.
• Multiple reinstall/reconfiguration attempts were required before reaching a stable state.

Severity

Moderate to High

Reasoning based on observed behavior:

• Core Codex functionality became non-operational.
• Failures affected primary chat/runtime behavior rather than an optional feature.
• Error messages and validation behavior made recovery difficult.
• The issue persisted across gateway restarts until configuration overrides were manually removed.

Current Status

Resolved

Stable operation restored after:

• removing custom plugins.entries.codex.config.appServer overrides
• restoring valid model configuration shape
• allowing OpenClaw to use the managed Codex app-server startup path

Additional information

Additional Information

• The issue occurred on Windows 11 using a standard npm/global installation workflow.

• openclaw doctor initially reported no critical blocking issues even while Codex sessions were unusable.

• The runtime failure only became clear through gateway logs during live session startup attempts.

• The issue appeared sensitive to Windows path handling and command parsing behavior.

• Removing all custom Codex appServer overrides immediately stabilized the runtime.

• Final healthy configuration relied entirely on OpenClaw-managed Codex startup behavior.

• Deep scan/doctor output later confirmed:

  • configuration valid
  • managed Codex runtime healthy
  • no active critical findings

• No evidence of authentication failure, provider outage, or network connectivity issues was observed during the incident.

• The gateway, websocket layer, and plugin loading all remained operational throughout the failures.

• The issue reproduced consistently until the custom Codex app-server override was removed.