Switch to PI Runtime

[velvet wigeon]

Since 5.12 i had so many issues with the webui not updating on every tool and message, aswell as my agent just randomly getting slower and slower. Now i also have increased token usage. How do i go back to the pi runtime and not use codex?

[spring rampart]

First, please check your version too, because 5.12.x behavior changed a lot:

openclaw --version

To force the embedded agent back to PI, set the embedded harness runtime to pi:

openclaw config set agents.defaults.embeddedHarness '{"runtime":"pi","fallback":"pi"}' --strict-json
openclaw gateway restart

Important bit: harness choice is pinned per session after the first embedded run, so this affects new/reset sessions, not necessarily an already-running transcript. After restarting, start a new chat/session or reset the affected one.

Also check you do not have env overrides forcing Codex:

[spring rampart]

env | rg 'OPENCLAW_AGENT_RUNTIME|OPENCLAW_AGENT_HARNESS_FALLBACK'

If you see OPENCLAW_AGENT_RUNTIME=codex, remove it from your shell/service env or change it to pi, then restart the gateway again.

Docs: https://docs.openclaw.ai/gateway/configuration#agentsdefaultsembeddedharness and quick debugging checklist: https://docs.openclaw.ai/help/faq#first-60-seconds-if-something-is-broken

[velvet wigeon]

OpenClaw 2026.5.12 (f066dd2)

What is really diffrent from codex and pi. Im guessing pi has less overhead compared to codex?

[spring rampart]

Yeah, your intuition is mostly right, but “overhead” is only part of it.

PI is the built-in embedded runner. OpenClaw directly owns the agent session, event stream, tools, compaction hooks, provider routing, and transcript. It is the older/default compatibility path and tends to be simpler in-process plumbing.

Codex is a plugin harness that routes the embedded turn through Codex app-server. Codex then owns the low-level agent session: native thread resume, model discovery, native compaction, and execution. OpenClaw still owns Discord/web UI delivery, tools, approvals, media, session files, and the visible transcript mirror.

So the practical differences are:

• PI: less moving parts, provider-agnostic, usually the safer fallback if you care about predictable OpenClaw behavior.
• Codex harness: more native Codex behavior, better fit if you specifically want Codex app-server/session semantics, but it adds another runtime layer and a sidecar thread/session mirror.
• Token usage: can differ because the harness owns how the native session/compaction/context is handled. It is plausible Codex has more overhead in some cases, especially if mirroring/compaction/session state is not behaving well, but I would treat the 5.12 slowdown + UI update issues as possible bugs/regressions too.

For your case, switching back to PI is reasonable. Since you are on 2026.5.12 (f066dd2), if the web UI still misses tool/message updates on PI with a fresh session, that is worth filing with logs: https://github.com/openclaw/openclaw/issues

Docs I checked: https://docs.openclaw.ai/plugins/codex-harness and https://docs.openclaw.ai/gateway/configuration#agentsdefaultsembeddedharness

[velvet wigeon]

Error: Config validation failed: agents.defaults.embeddedHarness: Unrecognized key: "fallback"

[spring rampart]

Yep, that is on me. I checked your exact build 2026.5.12 (f066dd2): in that version agents.defaults.embeddedHarness.fallback does not exist yet. Newer docs moved under my feet.

For your version, force PI with provider/model runtime policy instead:

openclaw config unset agents.defaults.embeddedHarness.fallback
openclaw config set models.providers.openai.agentRuntime '{"id":"pi"}' --strict-json
openclaw gateway restart

Then start a fresh session with /new or /reset.

If config unset refuses because validation is already broken, open the file from:

openclaw config file

[spring rampart]

and remove only this bad key:

fallback: "pi"

In 2026.5.12, the relevant docs say explicit PI is agentRuntime.id: "pi", while fallback only exists in newer config docs. Sorry for the bad key there. 🦞

[velvet wigeon]

root@openclaw:~ openclaw config unset agents.defaults.embeddedHarness.fallback

🦞 OpenClaw 2026.5.12 (f066dd2) — I'll do the boring stuff while you dramatically stare at the logs like it's cinema.

Config path not found: agents.defaults.embeddedHarness.fallback. Nothing was changed. Run openclaw config get <path> first if you are unsure of the path.
root@openclaw:~ openclaw config set models.providers.openai.agentRuntime '{"id":"pi"}' --strict-json

🦞 OpenClaw 2026.5.12 (f066dd2) — Built by lobsters, for humans. Don't question the hierarchy.

Error: Config validation failed: models.providers.openai.baseUrl: Invalid input: expected string, received undefined
root@openclaw:~

[spring rampart]

The first line is fine: there was no bad fallback key saved.

The second error is because setting models.providers.openai.agentRuntime creates/touches the whole OpenAI provider entry, and in this build that provider schema wants baseUrl. Avoid the provider-wide path and set the runtime on the exact model entry instead.

Check your selected model:

openclaw config get agents.defaults.model --json

If it prints "openai/gpt-5.5", run:

openclaw config set agents.defaults.models '{"openai/gpt-5.5":{"agentRuntime":{"id":"pi"}}}' --strict-json --merge
openclaw gateway restart

[spring rampart]

If it prints a different openai/... model, swap that key in the JSON. Example for openai/gpt-5.4-mini:

openclaw config set agents.defaults.models '{"openai/gpt-5.4-mini":{"agentRuntime":{"id":"pi"}}}' --strict-json --merge
openclaw gateway restart

Then use /new or /reset in the thread before testing.

This is the 5.12-specific shape from the docs: runtime policy can live at agents.defaults.models["provider/model"].agentRuntime.

[velvet wigeon]

Thats an annoying way of doing that. How do propperly switch all openai models? Also Is it smarter for me to use the git path or the npm package?

[spring rampart]

Yeah, agreed, model-by-model is annoying. The proper “all OpenAI agent models use PI” switch in 5.12 is provider-wide:

openclaw config set models.providers '{"openai":{"baseUrl":"https://api.openai.com/v1","agentRuntime":{"id":"pi"}}}' --strict-json --merge
openclaw gateway restart

Then use /new or /reset before testing.

Why this shape: models.providers.openai.agentRuntime.id = "pi" is the all-OpenAI runtime policy, but your config writer hit validation because the OpenAI provider object also needs baseUrl in this build. The merged object above sets both without replacing the rest of models.providers.

If you use a custom OpenAI-compatible endpoint, don’t use https://api.openai.com/v1; put your existing OpenAI baseUrl there instead.

On install path: for a normal always-on assistant, I’d use the stable npm/package install. Fewer moving parts, easier updates, less chance of sitting on a half-built checkout. Use the git/dev path when you want latest fixes quickly, are debugging with an agent that needs to read/edit the source, or you’re comfortable running pnpm install && pnpm build && pnpm ui:build.

You can switch channels with the installer/update flow:

[spring rampart]

openclaw update --channel stable
openclaw update --channel dev

Given you’re hitting 5.12-specific runtime/UI weirdness, my pragmatic take: stay on stable if PI fixes it; move to git/dev only if the bug still reproduces and you want the freshest fixes before the next package release.

Docs: https://docs.openclaw.ai/gateway/config-agents#runtime-policy and https://docs.openclaw.ai/install

[velvet wigeon]

what if im using openclaw with my codex sub?

[spring rampart]

If you’re using a Codex subscription, you have two valid routes:

1. Default/recommended Codex-sub route: keep openai/gpt-5.5 on the native Codex runtime. That uses Codex app-server and your Codex sign-in/subscription.
2. Compatibility route: force agentRuntime.id: "pi". PI can still use a selected openai-codex auth profile internally, so it can run through your Codex sub instead of normal OpenAI API billing.

So yes, you can use PI with your Codex sub. The important bit is: make sure the selected auth profile is openai-codex, not a normal openai API-key profile.

Check what you have:

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get models.providers.openai.agentRuntime --json

If you force PI provider-wide like this:

[spring rampart]

openclaw config set models.providers '{"openai":{"baseUrl":"https://api.openai.com/v1","agentRuntime":{"id":"pi"}}}' --strict-json --merge
openclaw gateway restart

then select/keep your Codex auth profile. If things look legacy or weird, run:

openclaw doctor --fix
openclaw config validate

Tradeoff: PI+Codex-sub is the “I want the older/simpler OpenClaw runner” path. Native Codex runtime is the “I want Codex app-server to own threads/compaction/execution” path. Given your UI/slowness issues, testing PI+Codex-sub is a reasonable move.

[velvet wigeon]

root@openclaw:~ openclaw update --channel dev
Updating OpenClaw...

│
◇ ✓ Working directory is clean (88ms)
│
◇ ✗ Fetching latest changes (353ms)
From https://github.com/openclaw/openclaw
! [rejected] v2026.5.16-beta.5 -> v2026.5.16-beta.5 (would clobber existing tag)

Update Result: ERROR
Root: /root/openclaw
Reason: fetch-failed
Before: 2026.5.17

Total time: 472ms
root@openclaw:~

trying to switch from npm to git dev, wtf, build broke after 31s no output from ts.

[spring rampart]

That specific error is git tag drift:

would clobber existing tag

Your local checkout has a v2026.5.16-beta.5 tag that does not match the remote tag. Since this is just a local tag cache, the usual fix is:

cd /root/openclaw
git status --short
git tag -d v2026.5.16-beta.5
git fetch --tags --force origin
openclaw update --channel dev

If it then gets to the build and dies with “no output from ts”, run the build manually once so you can see the real error instead of the updater timeout wrapper: