# OpenClaw: known issues context pack (KnownFix)
Generated 2026-10-26T10:18:14Z from github.com/openclaw/openclaw. Auto-extracted; verify via links. Source: https://knownfix.ai/issues/openclaw/
Fields: severity (auto-estimate) | symptom | versions mentioned | workaround (quoted from issue/comments, if any) | fixed-in (if referenced).

## Active
- [CRITICAL] Allow SecretRef objects in `mcp.servers[].env` schema (currently `string|number|boolean` only) (https://github.com/openclaw/openclaw/issues/76493)
  - symptom: The schema for mcp.servers[].env (and mcp.servers[].headers) is: This means SecretRef objects are rejected — operators following security best practices around secret indirection (openclaw config set 
  - versions: 2026.4.29
  - error: `The 3 most common MCP integrations (notion, github, postgres) each require at least one secret in `mcp.servers[].env`. With the current schema, these secrets MU`
  - workaround: The only documented workaround is the global `$OPENCLAW_STATE_DIR/.env`. [comment by @davidcittadini]
- [CRITICAL] [Bug]: Gateway memory sawtooth on 2026.9.6 — prepared-model-catalog worker grows to the full heap ceiling; ~200 critical (https://github.com/openclaw/openclaw/issues/159596)
  - symptom: Regression / performance On OpenClaw 2026.9.6 the Gateway exhibits a repeating memory "sawtooth": process RSS climbs steadily for several minutes, trips a memory pressure: level=critical event, an idl
  - versions: 2026.9.6, 16.6, 6.07
  - error: `openclaw gateway diagnostics export`
  - workaround: none stated
- [CRITICAL] [Bug]: OpenClaw 2026.9.5 Turned a Stable Environment Into an 8-Hour Failure Recovery Session (https://github.com/openclaw/openclaw/issues/153257)
  - symptom: Crash (process/app exits or hangs) I genuinely regret upgrading to OpenClaw 2026.9.5
  - versions: 2026.9.5, 9.5, 148.72
  - error: `SQLite transaction admission was refused`
  - workaround: none stated
- [MEDIUM] [Bug]: doctor --fix refuses `transcript-directives` while the gateway is running and blocks every later migration step — (https://github.com/openclaw/openclaw/issues/179481)
  - symptom: After a recovery that moved the old session store aside, openclaw doctor stops at: The only holder of the agent DB is the running gateway itself
  - versions: 2026.10.5
  - error: `Failing check transcript-directives (step-refused): Skipped historical transcript directive migration:`
  - workaround: `P2`: A large legacy-history installation cannot reliably complete offline repair at default limits, with an advanced-operator workaround and a focused repair already proposed. - `impact:ux-friction`: Repeated offline repair failures requir [comment by @clawsweeper[bot]]
- [HIGH] [Bug] "Cannot convert undefined or null to object" in 2026.3.2 with google-vertex/gemini-3.1-pro-preview (https://github.com/openclaw/openclaw/issues/38327)
  - symptom: Regression (worked before, now fails) After updating to 2026.3.2, any message causes embedded agent to fail with "Cannot convert undefined or null to object"
  - versions: 2026.3.2, 2026.2.26
  - error: `Mar 07 01:06:49 ... [agent/embedded] embedded run agent end: runId=... isError=true error=Cannot convert undefined or null to object`
  - workaround: none stated
- [CRITICAL] plugin-captures tmp dirs not GC'd after build/catalog operations — disk fills indefinitely (https://github.com/openclaw/openclaw/issues/158390)
  - symptom: /home/ /.openclaw/tmp/plugin-captures/ accumulates multi-GB session directories from plugin-build and model-catalog operations
  - error: `├── 9611f0b0-... 2.2G ← orphaned (empty owner.sqlite, no process handles)`
  - workaround: Manually delete orphaned dirs where `owner.sqlite` is empty and no process holds a file handle: [issue body]
- [MEDIUM] [Bug]: Codex app-server rewrites prompt on tool-call continuation turns, busting OpenAI prompt cache mid-turn (cache rat (https://github.com/openclaw/openclaw/issues/84110)
  - symptom: Regression (worked before, now fails) Since OC v2026.5.12 + codex-cli 0.130.0 (first observed 2026-05-15), the Codex app-server rewrites the full prompt between a user turn and its tool-call continuat
  - versions: 2026.5.12, 0.130.0, 3.5
  - error: `Turn 2 (exec tool call): cached=1`
  - workaround: none stated
- [CRITICAL] prepared-model-catalog.worker.js: unbounded memory leak, ~4-5 GB/h, provider-agnostic (reproduced on cold reboot + provi (https://github.com/openclaw/openclaw/issues/159662)
  - symptom: The gateway's prepared-model-catalog.worker.js worker thread leaks memory continuously and monotonically, independent of workload volume, model provider, or plugin configuration
  - versions: 2.5, 2026.9.6, 1.72
  - error: `openclaw gateway diagnostics export`
  - workaround: none stated
- [CRITICAL] [Bug]: 2026.9.5 model-catalog worker leaks openclaw-plugin-build-* source captures in tmp (1-3 GB/min, fills the disk) — (https://github.com/openclaw/openclaw/issues/156571)
  - symptom: Regression (worked before, now fails) On 2026.9.5 the prepared model-catalog worker keeps creating plugin source captures under $OPENCLAWHOME/tmp/openclaw-model-catalog-/openclaw-plugin-build- and nev
  - versions: 2026.9.5, 2.8, 58.8
  - error: `provider catalog refresh failed: Cannot find module '.../tmp/openclaw-model-catalog-XXXX/openclaw-plugin-build-GrYv8x/package-0/node_modules/llama-cpp/dist/prov`
  - workaround: a cron every minute that, inside each `openclaw-model-catalog-` folder, keeps the 10 oldest captures (the ones created at worker start) and deletes the rest older than 1 minute, by creation time (mtime keeps changing). [issue body]
- [MEDIUM] [Bug]: OpenAI Codex model discovery hardcodes `client_version=0.158.0`, ignoring the configured external Codex app-serve (https://github.com/openclaw/openclaw/issues/162768)
  - symptom: extensions/openai/openai-provider.ts always queries the Codex models endpoint with the managed runtime's version: However, the codex plugin officially supports external app-server binaries via plugins
  - versions: 0.158.0, 0.149.0, 2026.9.7
  - error: `// extensions/openai/openai-provider.ts:102-105 (main)`
  - workaround: none stated
- [CRITICAL] [Tracking] 2026.9.3 / 2026.9.4 update, upgrade and recovery reliability (https://github.com/openclaw/openclaw/issues/145252)
  - symptom: Track update, upgrade, Doctor, migration, rollback and restart reliability around OpenClaw 2026.9.3 / 2026.9.4
  - versions: 2026.9.3, 2026.9.4
  - error: `Track update, upgrade, Doctor, migration, rollback and restart reliability around OpenClaw 2026.9.3 / 2026.9.4. This coordination index does not replace the lin`
  - workaround: none stated
- [CRITICAL] [Bug]: 2026.9.6 prepared-model-catalog worker leaks ~1 GiB per 5 min; each memory reclamation supersedes the runtime pub (https://github.com/openclaw/openclaw/issues/160548)
  - symptom: Since upgrading to 2026.9.6 (eb377ac) the prepared-model-catalog.worker.js thread grows by roughly 1 GiB every 5 minutes with no user action, reaches 8 to 13 GiB, and the gateway's memory-pressure rec
  - versions: 2026.9.6, 8.59, 7.62
  - error: `... same sawtooth every 45 to 60 min through the day ...`
  - workaround: none stated

## Recently closed (with fix/workaround info)
- [Bug]: [Regression] 2026.5.27: Codex app-server turn-completion stall returns ("Codex stopped before confirmin (https://github.com/openclaw/openclaw/issues/88312); workaround: Only found workaround is pinning 5.26.
- [Bug]: Docker Install + Sandbox can't workspaceAccess at all (https://github.com/openclaw/openclaw/issues/31331); workaround: `"sandbox": { ; "mode": "all",`