codex harness | Friends of the Crustacean 🦞🤝 | Page 1

main citrus Apr 13, 2026, 3:31 PM

#

I'm trying to configure the new codex Harness runtime. Could you give me step-by-step instructions for setting it up and exactly what needs to go inside the config files?

frail sorrelBOT Apr 13, 2026, 3:31 PM

#

wicked sandBOT Apr 13, 2026, 3:33 PM

#

Assuming you mean the bundled Codex harness for embedded agent turns, here’s the clean setup.

Check the active config path and your version

openclaw --version
openclaw config file

Make sure these are true:

Node >= 22
recent OpenClaw build
Codex app-server 0.118.0+
Codex auth is visible to the gateway process (OPENAI_API_KEY, and optionally ~/.codex/auth.json / ~/.codex/config.toml)

Edit your active openclaw.json and put in this minimal config
(JSON5 style, not YAML)

#

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },

#

    },
  },
}

If you use plugins.allow, include codex too

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },

#

    },
  },
}

Optional, if you want Codex native approvals/sandbox policy

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {

#

            approvalPolicy: "on-request",
            sandbox: "workspace-write",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Restart and verify

openclaw gateway restart

#

openclaw status

Then in chat:

/codex status
/codex models

Important gotchas:

use codex/gpt-5.4, not openai/gpt-5.4
embeddedHarness.runtime: "codex" forces the Codex harness
fallback: "none" makes failures obvious instead of silently falling back to PI

Docs:

#

If you meant ACP Codex sessions instead of the embedded Codex harness, say that and I’ll paste the exact ACP config too.

main citrus Apr 13, 2026, 4:11 PM

#

I'm getting the following error even though I followed all the steps properly.

Requested agent harness "codex" is not registered and PI fallback is disabled

wicked sandBOT Apr 13, 2026, 4:12 PM

#

That error is actually pretty specific. OpenClaw sees embeddedHarness.runtime: "codex", but the Codex plugin never got registered. So this is usually plugin loading/config path/version, not auth.

Please paste these 5 outputs first:

openclaw --version
openclaw config file
openclaw gateway status
openclaw plugins inspect codex
openclaw config validate

Most common causes:

OpenClaw is too old and does not include the bundled Codex harness yet
You edited one config file, but the daemon is running with a different one
You have plugins.allow and it does not include codex

#

The gateway was not restarted after enabling the plugin

Your config should look like this:

{
  plugins: {
    // include allow only if you already use an allowlist
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {

#

    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

Quick things to try right now:

openclaw plugins enable codex

#

openclaw gateway restart
openclaw plugins list --enabled

You want codex to appear in the enabled plugin list.

Two useful interpretations of the output:

If openclaw plugins inspect codex says not found, you likely need to update OpenClaw
If openclaw config file and openclaw gateway status show different config paths, the daemon is reading the wrong file

Docs:

If you paste those 5 outputs plus your current config block, I can usually spot the issue pretty fast.

main citrus Apr 13, 2026, 9:56 PM

#

05:56:09 [gateway/channels] channel startup failed: Error: Requested agent harness "codex" is not registered and PI fallback is disabled.

#

@wicked sand im getting the following error

05:56:09 [gateway/channels] channel startup failed: Error: Requested agent harness "codex" is not registered and PI fallback is disabled.

wicked sandBOT Apr 13, 2026, 10:03 PM

#

Yep, same root cause. The gateway is trying to boot with runtime: "codex", but the Codex harness plugin never registered, so startup dies early.

First, please paste this one first:

openclaw --version

Then run these:

openclaw config file
openclaw gateway status
openclaw plugins inspect codex
openclaw plugins list --enabled
openclaw config validate

#

A few concrete things to check:

1. Config must include the plugin

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {

#

        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

2. If you use `plugins.allow`, `codex` must be in it

{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: { enabled: true },

#

    },
  },
}

3. Restart after changing config

openclaw gateway restart

4. If the gateway is stuck and you just need it to boot

Temporarily change this:

embeddedHarness: {

#

  runtime: "auto",
  fallback: "pi",
}

That should let the gateway come up while you verify whether the codex plugin is actually loading.

What the outputs will tell us

plugins inspect codex says not found → your OpenClaw build is likely too old, update first
config file and gateway status show different paths → you edited the wrong config
plugins list --enabled does not show codex → plugin is not enabled/allowlisted

Docs:

#

Paste the outputs plus your current plugins and agents.defaults blocks, and I’ll pinpoint it.

main citrus Apr 13, 2026, 10:22 PM

#

I'm running version 4.12. The config file shows fine. Gateway status shows fine. Plugins inspect codex shows a fine plugins list. Enable shows codex. Config validate returns okay. All the settings inside the config file are exactly as you pointed out. Still, the error persists.

wicked sandBOT Apr 13, 2026, 10:25 PM

#

If you’re on 2026.4.12 and all of that already checks out, I’m pretty suspicious this is a real regression, not you misconfiguring it.

One subtle but important thing:

openclaw plugins inspect codex needs to show status: loaded
enabled or installed alone is not enough.

Next checks I’d do:

openclaw plugins doctor
openclaw logs --follow

Then in another terminal:

#

openclaw gateway restart

Watch for anything mentioning:

codex
plugin load
register
runtime module
agent harness

Why I think this may be a bug:

the Codex extension registers its harness unconditionally when the plugin loads
so if config is valid, plugin is enabled, and you still get “codex is not registered”, the likely failure is:
1. the plugin is not actually loading at runtime, or
2. the daemon is still running stale code

#

I’d try updating first, because the Codex harness landed recently and there have been follow-up fixes:

pnpm add -g openclaw@latest
openclaw gateway restart

If you’re running from source instead:

git pull
pnpm install
pnpm build
openclaw gateway restart

Temporary workaround

#

If you just want the gateway to boot while debugging:

embeddedHarness: {
  runtime: "auto",
  fallback: "pi",
}

Or use:

model: "openai-codex/gpt-5.4"

That uses the Codex/OpenAI auth path through PI, not the native Codex harness, but it should stop startup from hard-failing.

#codex harness

1. Config must include the plugin

2. If you use plugins.allow, codex must be in it

3. Restart after changing config

4. If the gateway is stuck and you just need it to boot

What the outputs will tell us

Temporary workaround

2. If you use `plugins.allow`, `codex` must be in it