#swtich from API to openai subscription and use codex harness

1 messages · Page 1 of 1 (latest)

civic grotto
#

right now using gpt-5.4 via credits but openai has a generous subscription so i want to use codex as the harness specifically with the model openai/gpt-5.5 how do i switch? running in a vps btw

proud prawnBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

lilac minnowBOT
#

Yep — for native Codex harness, use:

  • model: openai/gpt-5.5
  • runtime: codex
  • auth: openai-codex OAuth/device-code on the VPS
openclaw --version

openclaw models auth login --provider openai-codex --device-code --set-default

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw config set agents.defaults.agentRuntime.fallback none
# 
openclaw doctor
openclaw gateway restart

Then start a fresh chat/session with /new or /reset, and check /status. You want to see Runtime: OpenAI Codex.

Important distinction: openai-codex/gpt-5.5 = subscription auth through normal OpenClaw/PI. openai/gpt-5.5 + agentRuntime.id: "codex" = actual Codex app-server harness.

OpenAI’s docs say Codex is included with ChatGPT paid plans, and on a VPS the device-code style sign-in is usually the least annoying route. (help.openai.com)

Docs: https://docs.openclaw.ai/providers/openai and https://docs.openclaw.ai/plugins/codex-harness 🦐

civic grotto
#

my default is also set by an env var "openai/gpt-5.5" if i change models later this way it wont cause problems right? (via coolify)

lilac minnowBOT
#

Mostly yes — as long as the runtime matches the model you switch to.

The thing that can bite you is this:

  • openai/gpt-5.5 + agentRuntime.id=codex ✅ native Codex harness
  • later switching to another Codex-compatible openai/gpt-* ✅ likely fine
  • later switching to anthropic/*, google/*, openai-codex/*, etc while agentRuntime.id=codex is still forced ⚠️ can fail, because OpenClaw will still try to run that turn through Codex

So if this VPS/Coolify deployment is Codex-only, you’re good. If you want to freely change providers later, either:

  1. make a dedicated Codex agent, or
  2. change runtime back when switching:
openclaw config set agents.defaults.agentRuntime.id pi
# or:
# 
openclaw config set agents.defaults.agentRuntime.id auto
openclaw gateway restart

Then use /new or /reset because runtime selection is sticky per session.

Also: if Coolify is setting the default via env/config templating, change it in Coolify too — otherwise a redeploy may overwrite whatever you changed with openclaw config set.

Docs: https://docs.openclaw.ai/plugins/codex-harness 🦐

civic grotto
#

openclaw models auth login --provider openai-codex --device-code --set-default
error: unknown option '--device-code'

lilac minnowBOT
#

Ah yep, that flag was wrong for your CLI. Use the method form:

openclaw models auth login --provider openai-codex --method device-code

I’d omit --set-default for your case, because --set-default may set the default to openai-codex/gpt-5.5 — that’s the PI subscription route, not the native Codex harness route you’re aiming for.

Then keep/set:

openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw gateway restart

If --method device-code also fails, paste:

# 
openclaw --version
openclaw models auth login --help

because then you’re probably on a version before the device-code method landed. 🦐

civic grotto
#

i dont see a code to paste into openai auth

🦞 OpenClaw 2026.4.26 (be8c246)
Welcome to the command line: where dreams compile and confidence segfaults.

│
◓ Requesting device code…│
◇ OpenAI Codex device code ──────────────────────────────────────╮
│ │
│ Open this URL in your LOCAL browser and enter the code below. │
│ URL: https://auth.openai.com/codex/device │
│ Code: [shown on the local device only] │
│ Code expires in 15 minutes. Never share it. │
│ │
├─────────────────────────────────────────────────────────────────╯

Open this URL in your LOCAL browser:

https://auth.openai.com/codex/device

◓ Waiting for device authorization…...

lilac minnowBOT
#

Yep, that looks like a 2026.4.26 remote/VPS UI bug: the device-code flow detects “remote” and hides the actual code, but then doesn’t show it anywhere useful. 😬

Fastest workaround: use the normal OAuth flow instead:

openclaw models auth login --provider openai-codex --method oauth

On a VPS it should print a URL, you open it locally, then paste the redirect URL/code back into the terminal.

If you specifically want device-code, you can force it to treat the terminal as “local” so it prints the code:

env -u SSH_CLIENT -u SSH_TTY -u SSH_CONNECTION -u REMOTE_CONTAINERS -u CODESPACES DISPLAY=:0 \
  openclaw models auth login --provider openai-codex --method device-code
#

It may fail to open a browser, but it should show the code in the terminal. Don’t share that code publicly.

After auth succeeds, continue with:

openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw gateway restart

Docs: https://docs.openclaw.ai/providers/openai

civic grotto
#

looks like it worked but the terminal crashed is it safe to do the whole thing again

lilac minnowBOT
#

Yep — safe to do again. The old device-code attempt will just expire, and re-running auth/config is effectively harmless.

Before repeating, check if it already saved:

openclaw models status
openclaw models list --provider openai-codex

If openai-codex auth looks present, skip auth and just do:

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw doctor
# 
openclaw gateway restart

If auth is missing, rerun login — don’t use --set-default:

openclaw models auth login --provider openai-codex --method oauth

or retry device-code with the workaround from above. After restart, use /new or /reset, then /status should show Runtime: OpenAI Codex.

civic grotto
#

also i was using api key before, will this switch to auth?

lilac minnowBOT
#

Yes — if you set the runtime to Codex, it should use the OpenAI Codex OAuth profile, not your old API-key billing path.

The important split:

openai/gpt-5.5 + agentRuntime.id=pi

= normal OpenAI API route / OPENAI_API_KEY

openai/gpt-5.5 + agentRuntime.id=codex

= native Codex harness, using Codex auth/account

So keep:

# 
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex

Your old OPENAI_API_KEY can stay for other OpenAI API usage, but if you want to be absolutely sure it never falls back to API-key behavior, remove it from Coolify after Codex OAuth is working.

Verify with /status: you want Runtime: OpenAI Codex, not OpenClaw Pi Default.

civic grotto
#

ok auth complete now how to swtich to the codex harness

lilac minnowBOT
#

Nice — now switch the runtime to Codex:

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw config set agents.defaults.agentRuntime.fallback none

openclaw doctor
openclaw gateway restart

Then in chat run:

/new
# 
/status

You want /status to show:

Runtime: OpenAI Codex

If Coolify sets your model via env/config template, also make sure Coolify still has openai/gpt-5.5 and doesn’t overwrite the config on redeploy.

Docs: https://docs.openclaw.ai/plugins/codex-harness

civic grotto
#

do i really need to run all these?

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model.primary openai/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id codex
openclaw config set agents.defaults.agentRuntime.fallback none

can you explain what each one does

lilac minnowBOT
#

Not all 4 are strictly required in every setup.

The essential one is:

openclaw config set agents.defaults.agentRuntime.id codex

That tells OpenClaw: “run agent turns through the Codex harness.”

What each line does:

openclaw config set plugins.entries.codex.enabled true

Enables the bundled Codex plugin. Needed if it isn’t already enabled.

# 
openclaw config set agents.defaults.model.primary openai/gpt-5.5

Sets the default model. If Coolify already sets this to openai/gpt-5.5, you can skip this — just make sure Coolify won’t overwrite it later.

openclaw config set agents.defaults.agentRuntime.id codex

This is the actual harness switch. Without this, openai/gpt-5.5 may still route through normal OpenClaw/PI/API behavior instead of native Codex.

openclaw config set agents.defaults.agentRuntime.fallback none

Optional safety. It means “if Codex can’t run, fail clearly instead of silently falling back.” For explicit codex runtime this is basically the default, but setting it makes the intent obvious.

#

So minimal version, assuming your model is already set:

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.agentRuntime.id codex
openclaw gateway restart

Then /new or /reset, then /status should show Runtime: OpenAI Codex.

Docs: https://docs.openclaw.ai/plugins/codex-harness

civic grotto
#

openclaw config set plugins.entries.codex.enabled true

🦞 OpenClaw 2026.4.26 (be8c246)
I've seen your commit messages. We'll work on that together.

Config overwrite: /data/.openclaw/openclaw.json (sha256 72497349a84b075f692eaa61e9838faa7525de26a9cf60dee5bde7d98bc32606 -> 0ba4183c9a82f96e407e2059be4ae818faa0de0741241b7440029bbcde37a7c6, backup=/data/.openclaw/openclaw.json.bak)
Updated plugins.entries.codex.enabled. Restart the gateway to apply.
openclaw config set agents.defaults.model.primary openai/gpt-5.5

🦞 OpenClaw 2026.4.26 (be8c246)
I'm like tmux: confusing at first, then suddenly you can't live without me.

Config overwrite: /data/.openclaw/openclaw.json (sha256 0ba4183c9a82f96e407e2059be4ae818faa0de0741241b7440029bbcde37a7c6 -> 764f5ed84ee67dec3b3249a59713a541c53ac327108a99a3d250adb88525c92b, backup=/data/.openclaw/openclaw.json.bak)
Updated agents.defaults.model.primary. Restart the gateway to apply.
openclaw config set agents.defaults.agentRuntime.id codex

🦞 OpenClaw 2026.4.26 (be8c246)
I autocomplete your thoughts—just slower and with more API calls.

Config overwrite: /data/.openclaw/openclaw.json (sha256 764f5ed84ee67dec3b3249a59713a541c53ac327108a99a3d250adb88525c92b -> 19cb2c98696ea283c13a439f13585a98cf172cfb8e1cfdf1abcd24972a486dcc, backup=/data/.openclaw/openclaw.json.bak)
Updated agents.defaults.agentRuntime.id. Restart the gateway to apply.
openclaw config set agents.defaults.agentRuntime.fallback none

🦞 OpenClaw 2026.4.26 (be8c246)
I run on caffeine, JSON5, and the audacity of "it worked on my machine."

Config overwrite: /data/.openclaw/openclaw.json (sha256 19cb2c98696ea283c13a439f13585a98cf172cfb8e1cfdf1abcd24972a486dcc -> 4efd028f85859f3367c4099fa922497b2ff5ba97df39a58cc72f0e01fe2738a2, backup=/data/.openclaw/openclaw.json.bak)
Updated agents.defaults.agentRuntime.fallback. Restart the gateway to apply.

^ ok i ran all of these, i will restart now and get back

lilac minnowBOT
#

Perfect, those all applied cleanly. After restart, do:

/new
/status

Expected:

Model: openai/gpt-5.5
Runtime: OpenAI Codex

If it still says OpenClaw Pi Default, the usual culprits are:

  1. old session wasn’t reset (/new fixes it)
#
  1. Coolify env/template overwrote config on restart
  2. Codex plugin didn’t load — run openclaw doctor / openclaw status --all

You’re on the right track. 🦐

civic grotto
#

/status worked with out /new

why?

also it still shows openai env key

🦞 OpenClaw 2026.4.26 (be8c246)
🧠 Model: openai/gpt-5.5 · 🔑 api-key (env: OPENAI_API_KEY)
🗄️ Cache: 100% hit · 20k cached, 0 new
📚 Context: 0/200k (0%) · 🧹 Compactions: 0
🧵 Session: agent:main:main • updated just now
⚙️ Execution: direct · Runtime: OpenAI Codex · Think: low · Text: low · elevated
🪢 Queue: collect (depth 0)
lilac minnowBOT
#

That’s actually the good state ✅

Why /status worked without /new: /new is only needed if the existing session was already pinned to the old PI runtime. Your session apparently wasn’t pinned that way, so after restart /status resolved the new runtime config directly.

The important line is this:

Runtime: OpenAI Codex

That means the harness switch worked.

The confusing line:

Model: openai/gpt-5.5 · 🔑 api-key (env: OPENAI_API_KEY)
#

is because the model prefix is still openai/..., so status sees your old OPENAI_API_KEY env var and reports it as available auth for the OpenAI provider. It does not mean the runtime is PI. Provider/model and runtime are separate.

For native Codex, OpenClaw should prefer your openai-codex OAuth profile for the Codex app-server. If you want to be extra sure it never falls back to API key, remove OPENAI_API_KEY from Coolify after confirming you don’t need it for other OpenAI stuff.

You can also check:

/codex account

That should show the Codex-side account/rate-limit status.

civic grotto
#

/codex account

Account: available
Rate limits: chatgpt authentication required to read rate limits

lilac minnowBOT
#

⚠️ Agent couldn't generate a response. Note: some tool actions may have already been executed — please verify before retrying.

civic grotto
#

/codex account

Account: available
Rate limits: chatgpt authentication required to read rate limits

lilac minnowBOT
#

That’s not a failure.

Account: available = Codex app-server is reachable and sees some usable account/auth state.

Rate limits: chatgpt authentication required to read rate limits = the separate rate-limit probe couldn’t read ChatGPT plan/quota details. Annoying, but it doesn’t mean the harness switch failed.

Your real success signals are still:

Runtime: OpenAI Codex

and then a normal prompt works.

Try a fresh small test:

# 
/new
say "codex harness test ok"

If it replies normally, you’re done. If the reply errors with auth/API-key stuff, then paste openclaw status --all / recent logs. Otherwise I’d call this solved.

civic grotto
#

codex harness test ok

but still

Account: available
Rate limits: chatgpt authentication required to read rate limits

lilac minnowBOT
#

Yep, that’s fine. The actual harness test passed, so the setup is working.

That rate-limit line is just the /codex account helper failing to read quota/plan metadata:

Rate limits: chatgpt authentication required to read rate limits

It’s annoying, but not blocking. If Codex can answer and /status shows:

Runtime: OpenAI Codex

then you’re on the Codex harness.

I’d leave it alone unless you specifically need rate-limit visibility. If everything works, please mark the solution so Answer Overflow indexes it for the next person. 🎉

civic grotto
#

why does this say acp?

🧠 Model: openai/gpt-5.5 · 🔑 api-key (openai:default)
🧮 Tokens: 983 in / 126 out
🗄️ Cache: 99% hit · 101k cached, 0 new
📚 Context: 102k/272k (38%) · 🧹 Compactions: 0
🧵 Session: agent:main:telegram:group:-1003705610703:topic:1124 • updated just now
📌 Tasks: recently finished · acp · Context engine turn maintenance · No transcript changes were needed.
⚙️ Execution: direct · Runtime: OpenAI Codex · Think: medium · Text: low
👥 Activation: always · 🪢 Queue: collect (depth 0)```
lilac minnowBOT
#

That acp is not your main harness.

It’s this line:

📌 Tasks: recently finished · acp · Context engine turn maintenance · No transcript changes were needed.

That’s the background task system reporting a recently finished maintenance task. It ran via ACP, probably because the context engine / maintenance path uses task records.

Your actual chat/runtime line is this:

⚙️ Execution: direct · Runtime: OpenAI Codex

That means your normal replies are using the native Codex harness, not ACP.

civic grotto
#

i dont remember settings any acp up what is it used for usually?

lilac minnowBOT
#

You probably didn’t set it up manually — fresh installs usually include the bundled acpx ACP backend.

ACP = Agent Client Protocol. In OpenClaw it’s mainly used for:

  • /acp spawn claude → run Claude Code as an external harness
  • /acp spawn codex → run Codex via ACP fallback path
  • Gemini/OpenCode/Cursor/Copilot-style external harness sessions
  • background task records for those external sessions

But your normal chat is not using ACP here. This is the important line:

Runtime: OpenAI Codex

The acp you saw was only in:

civic grotto
#

if a task is over how do i know what it was used for?

lilac minnowBOT
#

Use the task ledger.

In chat:

/tasks

That shows tasks linked to the current session, including recently completed ones.

From the VPS CLI:

openclaw tasks list
openclaw tasks list --runtime acp
openclaw tasks show <task-id-or-run-id-or-session-key>
#

list tells you the task id/runtime/status/title, and show is where you see what it was tied to: session key, timing, runtime, status, and details like “Context engine turn maintenance”.

One caveat: completed task records are retained for about 7 days, then pruned. So for old tasks, you may need logs instead:

openclaw logs --limit 500

Docs: https://docs.openclaw.ai/automation/tasks

civic grotto
#

what if logs now say no openai api key?

lilac minnowBOT
#

If logs say “No OpenAI API key”, first check which path emitted it.

For your current setup, this can be harmless:

  • openai/gpt-5.5 + Runtime: OpenAI Codex = native Codex harness
  • Codex harness should use your openai-codex OAuth/account
  • OPENAI_API_KEY is only needed for direct OpenAI API paths

So if these are still true:

/status -> Runtime: OpenAI Codex
/codex account -> Account: available
normal message works

then you’re fine. It’s probably just some OpenAI-provider/status/model-probe/tool path noticing there’s no direct API key.

#

It matters if normal replies start failing. Then check:

openclaw models list --provider openai-codex
openclaw status --all

and paste the exact “no API key” log line, because the fix depends on whether it came from direct openai/*, Codex app-server auth, image/TTS, or a model probe.

civic grotto
#

u sure?

lilac minnowBOT
#

Yes — with one caveat: I’m sure the harness is correct if /status says:

Runtime: OpenAI Codex

OpenClaw’s docs explicitly split these paths:

  • openai/gpt-* + normal PI runtime = direct OpenAI API key path
  • openai-codex/gpt-* = Codex OAuth through PI
  • openai/gpt-5.5 + agentRuntime.id: "codex" = native Codex app-server harness, expected status Runtime: OpenAI Codex (docs.openclaw.ai)

What I’m not 100% sure about without the exact log line is which component is complaining about the missing API key. If normal replies work, it’s likely some side path/probe/tool checking direct openai/* auth, not the Codex harness turn itself.

So:

# 
Runtime: OpenAI Codex + normal replies work = good

If an actual reply fails, paste the exact log around “no OpenAI API key”:

openclaw logs --tail 200 | grep -C3 -i "api key"

That’ll tell us whether it’s the main turn, model probe, image/TTS, or something else.

civic grotto
#

so why is it not working then without the api key?

lilac minnowBOT
#

Yeah — you found the caveat. I was too loose earlier.

For native Codex harness, openai/gpt-5.5 does not automatically mean “use my openai-codex OAuth profile”. The Codex app-server auth order is basically:

  1. explicit openai-codex auth profile bound to the run/session
  2. existing Codex/ChatGPT account in the app-server
  3. fallback CODEX_API_KEY / OPENAI_API_KEY

So if removing OPENAI_API_KEY breaks it, your run was probably still falling through to the API-key fallback instead of using the Codex OAuth profile.

Try pinning the Codex auth profile explicitly:

/model openai/gpt-5.5@openai-codex:default --runtime codex

If your profile id isn’t openai-codex:default, find it with:

# 
openclaw models status --plain
# or
openclaw models auth order get --provider openai-codex

Then use that id after the @.

Alternative: if you just want subscription auth and don’t care about native harness, use:

openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id pi

But for native Codex harness without API key, you need the openai-codex profile actually pinned/forwarded.

civic grotto
#

are you sure? docs didnt mention this right?

#

do i have to unset the api or something?

lilac minnowBOT
#

You’re right to challenge that. I checked again: the docs do mention the concept, but they don’t make the practical behavior super clear.

Docs say native Codex auth order is:

  1. explicit OpenClaw openai-codex auth profile
  2. existing Codex/ChatGPT app-server account
  3. CODEX_API_KEY, then OPENAI_API_KEY

But they don’t clearly say “after openclaw models auth login --provider openai-codex, openai/gpt-5.5 + agentRuntime.id=codex will automatically use that OAuth profile.”

And based on your test — works with API key, fails without — it sounds like 2026.4.26 is falling through to the API-key fallback instead of forwarding the OAuth profile automatically. So my earlier “you’re fine” was too confident. Sorry, that’s on me.

Practical options:

Most reliable subscription route:

# 
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id pi

That uses Codex OAuth/subscription, but not native Codex harness.

Native Codex harness route:

openai/gpt-5.5 + agentRuntime.id codex

…but on your version it may currently still need either an explicit bound Codex auth profile or the API-key fallback.

I’d file this as a docs/behavior issue: https://github.com/openclaw/openclaw/issues

#

Include: OpenClaw 2026.4.26, Coolify/VPS, Runtime: OpenAI Codex, works with OPENAI_API_KEY, fails without it despite openai-codex OAuth login.

#

No — you don’t have to unset it just to make OpenClaw run.

But if your goal is “make sure I’m not spending OpenAI API credits”, then yes, leaving OPENAI_API_KEY around makes it harder to prove what’s happening.

Given your test:

  • works with OPENAI_API_KEY
  • breaks without it

…I’d assume native Codex harness on 2026.4.26 is still relying on the API-key fallback in your setup.

So safest choices:

A) Keep native Codex harness working

# leave OPENAI_API_KEY set for now
#

Works, but may use API credits.

B) Force subscription/OAuth route

openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
openclaw config set agents.defaults.agentRuntime.id pi
openclaw gateway restart

This uses Codex OAuth/subscription route, but not native Codex harness.

If you want to test cleanly, remove OPENAI_API_KEY in Coolify, restart, and try option B. For option A, I’d keep the key until the native harness OAuth behavior is clarified/fixed.

civic grotto
lilac minnowBOT
#

You’re right — that doc quote is exactly why I originally expected this to work without OPENAI_API_KEY.

So correction/clarification:

  • openai/gpt-5.5 + agentRuntime.id=codex is supposed to be the native Codex app-server harness route
  • docs say GPT-5.5 there is subscription/OAuth-only
  • if it only works when OPENAI_API_KEY exists, that smells like either:
    1. the error is coming from some side path/probe, not the actual Codex turn, or
    2. a 2026.4.26 bug/docs mismatch where the native Codex harness is not selecting/forwarding your openai-codex OAuth profile correctly and falls back to API key

I’d test cleanly:

# remove OPENAI_API_KEY in Coolify, redeploy/restart gateway
openclaw models status --plain
openclaw models auth order get --provider openai-codex
# 
openclaw models list --provider openai-codex

Then in chat:

/status
/codex account
say "codex no api key test"

If /status still says Runtime: OpenAI Codex but the test fails with “no OpenAI API key”, I’d file that as a bug/docs mismatch: https://github.com/openclaw/openclaw/issues

Include that exact docs quote, OpenClaw 2026.4.26, and the failing log.

civic grotto
#

setting a random str to the env var did the trick

lilac minnowBOT
#

Ahh, interesting — nice find.

So for this setup, the code path apparently only needs OPENAI_API_KEY to be present, but the native Codex harness is not actually using that value for billing/auth. A dummy value satisfying the env check is a pretty good signal that your real auth is coming from Codex/OAuth.

I’d still treat that as a bug/rough edge: openai/gpt-5.5 + agentRuntime.id=codex shouldn’t require a dummy OPENAI_API_KEY if Codex OAuth is present.

If you file it, include:

  • OpenClaw 2026.4.26
  • Coolify/VPS
  • model openai/gpt-5.5
  • agents.defaults.agentRuntime.id=codex
  • openai-codex OAuth completed
  • missing OPENAI_API_KEY fails
  • dummy OPENAI_API_KEY=random-string works

That’s actually useful repro detail. 🦐

civic grotto
#

so i do need to unset the key?

lilac minnowBOT
#

Yes — if your goal is avoid API credit usage, unset the real key.

But because of that env-check bug/rough edge, replace it with a dummy placeholder instead of leaving it empty:

OPENAI_API_KEY=dummy

or whatever random string you tested.

Then restart/redeploy Coolify and verify:

/status

You want:

# 
Runtime: OpenAI Codex

and if a normal prompt works with the dummy key, then it can’t be billing through your real API key. That’s the safest setup until the env-check behavior is fixed.

civic grotto
#

what if tts or something needs a key how will i know?

lilac minnowBOT
#

You’ll know because that specific feature will fail and the log will name the surface.

Examples:

  • TTS / realtime voice / STT: OpenAI speech paths still use direct OpenAI API auth and fall back to OPENAI_API_KEY. With OPENAI_API_KEY=dummy, they’ll likely fail with auth/401 when used.
  • Image generation: OpenAI image generation can use Codex OAuth if openai-codex OAuth is configured, so that one may still work without a real API key.
  • Main chat: if Runtime: OpenAI Codex and replies work with dummy key, it’s not using your real API key.

Quick way to check voice/TTS:

/tts status

If you actually use OpenAI TTS, make a small test and watch logs:

# 
openclaw logs --tail 200 | grep -iE "tts|speech|openai|api key|401|auth"

If TTS breaks and you want it, either:

  1. use a non-OpenAI TTS provider, or
  2. set a real key specifically for TTS config instead of the global env var.

For your “don’t spend API credits on chat” goal: keep global OPENAI_API_KEY dummy, then only add real keys to the specific features you knowingly want to bill.

civic grotto
#

ok makes sense. check github to see if others have had similar problems

lilac minnowBOT
#

I checked GitHub. I didn’t find an exact OpenClaw issue for “native Codex harness needs a dummy OPENAI_API_KEY even with openai-codex OAuth”, but I did find several nearby openai-codex/OAuth regressions:

  • openai-codex provider failures since 2026.4.5 involving Cloudflare / missing OAuth scope. (github.com)
  • Proxy/env-related openai-codex runtime failures where OAuth login was healthy but runtime requests still failed. (github.com)
  • An OpenAI Codex CLI issue where a path required OPENAI_API_KEY even when it shouldn’t — not OpenClaw, but very similar “env var presence check” shape. (github.com)

So your exact dummy-env workaround sounds like a new or underreported OpenClaw bug/rough edge, not something already clearly tracked.

Good issue title:

Native Codex harness requires dummy OPENAI_API_KEY despite openai-codex OAuth

Include:

  • OpenClaw 2026.4.26
  • Coolify/VPS
GitHub
openai-codex provider broken since 2026.4.5 — Cloudflare challeng...

Bug Description The openai-codex provider fails on all models (gpt-5.4, gpt-5.3-codex, gpt-5.2) since approximately version 2026.4.5. Two stacked issues prevent any request from completing. Environ...

GitHub
openai-codex runtime requests can ignore proxy env unless NODE_USE_...

Summary openai-codex runtime requests can fail in proxy-only environments even when: ChatGPT Plus OAuth login succeeds openclaw models status shows a healthy openai-codex profile the same machine c...

GitHub
Bug: Quiet mode requires OPENAI_API_KEY even when using other provi...

Bug Description When using non-OpenAI providers (such as OpenRouter), the CLI’s quiet mode (-q) still requires the OPENAI_API_KEY to be set, even though it is not needed. Steps to Reproduce Set the...

civic grotto
#

⚠️ All models are temporarily rate-limited. Please try again in a few minutes.

I keep getting this now

Even though my subscription limits are solid when I check online

#

⚠️ All models are temporarily rate-limited. Please try again in a few minutes.

I keep getting this now

Even though my subscription limits are solid when I check online

@lilac minnow

civic grotto
#

2026-Apr-30 01:13:11
2026-04-30T01:13:11.688+00:00 [agent/embedded] embedded run failover decision: runId=f23b1ebe-7c00-441b-a3df-e00cc7238019 stage=prompt decision=surface_error reason=rate_limit from=openai/gpt-5.5 profile=- rawError=Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:11
2026-04-30T01:13:11.690+00:00 [diagnostic] lane task error: lane=main durationMs=9709 error="Quota exceeded. Check your plan and billing details."
2026-Apr-30 01:13:11
2026-04-30T01:13:11.691+00:00 [diagnostic] lane task error: lane=session:agent:main:telegram:direct:367989403 durationMs=9710 error="Quota exceeded. Check your plan and billing details."
2026-Apr-30 01:13:11
2026-04-30T01:13:11.695+00:00 [model-fallback/decision] model fallback decision: decision=candidate_failed requested=openai/gpt-5.5 candidate=openai/gpt-5.5 reason=rate_limit next=none detail=Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:11
2026-04-30T01:13:11.727+00:00 Embedded agent failed before reply: Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:12
2026-04-30T01:13:12.037+00:00 [telegram] sendMessage ok chat=367989403 message=1089

⚠️ All models are temporarily rate-limited. Please try again in a few minutes.

I keep getting this now

Even though my subscription limits are solid when I check online

@lilac minnow

#

also openclaw doctor --fix gives me this:
│
◇ State integrity ────────────────────────────────────────────────────╮
│ │
│ - 4/5 recent sessions are missing transcripts. │
│ Verify sessions in store: openclaw sessions --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" │
│ Preview cleanup impact: openclaw sessions cleanup --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" --dry-run │
│ Prune missing entries: openclaw sessions cleanup --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" --enforce │
│ --fix-missing │
│ - Found 1 orphan transcript file in │
│ /data/.openclaw/agents/main/sessions. │
│ These .jsonl files are no longer referenced by sessions.json, so │
│ they are not part of any active session history. │
│ Doctor can archive them safely by renaming each file to │
│ *.deleted.<timestamp>. │
│ Examples: a32130f1-fa47-4718-8703-98f8390691fb.trajectory.jsonl │
│ │
├──────────────────────────────────────────────────────────────────────╯
│
◇ Doctor changes ─────────────────────────────────────────────────╮
│ │
│ - Archived 1 orphan transcript file in │
│ /data/.openclaw/agents/main/sessions as .deleted timestamped │
│ backups. │

civic grotto
#

2026-Apr-30 01:13:11
2026-04-30T01:13:11.688+00:00 [agent/embedded] embedded run failover decision: runId=f23b1ebe-7c00-441b-a3df-e00cc7238019 stage=prompt decision=surface_error reason=rate_limit from=openai/gpt-5.5 profile=- rawError=Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:11
2026-04-30T01:13:11.690+00:00 [diagnostic] lane task error: lane=main durationMs=9709 error="Quota exceeded. Check your plan and billing details."
2026-Apr-30 01:13:11
2026-04-30T01:13:11.691+00:00 [diagnostic] lane task error: lane=session:agent:main:telegram:direct:367989403 durationMs=9710 error="Quota exceeded. Check your plan and billing details."
2026-Apr-30 01:13:11
2026-04-30T01:13:11.695+00:00 [model-fallback/decision] model fallback decision: decision=candidate_failed requested=openai/gpt-5.5 candidate=openai/gpt-5.5 reason=rate_limit next=none detail=Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:11
2026-04-30T01:13:11.727+00:00 Embedded agent failed before reply: Quota exceeded. Check your plan and billing details.
2026-Apr-30 01:13:12
2026-04-30T01:13:12.037+00:00 [telegram] sendMessage ok chat=367989403 message=1089

⚠️ All models are temporarily rate-limited. Please try again in a few minutes.

I keep getting this now

Even though my subscription limits are solid when I check online

@lilac minnow

#

also openclaw doctor --fix gives me this:
│
◇ State integrity ────────────────────────────────────────────────────╮
│ │
│ - 4/5 recent sessions are missing transcripts. │
│ Verify sessions in store: openclaw sessions --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" │
│ Preview cleanup impact: openclaw sessions cleanup --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" --dry-run │
│ Prune missing entries: openclaw sessions cleanup --store │
│ "/data/.openclaw/agents/main/sessions/sessions.json" --enforce │
│ --fix-missing │
│ - Found 1 orphan transcript file in │
│ /data/.openclaw/agents/main/sessions. │
│ These .jsonl files are no longer referenced by sessions.json, so │
│ they are not part of any active session history. │
│ Doctor can archive them safely by renaming each file to │
│ *.deleted.<timestamp>. │
│ Examples: a32130f1-fa47-4718-8703-98f8390691fb.trajectory.jsonl │
│ │
├──────────────────────────────────────────────────────────────────────╯
│
◇ Doctor changes ─────────────────────────────────────────────────╮
│ │
│ - Archived 1 orphan transcript file in │
│ /data/.openclaw/agents/main/sessions as .deleted timestamped │
│ backups. │

civic grotto
#

do these still work for harness migration in 2026.5.7?

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.agentRuntime.id codex
openclaw config set agents.defaults.agentRuntime.fallback none

lilac minnowBOT
#

Short answer: first one yes, the other two are legacy/not the right place in 2026.5.7.

For Codex harness + subscription auth, use canonical OpenAI model refs and enable the bundled Codex plugin:

openclaw models auth login --provider openai-codex
openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart

If your config has plugins.allow, also add codex there or the plugin may stay blocked.

agents.defaults.agentRuntime.id codex is now a stale whole-agent runtime pin; current docs say whole-agent runtime keys are ignored and doctor --fix removes/migrates them. agents.defaults.agentRuntime.fallback none is also legacy/invalid for the current runtime policy shape.

If you specifically want “fail closed if Codex is unavailable” instead of auto/fallback behavior, set runtime policy on the provider/model, e.g. model-scoped:

civic grotto
#

i am already logged in via that method

lilac minnowBOT
#

Perfect — then skip the login step. The config side is the important part:

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart

And remove/ignore these old ones:

openclaw config unset agents.defaults.agentRuntime
# or run:
openclaw doctor --fix

If you want strict Codex-only / no PI fallback, add the model-scoped runtime policy:

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

Then /new or /reset the chat before testing, because existing sessions can keep old route state.

Also: what does openclaw --version show? 2026.5.7 should match this behavior, but I want to sanity-check the exact build before we chase ghosts. 🦞

civic grotto
#

so right now this is the way to switch harness to codex from pi? u sure? can you give me docs refs (that you read to confirm)

lilac minnowBOT
#

Yep — I’m sure for current docs/main, with one nuance:

To switch normal OpenAI agent turns from PI to native Codex harness, the key is:

openclaw config set plugins.entries.codex.enabled true
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart

Then /new or /reset the existing chat before testing.

The old commands you pasted are not the current way:

openclaw config set agents.defaults.agentRuntime.id codex
# 
openclaw config set agents.defaults.agentRuntime.fallback none

Current docs say whole-agent runtime pins like agents.defaults.agentRuntime are legacy/ignored. Runtime policy now belongs on the provider or model, not the whole agent.

Docs I checked:

So if you want the strict/no-PI version, use either provider-scoped:

openclaw config set models.providers.openai.agentRuntime '{"id":"codex"}' --strict-json
#

or model-scoped:

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

And cleanup old state with:

openclaw doctor --fix
civic grotto
#

│
◇ Model auth ───────────────────────────────────────────────────────────╮
│ │
│ - openai-codex:aaqilaziz96@hotmail.com: expiring (21h) — Re-auth via │
│ openclaw models auth login --provider openai-codex or openclaw │ │ configure. │
│ │
├────────────────────────────────────────────────────────────────────────╯

if i login with another account rn, itll auto switch when expired?

lilac minnowBOT
#

Yes, if it’s in the resolved auth order and the session isn’t user-pinned to the old profile.

The important bit: merely logging into another account creates another openai-codex:* profile, but I’d explicitly check/set order instead of trusting whatever order you happen to get.

openclaw models auth order get --provider openai
openclaw models status --probe

If both profiles show up, set the preferred order, e.g.:

openclaw models auth order set --provider openai \
  openai-codex:new@example.com \
  openai-codex:aaqilaziz96@hotmail.com
#

Or put the current one first and the new one second if you want it used only after expiry/limit:

openclaw models auth order set --provider openai \
  openai-codex:aaqilaziz96@hotmail.com \
  openai-codex:new@example.com

Docs I checked:

So: auto switch on expiry/limit is expected only through auth order / automatic selection. If you used something like /model openai/gpt-5.5@openai-codex:aaqilaziz96@hotmail.com, that’s user-pinned and you should unpin/switch it.

civic grotto
lilac minnowBOT
#

The usage line is provider-level, so it doesn’t tell you which profile is currently selected. Check the resolved auth order / session pin.

Run:

openclaw models auth order get --provider openai
openclaw models auth list --provider openai-codex
openclaw models status --probe

Rules of thumb:

  • If auth order get --provider openai lists one first, that’s the one OpenClaw will try first for openai/gpt-* Codex harness turns.
  • If there’s no explicit order, OpenClaw uses its resolved/default order; models status --probe is the best sanity check.
  • If the current chat was pinned with /model openai/gpt-5.5@openai-codex:..., that session is locked to that profile. Use /model or /new//reset to get back to automatic selection.

If you want to force ev@gmail.com first:

# 
openclaw models auth order set --provider openai \
  openai-codex:ev@gmail.com \
  openai-codex:aa@hotmail.com

If you want aa@hotmail.com first and ev@gmail.com as backup:

openclaw models auth order set --provider openai \
  openai-codex:aa@hotmail.com \
  openai-codex:ev@gmail.com

Docs ref: models status --probe shows profile probe status/exclusions, and auth order controls which provider credential order is used: https://docs.openclaw.ai/cli/models

civic grotto
#

openclaw config set models.providers.openai.agentRuntime '{"id":"codex"}' --strict-json

also curious how to switch back to pi

lilac minnowBOT
#

Yep. To force Codex for OpenAI agent turns:

openclaw config set models.providers.openai.agentRuntime '{"id":"codex"}' --strict-json
openclaw gateway restart

To switch back to PI, set the same provider runtime to pi:

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

Or remove the explicit runtime policy and go back to auto/default behavior:

# 
openclaw config unset models.providers.openai.agentRuntime
openclaw gateway restart

After switching either way, use /new or /reset in the chat/thread before testing, otherwise the existing session can keep old route/session state.

Verify with /status:

  • Codex path should show Runtime: OpenAI Codex
  • PI path should show PI runtime / no Codex runtime

Docs ref: Codex harness says direct OpenAI API through PI is provider/model agentRuntime.id: "pi", while Codex fail-closed is provider/model agentRuntime.id: "codex": https://docs.openclaw.ai/plugins/codex-harness

civic grotto
lilac minnowBOT
#

Ah — good catch. My previous --provider openai command was wrong for the CLI path. Sorry, that error is real.

For two openai-codex:* OAuth profiles, use the openai-codex provider in the auth-order CLI:

openclaw models auth order get --provider openai-codex

Set ev@gmail.com first:

openclaw models auth order set --provider openai-codex \
  openai-codex:ev@gmail.com \
  openai-codex:aa@hotmail.com

Or keep aa@hotmail.com first with ev@gmail.com as backup:

# 
openclaw models auth order set --provider openai-codex \
  openai-codex:aa@hotmail.com \
  openai-codex:ev@gmail.com

Then restart/reset the session if you want a clean test:

openclaw gateway restart

and in chat:

/new
# 
/status

Why the mismatch: docs say the newer OpenAI/Codex routing prefers OpenAI model refs like openai/gpt-*, but the stored OAuth profile provider is still openai-codex, and the models auth order CLI validates that the --provider matches the actual profile provider. So for these profile IDs, --provider openai-codex is the right command.

civic grotto
#

openclaw config set models.providers.openai.agentRuntime '{"id":"codex"}' --strict-json

🦞 OpenClaw 2026.5.7 (eeef486) — Your config is valid, your assumptions are not.

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

lilac minnowBOT
#

That error means config set is trying to create a custom models.providers.openai entry, and custom provider entries require baseUrl. So don’t use that provider-scoped command on a stock/bundled OpenAI provider config.

Use the model-scoped runtime policy instead — it doesn’t require defining models.providers.openai:

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

To switch that exact model back to PI:

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

To remove the explicit override and go back to auto/default routing:

# 
openclaw config unset 'agents.defaults.models.openai/gpt-5.5.agentRuntime'
openclaw gateway restart

Then /new or /reset before testing.

I should’ve recommended the model-scoped command first — the docs say provider/model policy, but the provider-scoped CLI form collides with the custom-provider schema unless you already have a full models.providers.openai object with baseUrl. 🦞

civic grotto
#

openclaw config set models.providers.openai.agentRuntime '{"id":"pi"}' --strict-json

🦞 OpenClaw 2026.5.7 (eeef486) — Half butler, half debugger, full crustacean.

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

lilac minnowBOT
#

Yep, same root cause: models.providers.openai.* is the custom provider config surface, and if you create/touch models.providers.openai, schema requires a full provider object including baseUrl.

So don’t use this:

openclaw config set models.providers.openai.agentRuntime '{"id":"pi"}' --strict-json

Use model-scoped runtime instead:

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

For Codex:

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

If that failed provider command left a partial config behind, remove it:

openclaw config unset models.providers.openai
openclaw config validate

Then /new or /reset before testing. Sorry — this is exactly the sharp edge between “provider/model runtime policy” in docs and the CLI schema for bundled vs custom providers.

civic grotto
#

🦞 OpenClaw 2026.5.7 (eeef486)
⏱️ Uptime: gateway 50s · system 37m 10s
🧠 Model: openai-codex/gpt-5.5 · 🔑 oauth (openai-codex:evtkruys@gmail.com (evtkruys@gmail.com))
🧮 Tokens: 19k in / 210 out
🗄️ Cache: 53% hit · 22k cached, 0 new
📚 Context: 22k/272k (8%) · 🧹 Compactions: 0
📊 Usage: 5h 100% left ⏱4h 59m · Week 100% left ⏱6d 23h
🧵 Session: agent:main:telegram:group:-1003705610703:topic:1124 • updated 1m ago
⚙️ Execution: direct · Runtime: OpenClaw Pi Default · Think: medium · Text: low
👥 Activation: always · 🪢 Queue: steer (depth 0)

026-May-11 14:38:04
Embedded agent failed before reply: Requested agent harness "codex" is not registered.
2026-May-11 14:38:36
2026-05-11T14:38:36.316+00:00 [plugins] memory-core: managed dreaming cron could not be reconciled (cron service unavailable).
2026-May-11 14:38:36
2026-05-11T14:38:36.319+00:00 [diagnostic] lane task error: lane=cron-nested durationMs=15 error="Error: Requested agent harness "codex" is not registered."
2026-May-11 14:38:36
2026-05-11T14:38:36.320+00:00 [diagnostic] lane task error: lane=session:agent:main:cron:1e5277a3-2c0b-4327-8ef7-9b97f14b383e:run:9bdb03e3-c9be-4e56-bd12-477f4a59f63e durationMs=16 error="Error: Requested agent harness "codex" is not registered."
2026-May-11 14:38:41
2026-05-11T14:38:41.204+00:00 [diagnostic] lane task error: lane=cron-nested durationMs=9 error="Error: Requested agent harness "codex" is not registered."
2026-May-11 14:38:41
2026-05-11T14:38:41.206+00:00 [diagnostic] lane task error: lane=session:agent:main:cron:6347b8be-82cc-413d-b2cb-1b04973dd184:run:85e5236d-483d-4202-9640-51e276ae14ec durationMs=12 error="Error: Requested agent harness "codex" is not registered."

lilac minnowBOT
#

This confirms the Codex plugin/harness is not loaded:

Requested agent harness "codex" is not registered
Runtime: OpenClaw Pi Default

Also this is still legacy route state:

Model: openai-codex/gpt-5.5

Current Codex harness setup wants openai/gpt-*, not openai-codex/gpt-*.

Do this cleanup path:

# 
# 1) repair legacy openai-codex/* model refs + stale runtime pins
openclaw doctor --fix

# 2) enable the bundled codex plugin
openclaw config set plugins.entries.codex.enabled true

# 3) if you have a restrictive plugin allowlist, include codex
openclaw config get plugins.allow --json

If that last command prints a non-empty list and it doesn’t include codex, add it. Easiest patch form:

openclaw config patch --stdin <<'JSON5'
{
# 
  plugins: {
    allow: ["codex"]
  }
}
JSON5

Careful: if plugins.allow already contains other plugins, don’t replace it with only codex; include the existing entries too.

Then:

openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart
openclaw plugins list --enabled | grep codex
#

In the chat/thread:

/new
/status
/codex status

Expected: /status should move from Runtime: OpenClaw Pi Default to Runtime: OpenAI Codex.

Docs I’m anchoring this to: Codex troubleshooting says if OpenClaw uses PI, check model ref is openai/gpt-*, Codex plugin is installed/enabled, and plugins.allow doesn’t exclude codex; legacy openai-codex/* should be repaired with doctor --fix: https://docs.openclaw.ai/plugins/codex-harness#troubleshooting

civic grotto
#

but its running on pi

lilac minnowBOT
#

Right — exactly. It’s using Codex OAuth auth, but still executing through PI.

These are separate layers:

Model/Auth: openai-codex/gpt-5.5 + oauth profile
Runtime: OpenClaw Pi Default

So your subscription login is being used, but the Codex harness is not active. The smoking gun is:

Requested agent harness "codex" is not registered

That means setting agentRuntime: codex can’t work yet because the codex plugin did not load/register the harness.

#

Fix order:

openclaw config set plugins.entries.codex.enabled true
openclaw config get plugins.allow --json
openclaw plugins list --enabled | grep codex

If plugins.allow is non-empty and doesn’t include codex, add codex to that existing list. Then:

openclaw doctor --fix
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart

Then in the chat:

# 
/new
/status

Only after openclaw plugins list --enabled | grep codex shows the plugin loaded should you force model-scoped runtime:

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

If you force it before the plugin is registered, you’ll keep getting Requested agent harness "codex" is not registered.

civic grotto
#

ok so how do i keep it to pi?

lilac minnowBOT
#

To keep it on PI, don’t force codex anywhere. Your current /status already shows PI:

Runtime: OpenClaw Pi Default

Clean/force PI like this:

# remove legacy whole-agent runtime pins
openclaw config unset agents.defaults.agentRuntime

# remove the broken/partial provider override if it exists
openclaw config unset models.providers.openai

# use canonical OpenAI model ref, but force PI for this model
# 
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw config set agents.defaults.models '{"openai/gpt-5.5":{"agentRuntime":{"id":"pi"}}}' --strict-json --merge

openclaw gateway restart

Optional: if you don’t want the Codex harness loaded at all:

openclaw config set plugins.entries.codex.enabled false
openclaw gateway restart

Then in the chat/thread:

# 
/new
/status

Expected: Runtime: OpenClaw Pi Default / PI runtime.

Using an openai-codex:* OAuth profile for auth can still be okay — that’s auth. The thing that decides PI vs Codex harness is the runtime policy.

civic grotto
#

openclaw config set plugins.entries.codex.enabled false is the thing that caused the error. even though it was on pi

lilac minnowBOT
#

Yep — that makes sense. You were running on PI, but your config/session still had something that requested Codex:

  • legacy model ref: openai-codex/gpt-5.5, or
  • model-scoped agentRuntime: { id: "codex" }, or
  • old whole-agent/session runtime pin

When you disabled the Codex plugin, that hidden/stale Codex request could no longer resolve, so it failed with:

Requested agent harness "codex" is not registered

To keep PI safely, do this order:

# remove explicit/stale codex runtime config
# 
openclaw config unset agents.defaults.agentRuntime
openclaw config unset 'agents.defaults.models.openai/gpt-5.5.agentRuntime'
openclaw config unset 'agents.defaults.models.openai-codex/gpt-5.5'

# use canonical model ref + explicit PI runtime
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw config set agents.defaults.models '{"openai/gpt-5.5":{"agentRuntime":{"id":"pi"}}}' --strict-json --merge

# now it is safe to leave codex disabled
openclaw config set plugins.entries.codex.enabled false
openclaw config validate
openclaw gateway restart

Then in the thread:

# 
/new
/status

Expected: model should be openai/gpt-5.5 or similar, and runtime should stay PI.

Key thing: don’t keep openai-codex/gpt-* as the model ref if your goal is PI. That legacy prefix carries Codex routing baggage; use openai/gpt-* plus agentRuntime: { id: "pi" }.

civic grotto
#

wait isnt it openai/gpt-5.5 only for codex?

lilac minnowBOT
#

No — openai/gpt-5.5 is the canonical model ref, not “Codex-only”.

Think of it as two separate knobs:

model ref: openai/gpt-5.5
runtime:   codex OR pi

In current OpenClaw:

  • openai/gpt-5.5 + Codex plugin/auto runtime → Codex harness
  • openai/gpt-5.5 + agentRuntime: { id: "pi" } → PI
  • openai-codex/gpt-5.5 → legacy route; don’t use for new config

So for PI, the shape is still:

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

For Codex harness, same model ref, different runtime:

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

Docs phrase it as: openai/gpt-5.5 is the model ref, codex is the runtime. The old openai-codex/gpt-* prefix is legacy and doctor --fix rewrites it.

civic grotto
#

openai-codex is for using codex subscription

lilac minnowBOT
#

Yes — openai-codex is for the Codex subscription auth/profile.

The confusing part is that there are two different things with similar names:

openai-codex:ev@gmail.com   = auth profile / subscription login ✅
openai-codex/gpt-5.5        = legacy model ref ⚠️
openai/gpt-5.5              = current canonical model ref ✅

So the modern setup is:

  • use openai-codex:* for the OAuth/subscription credential
  • use openai/gpt-5.5 as the model ref
  • choose runtime separately:
    • agentRuntime: { id: "codex" } → Codex harness
    • agentRuntime: { id: "pi" } → PI
#

That’s why /status can show auth like:

🔑 oauth (openai-codex:ev@gmail.com)

while runtime still says:

Runtime: OpenClaw Pi Default

Subscription auth and execution harness are separate knobs.

civic grotto
#

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

🦞 OpenClaw 2026.5.7 (eeef486)
I'm the assistant your terminal demanded, not the one your sleep schedule requested.

Error: Config validation failed: agents.defaults.models.openai/gpt-5.5: Unrecognized key: "agentRuntime"

lilac minnowBOT
#

You’re right — for 2026.5.7 specifically, my model-scoped command is wrong. That schema does not accept agents.defaults.models[...].agentRuntime yet. Sorry, I mixed current docs/main behavior with the released build you’re on.

For 2026.5.7, use the whole-agent runtime knob:

To keep PI:

openclaw config set agents.defaults.agentRuntime.id pi
openclaw config unset agents.defaults.agentRuntime.fallback
openclaw gateway restart

To use Codex harness on 2026.5.7:

openclaw config set plugins.entries.codex.enabled true
# 
openclaw config set agents.defaults.agentRuntime.id codex
openclaw config unset agents.defaults.agentRuntime.fallback
openclaw config set agents.defaults.model openai/gpt-5.5
openclaw gateway restart

Important bits:

  • agents.defaults.agentRuntime.fallback none is not supported anymore — remove it.
  • agents.defaults.models.{model}.agentRuntime is not valid in your 2026.5.7 build — that’s why you got Unrecognized key: "agentRuntime".
  • If you disable plugins.entries.codex.enabled false while agents.defaults.agentRuntime.id codex is still set, you’ll get Requested agent harness "codex" is not registered.

So for your current “stay on PI” goal, the clean command is:

# 
openclaw config set agents.defaults.agentRuntime.id pi
openclaw config unset agents.defaults.agentRuntime.fallback
openclaw config set plugins.entries.codex.enabled false
openclaw gateway restart

Then /new and /status; expected runtime is OpenClaw Pi Default.

narrow mangoBOT
civic grotto
#

How to set a fall back model to zai/glm-5.1 (when primary is OpenAI/codex OAuth with pi harness)

lilac minnowBOT
#

Use the fallback list, not a second primary.

For PI + Codex OAuth primary:

# make sure Codex OAuth is the primary route
openclaw config set agents.defaults.model.primary "openai-codex/gpt-5.5"

# add GLM as the text fallback
openclaw models fallbacks add "zai/glm-5.1"

# verify resolved primary + fallback chain/auth
openclaw models status

Make sure Z.AI auth exists first, otherwise fallback will just fail when it gets there:

# 
openclaw onboard --auth-choice zai-api-key
# or one of the region/plan-specific choices, e.g. zai-coding-global / zai-coding-cn

If you have agents.defaults.models set as an allowlist, also add GLM to it:

openclaw config set agents.defaults.models '{"zai/glm-5.1":{"alias":"GLM 5.1"}}' --strict-json --merge

Equivalent config shape is:

agents: {
  defaults: {
civic grotto
#

Zai is not Auth, that one is by API key

lilac minnowBOT
#

Yep — sorry, I used “auth” too broadly there. For Z.AI/GLM it’s API-key auth via ZAI_API_KEY, not OAuth.

So the shape is:

# put the API key somewhere the gateway can see it
openclaw onboard --auth-choice zai-api-key
# or set ZAI_API_KEY in the gateway env/config

openclaw config set agents.defaults.model.primary "openai-codex/gpt-5.5"
openclaw models fallbacks add "zai/glm-5.1"
openclaw models status

If you’re doing it directly in config, it’s basically:

# 
env: { ZAI_API_KEY: "sk-..." },
agents: {
  defaults: {
    model: {
      primary: "openai-codex/gpt-5.5",
      fallbacks: ["zai/glm-5.1"],
    },
  },
}

And if agents.defaults.models is set, merge GLM into that allowlist too.

civic grotto
#

Model provider zai not found

lilac minnowBOT
#

That means your config/session is still trying to use the zai provider, but this OpenClaw runtime doesn’t have that provider registered.

First thing: please paste:

openclaw --version
openclaw models status

Likely fixes:

  • If you’re switching to OpenAI subscription / Codex OAuth, set the model/provider to openai-codex, not zai:
openclaw models auth login --provider openai-codex
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
openclaw models list --provider openai-codex