Using codex cli via openclaw | Friends of the Crustacean 🦞🤝 | Page 1

edgy wasp Apr 21, 2026, 8:57 PM

#

Is possible for openclaw agent to use openai codex cli to invoke codex for tasks? How to do this?

dark heraldBOT Apr 21, 2026, 8:57 PM

#

undone pantherBOT Apr 21, 2026, 8:57 PM

#

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

dark heraldBOT Apr 21, 2026, 8:57 PM

#

spice smeltBOT Apr 21, 2026, 8:59 PM

#

Yes.

There are two different Codex integrations, and the names are easy to mix up:

Run the actual Codex harness/CLI through OpenClaw
Use ACP:
- /acp doctor
- /acp spawn codex --bind here
- or /acp spawn codex --mode persistent --thread auto
- optional repo cwd: /acp spawn codex --bind here --cwd /absolute/path/to/repo
Fresh installs usually already have the bundled acpx backend enabled. First use may still fetch the Codex adapter.
Use Codex auth/models inside normal OpenClaw runs
That is the openai-codex/* route, which is not the Codex CLI harness.

If you want real Codex-run coding tasks, ACP is the one you want.

#

One important gotcha: ACP sessions are non-interactive, so if Codex needs to write files or run shell commands, set:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw gateway restart

Otherwise you can hit Permission prompt unavailable in non-interactive mode.

If instead you want OpenClaw’s embedded agent runtime to use Codex natively, that’s the bundled Codex harness (codex/*), not ACP.

Docs:

If you want, paste your openclaw --version plus whether you want:

#

ACP Codex session, or
embedded Codex harness

and I’ll give you the exact config block.

edgy wasp Apr 21, 2026, 9:27 PM

#

In webchat i got ACP error internal error when use /acp spawn codex

spice smeltBOT Apr 21, 2026, 9:29 PM

#

Hmm, that usually means the ACP backend failed, not that your command syntax was wrong.

A few concrete things to try:

First, paste your version
```
openclaw --version
```
In webchat, run
```
/acp doctor
```
Try this instead of bare /acp spawn codex

#

   /acp spawn codex --bind here

or

/acp spawn codex --mode oneshot --thread off

Why: bare /acp spawn codex can go through a thread-binding flow, and webchat may be choking there. --bind here / --thread off narrows that down fast.

If it still fails, grab the gateway log
```
openclaw logs --follow
```
then rerun the spawn and paste the ACP error lines.

Most common causes from the docs:

#

acpx backend missing/disabled
first-run Codex adapter fetch failed (npm/network issue)
permission prompt failure in non-interactive ACP sessions

If the log mentions permission prompt unavailable, fix with:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw gateway restart

Docs: https://docs.openclaw.ai/tools/acp-agents

If you paste:

openclaw --version
/acp doctor
the exact log line

#

I can usually tell you the exact fix pretty quickly.

edgy wasp Apr 21, 2026, 9:31 PM

#

Using /acp spawn codex via web chat i got this error ACP error (ACP_TURN_FAILED) Internal error

spice smeltBOT Apr 21, 2026, 9:32 PM

#

That narrows it down.

ACP_TURN_FAILED: Internal error means the ACP runtime got far enough to start the turn, then something inside the backend/harness blew up. The webchat message is just hiding the real cause.

I’d do this in order:

Paste your version
```
openclaw --version
```
Run ACP doctor
In webchat:
```
/acp doctor
```
or in CLI:

#

   openclaw acp doctor

Retry with the simplest spawn
```
/acp spawn codex --mode oneshot --thread off
```
Don’t start with bare /acp spawn codex in webchat, that can involve extra binding/thread behavior.
Grab the real error from logs
```
openclaw logs --follow
```
Then rerun the spawn and paste the ACP/Codex lines.

Most likely causes:

#

acpx backend not actually healthy
first-run Codex adapter fetch failed
Codex auth missing on the host
non-interactive permission prompt crash

If the logs mention permission prompt unavailable in non-interactive mode, fix with:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw gateway restart

If you paste:

openclaw --version
/acp doctor
10 to 20 lines from openclaw logs --follow

#

I can usually pinpoint it pretty fast.

Docs:

edgy wasp Apr 21, 2026, 9:39 PM

#

Codex is configured to use toml file non auth

spice smeltBOT Apr 21, 2026, 9:41 PM

#

Ah, that helps.

~/.codex/config.toml is fine. auth.json is not required. The important part is that the OpenClaw gateway/acpx process can see the same Codex config and any env vars it depends on.

That’s the part that often breaks.

A few key points:

If Codex works in your shell, but OpenClaw runs as a daemon/service, the gateway may not inherit the same env/HOME.
If your config.toml references something like OPENAI_API_KEY, the gateway service needs that too.

Best next test

Run the gateway in the same shell where Codex works, then retry:

openclaw gateway run

#

Then from webchat try:

/acp spawn codex --mode oneshot --thread off

If that works, the problem is almost certainly service env / HOME / file visibility, not ACP itself.

Also do these

Paste:
```
openclaw --version
```
Run:
```
/acp doctor
```

#

If the daemon is the problem

Put the needed env in:

~/.openclaw/.env

or enable shell env import in config:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },

#

  },
}

Then restart the gateway.

Small correction to my earlier note: for harness health, use /acp doctor in chat. openclaw acp is a different bridge command.

Docs:

If you want, paste:

openclaw --version
/acp doctor

#

whether OpenClaw is running as a daemon or foreground process

and I can narrow it down fast.

edgy wasp Apr 21, 2026, 9:49 PM

#

I started gateway from shell and now respond, is a problem of envirnoment?

spice smeltBOT Apr 21, 2026, 9:50 PM

#

Yep, that pretty much confirms it.

If it works when you start the gateway from your shell, but not when the background service/daemon runs, then it’s almost certainly an environment / HOME / PATH / file-visibility issue.

Most likely one of these:

the daemon does not inherit the env vars your shell has
the daemon is running as a different user, so ~/.codex/config.toml is not the same file
config.toml depends on env vars like OPENAI_API_KEY, but those exist only in your shell

Best fix

Put the needed vars in:

~/.openclaw/.env

#

or enable shell-env import:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Then restart:

#

openclaw gateway restart

Also make sure the daemon runs as the same user that owns ~/.codex/config.toml.

If you want, paste the relevant part of ~/.codex/config.toml with secrets redacted, and I can tell you exactly what needs to move into ~/.openclaw/.env.

Docs:

Glad we caught that, this looks much more like service env than ACP itself.

edgy wasp Apr 21, 2026, 10:02 PM

#

How can I assure thet gateway reads .env whe started with openclaw gateway restart?

spice smeltBOT Apr 21, 2026, 10:03 PM

#

Yep, the reliable way is:

Use `~/.openclaw/.env`

Not the project/local .env.

When you run:

openclaw gateway restart

the daemon/service starts fresh and loads env at startup. Per docs, the safe global file is:

~/.openclaw/.env

#

(or $OPENCLAW_STATE_DIR/.env if you changed the state dir)

Example

mkdir -p ~/.openclaw
printf 'OPENAI_API_KEY=sk-...\n' >> ~/.openclaw/.env
openclaw gateway restart

Important nuance

OpenClaw does not override existing env vars.

So load order is roughly:

service process env
.env in current working dir
~/.openclaw/.env

#

config env block
optional shell import

That means:

~/.openclaw/.env is the best place for daemon-safe vars
if the service already has a wrong value baked in, .env will not replace it

How to verify

After restart, check:

openclaw models status

If your Codex setup depends on vars referenced from ~/.codex/config.toml, those vars should also go into ~/.openclaw/.env.

#

If you want, I can show you a tiny exact .env + config example for Codex ACP.

Docs:

edgy wasp Apr 21, 2026, 10:04 PM

#

In .env I insert only the key or also the var?

spice smeltBOT Apr 21, 2026, 10:04 PM

#

Both, the variable name and the value.

Like this:

OPENAI_API_KEY=sk-...

Not just:

sk-...

A few quick rules:

one NAME=value per line

#

no export
no spaces around =

Example ~/.openclaw/.env:

OPENAI_API_KEY=sk-...
ANOTHER_VAR=value

If your ~/.codex/config.toml references a specific env var, use that exact var name in .env.

edgy wasp Apr 21, 2026, 10:08 PM

#

Ok it works, now this /acp spawn codex is using soul user, memory from?

spice smeltBOT Apr 21, 2026, 10:09 PM

#

Not exactly.

/acp spawn codex is a separate Codex ACP session, not a normal OpenClaw-native agent run.

So the rough model is:

It does use

the messages you send into that ACP session
the selected workspace / cwd
the Codex session history, if you keep that ACP session alive

It does not automatically use

OpenClaw’s native persona/bootstrap files as first-class agent state, like:
- SOUL.md
- USER.md
- memory.md

#

Those are part of the OpenClaw agent bootstrap, not Codex’s own runtime.

But...

If those files are inside the workspace Codex can see, and Codex is prompted to read them, then yes, it can use them as normal files.

So the best mental model is:

OpenClaw-native agent → uses OpenClaw soul/user/memory system
ACP Codex session → uses Codex session memory + whatever files exist in its cwd

If you want Codex to behave with specific context, point it at a workspace with the files/instructions you want, for example with --cwd /path/to/workspace.

edgy wasp Apr 21, 2026, 10:10 PM

#

Ok so codex should have his own workspace?

spice smeltBOT Apr 21, 2026, 10:11 PM

#

Not required, but often a good idea.

Two sane setups

Same workspace
Use this if you want Codex to work on the same repo/files as the main agent.
Separate workspace
Use this if you want Codex to have different instructions, memory files, or experiments without mixing things.

My recommendation

For real coding on one repo: point Codex at that repo with --cwd /path/to/repo
For a different personality / different context / isolated runs: give Codex its own workspace

So yes, Codex can have its own workspace, but it does not have to.

The important split is:

#

session memory = separate ACP/Codex session
filesystem workspace = shared or separate, your choice

If you want, I can show you a clean setup for:

shared repo
separate Codex workspace
separate Codex agent config

edgy wasp Apr 21, 2026, 10:11 PM

#

Yes

spice smeltBOT Apr 21, 2026, 10:12 PM

#

Nice, here’s the clean version.

1) Shared repo workspace

Best when Codex should work on the same project:

/acp spawn codex --bind here --cwd /absolute/path/to/repo

2) Separate Codex workspace

Best when you want Codex to have its own instructions/files:

/acp spawn codex --bind here --cwd /absolute/path/to/codex-workspace

Then put whatever context you want in that workspace.

#

3) Dedicated Codex agent with its own default workspace

If you want this permanently:

{
  acp: {
    enabled: true,
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["codex"],
  },
  agents: {
    list: [
      {
        id: "codex",
        runtime: {

#

          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/absolute/path/to/codex-workspace",
          },
        },
      },
    ],
  },
}

Then you can just do:

#

/acp spawn codex --bind here

and it should use that default Codex workspace.

Practical recommendation

Same repo if Codex should edit your project
Separate workspace if Codex should have its own context/persona/files

Docs: https://docs.openclaw.ai/tools/acp-agents

Glad you got it working 🎉
If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it.

edgy wasp Apr 21, 2026, 10:17 PM

#

How it works tools and commands that codex can execute? Where are defined boundaries?

spice smeltBOT Apr 21, 2026, 10:17 PM

#

Think of /acp spawn codex as OpenClaw launching an external coding harness, not as normal OpenClaw tool-calls.

Where the boundaries are

cwd / workspace
- This is Codex’s starting context
- Good for telling it “work here”
- But it is not a hard jail by itself
ACPX permission config
This is the main harness-level control:
- approve-all → Codex can write files + run shell commands
- approve-reads → reads only; writes/exec would need prompts
- deny-all → deny prompts entirely
And because ACP is non-interactive:

#

nonInteractivePermissions=fail → session errors out
- nonInteractivePermissions=deny → deny and continue

Host OS permissions
This is the real hard boundary for ACP.
ACP sessions run on the host, not inside OpenClaw’s sandbox.

So if the gateway user can access a path or run a command, Codex may be able to as well, depending on the ACPX permission mode.
OpenClaw plugin tools
By default, ACPX sessions do not get OpenClaw plugin tools.
They only get them if you explicitly enable:
```
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```

#

Custom MCP servers are also separate and explicit.

Allowed harnesses
acp.allowedAgents controls which ACP agents can even be spawned.

Important distinction

OpenClaw exec approvals ≠ ACPX harness permissions
ACP ≠ sandboxed subagent

If you want hard isolation, ACP is the wrong tool. Use a sandboxed subagent instead.

Practical recommendation

Safer setup:

#

dedicated Codex workspace
permissionMode=approve-reads
nonInteractivePermissions=deny

Autonomous coding setup:

dedicated workspace
permissionMode=approve-all

But with approve-all, treat it like host-level write/exec access for that gateway user.

Docs:

If you want, I can give you:

a safe Codex ACP config
or a full-power Codex ACP config

edgy wasp Apr 21, 2026, 10:21 PM

#

Give me both

spice smeltBOT Apr 21, 2026, 10:22 PM

#

Yep, here are both.

1) Safe Codex ACP config

Good when you want Codex to read/analyze, but not freely write/exec.

{
  acp: {
    enabled: true,
    backend: "acpx",
    allowedAgents: ["codex"],
  },
  plugins: {
    entries: {
      acpx: {
        enabled: true,

#

        config: {
          permissionMode: "approve-reads",
          nonInteractivePermissions: "deny",
        },
      },
    },
  },
}

Use it like:

/acp spawn codex --bind here --cwd /absolute/path/to/codex-workspace

#

Behavior

reads: allowed
writes/exec: denied gracefully
safer for shared/personal setups

2) Full-power Codex ACP config

Good when you want Codex to edit files and run commands autonomously.

{
  acp: {
    enabled: true,
    backend: "acpx",
    allowedAgents: ["codex"],

#

  },
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          permissionMode: "approve-all",
          nonInteractivePermissions: "fail",
        },
      },
    },
  },
}

Use it like:

#

/acp spawn codex --bind here --cwd /absolute/path/to/codex-workspace

Behavior

reads: allowed
writes: allowed
shell commands: allowed
basically host-level write/exec as the gateway user

Optional: let Codex use OpenClaw plugin tools too

Off by default.

#

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Only enable that if you actually want ACP Codex to call installed OpenClaw plugin tools.

After editing config

Restart the gateway:

openclaw gateway restart

#

My recommendation

start with safe
switch to full-power only for trusted chats/workspaces

Docs:

Glad you got this working 🎉
If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it.

edgy wasp Apr 21, 2026, 10:24 PM

#

I havent acp entry in config json only acpx is right?

spice smeltBOT Apr 21, 2026, 10:25 PM

#

Not exactly, they are different things:

acpx = the backend plugin/runtime
acp = the top-level feature/policy config

So:

acpx answers: what runtime plugin runs Codex
acp answers: is ACP enabled, which backend to use, which agents are allowed, defaults, limits, etc.

If /acp spawn codex is already working for you, then your current setup is obviously functional. But for a clean explicit config, I’d still recommend having both:

{
  acp: {
    enabled: true,

#

    backend: "acpx",
    allowedAgents: ["codex"],
  },
  plugins: {
    entries: {
      acpx: {
        enabled: true,
      },
    },
  },
}

Then add the plugins.entries.acpx.config.* permission settings on top of that.

So short answer:

#

No, acpx alone is not the same thing as acp
Yes, acpx is the right backend plugin
Best practice is to define an explicit top-level acp block too

Docs:

If you want, I can give you one final minimal working openclaw.json example for Codex ACP.

edgy wasp Apr 21, 2026, 10:28 PM

#

Codex gives me this error:

Bwrap: loopback: failed RTM_NEWADDR: Operation not permitted

spice smeltBOT Apr 21, 2026, 10:30 PM

#

That error is coming from Codex’s own Linux sandbox, not from OpenClaw itself.

bwrap = bubblewrap, which Codex uses on Linux for sandboxing.
So the flow is basically:

OpenClaw launches Codex via ACP
Codex tries to start its own sandbox
Linux blocks the bwrap network/namespace setup
Codex fails with:

Bwrap: loopback: failed RTM_NEWADDR: Operation not permitted

What this usually means

On recent Linux, especially Ubuntu 24.04 / WSL / AppArmor-restricted setups, Codex’s bubblewrap sandbox can fail because unprivileged user namespace / loopback setup is blocked.

#

What to try

Make sure the distro bubblewrap package is installed
Codex’s docs recommend that on Linux.
If it still fails, this is likely an OS/AppArmor restriction
In that case the fix is on the Codex/Linux side, not OpenClaw.
Pragmatic workaround
Use a Codex sandbox mode that avoids the broken bwrap path, or run Codex with less sandboxing in a dedicated workspace if you trust that machine.

Important warning

If you relax Codex’s own sandbox and use ACP full-power permissions, then Codex is basically running with host-level access as the gateway user.

So my recommendation is:

best: fix the Codex Linux sandbox properly
temporary workaround: use a dedicated workspace and loosen Codex sandboxing only there

#

Docs:

Codex sandbox docs: https://developers.openai.com/codex/concepts/sandboxing
OpenClaw ACP docs: https://docs.openclaw.ai/tools/acp-agents

If you want, paste:

your OS
your Codex version
whether you want the safe fix or the fast workaround

and I’ll suggest the least ugly path.

edgy wasp Apr 21, 2026, 10:35 PM

#

Ubuntu 24.04.4 LTS
Kernel linux 6.8.0-101-generic
x86_64
Codex-cli 0.122.0
Openclaw 2026.4.5

spice smeltBOT Apr 21, 2026, 10:35 PM

#

Yep, that combo fits the pattern almost perfectly.

With:

Ubuntu 24.04.4
Kernel 6.8
Codex CLI 0.122.0

that bwrap ... RTM_NEWADDR ... Operation not permitted error is very likely the Codex/Linux bubblewrap sandbox issue on Ubuntu/AppArmor, not an OpenClaw ACP bug.

What that means

Your ACP launch is basically working.

The failure happens after OpenClaw starts Codex, when Codex tries to create its own Linux sandbox.

So I’d read it like this

OpenClaw side: mostly fine

#

Codex side: sandbox is failing on Ubuntu 24.04/AppArmor/userns restrictions

Best path

Keep treating this as a Codex sandbox problem
Use a dedicated Codex workspace
Either:
- fix Codex’s Linux sandbox properly, or
- temporarily relax Codex’s own sandboxing for that dedicated workspace if you trust the machine

Important caution

If you relax Codex sandboxing and also give ACP full-power permissions, then Codex is effectively operating with host-level access as the gateway user.

So for safety I’d recommend:

Preferred: fix Codex sandbox, keep boundaries
Temporary workaround: dedicated workspace + relaxed Codex sandbox only there

#

About your OpenClaw version

2026.4.5 is a bit older, so updating later is sensible, but I would not expect that alone to fix this exact bwrap error.

Docs:

Codex sandbox docs: https://developers.openai.com/codex/concepts/sandboxing
OpenClaw ACP docs: https://docs.openclaw.ai/tools/acp-agents

If you want, next I can give you:

a safe dedicated-workspace workaround
or the proper Ubuntu-side fix path (without going straight to scary system-wide changes)

edgy wasp Apr 21, 2026, 10:38 PM

#

Can openclaw agent message send to codex spawn wit AgenttoAgent conf?

#

?

spice smeltBOT Apr 21, 2026, 10:42 PM

#

Yes, but use sessions_send, not the message tool.

Short version

If you want:

main OpenClaw agent → send work to → Codex ACP agent/session

then you need both:

tools.agentToAgent enabled
tools.sessions.visibility wide enough, usually "all" for cross-agent reach

Minimal shape

#

  agents: {
    list: [
      {
        id: "main",
      },
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/absolute/path/to/codex-workspace",
          },

#

        },
      },
    ],
  },

  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["codex"],
    },
    sessions: {
      visibility: "all",
    },
  },
}

#

How it works

Spawn or bind a Codex ACP session
From another agent, use sessions_send
Target it by session key or label

Important distinction

bindings[].type = "acp" = route a Discord thread/channel directly into Codex
tools.agentToAgent + sessions_send = one agent talks to another agent/session internally

So if your goal is:

users in this thread talk directly to Codex → use ACP binding
one OpenClaw agent delegates to Codex behind the scenes → use agent-to-agent + sessions_send

If you want, I can write the exact JSON5 config for:

direct Discord thread → Codex, or
main agent → Codex relay

#

Yep 🙂

Yes, OpenClaw can send work to a Codex ACP session.

But the clean way is:

not message
use sessions_send
and enable tools.agentToAgent

Simplest mental model

Discord thread -> Codex directly
use: /acp spawn codex --bind here
OpenClaw agent -> Codex internally
use: sessions_send + tools.agentToAgent

#

So the answer is yes, but via session tools, not normal chat-message forwarding.

If you want, I can give you a copy-paste config for the exact setup:

A) Discord thread bound to Codex
B) main agent delegating to Codex behind the scenes

edgy wasp Apr 22, 2026, 9:47 AM

#

B option and how to start it from scratch step by step

spice smeltBOT Apr 22, 2026, 9:49 AM

#

Yep, for B = main agent delegates to Codex behind the scenes, I’d set it up like this.

1) Make a separate `codex` agent

Add a normal main agent plus a second agent whose runtime is ACP/Codex:

{
  acp: {
    enabled: true,
    backend: "acpx",
    allowedAgents: ["codex"],
  },

  plugins: {
    entries: {
      acpx: {

#

        enabled: true,
        config: {
          // Needed if you want Codex to actually write files / run commands
          permissionMode: "approve-all",
          nonInteractivePermissions: "fail",
        },
      },
    },
  },

  agents: {
    list: [
      {
        id: "main",
        default: true,

#

        workspace: "/absolute/path/to/main-workspace",

        // Let main target codex with sessions_spawn(... agentId:"codex")
        subagents: {
          allowAgents: ["codex"],
        },
      },
      {
        id: "codex",
        workspace: "/absolute/path/to/codex-workspace",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",

#

            mode: "persistent",
            cwd: "/absolute/path/to/codex-workspace",
          },
        },
      },
    ],
  },

  tools: {
    // Allow inter-agent/session messaging
    agentToAgent: {
      enabled: true,
      allow: ["codex"],
    },

#

    // Let sessions_send reach across agent boundaries
    sessions: {
      visibility: "all",
    },
  },
}

2) If you use a tool allowlist, include these too

If your main agent has tools.allow, make sure it includes at least:

sessions_spawn
sessions_send
sessions_list (helpful for discovery/debugging)
session_status (optional but useful)

#

3) Restart the gateway

After saving config:

openclaw gateway restart

4) Start a Codex worker session

Now from the main agent chat, ask it to create a persistent Codex worker session.

Conceptually, the main agent should do:

sessions_spawn({
  runtime: "acp",
  agentId: "codex",

#

  mode: "session",
  cleanup: "keep",
  label: "codex-worker"
})

In plain English, you can tell it something like:

Create a persistent ACP session for agent codex, keep it alive, label it codex-worker.

5) Send work to that Codex session

Then the main agent can forward tasks to it with sessions_send, for example:

sessions_send({

#

  label: "codex-worker",
  message: "Open the repo, inspect the auth flow, and propose a fix for the failing login test."
})

In plain English:

Send this task to the codex-worker session and give me back the result.

6) Important gotchas

This is not automatic by default.
The main agent needs to be told to spawn/reuse Codex and send tasks to it.
If the requester session is sandboxed, ACP spawn can be blocked.
If Codex still throws the bwrap error, that is still the Codex/Linux sandbox problem, not the session routing.

Recommended workflow

#

The simplest pattern is:

main agent session starts
main agent spawns codex-worker once
main agent reuses codex-worker with sessions_send
Codex does code work, main agent summarizes back to you

Docs:

ACP agents: https://docs.openclaw.ai/tools/acp-agents
Session tools: https://docs.openclaw.ai/concepts/session-tool

If you want, I can next give you a copy-paste full config with fake paths replaced by real example paths so you can drop it straight into your config.

edgy wasp Apr 22, 2026, 11:50 AM

#

how can I verify that agent:codex:main is effectively an openai codex harness via acp and not an openclaw harness?

spice smeltBOT Apr 22, 2026, 11:51 AM

#

The fastest check is the session key shape.

If it is really:

agent:codex:main

then that is not an ACP session.

That key means:

agentId = codex
session = main

So it is the normal OpenClaw session for the codex agent, not an ACP-spawned external harness session.

ACP sessions look like:

#

agent:codex:acp:<uuid>

From the docs:

ACP session key → agent:<agentId>:acp:<uuid>
subagent session key → agent:<agentId>:subagent:<uuid>

So if you want to verify “is this really Codex via ACP?”, the answer is:

agent:codex:main → no, not ACP
agent:codex:acp:... → yes, ACP runtime session

Important nuance

agent:codex:main could still be using the embedded Codex harness, but that is a different path.

#

So there are 3 different cases:

OpenClaw normal session
- key like agent:codex:main
OpenClaw embedded Codex harness
- still an OpenClaw session
- usually driven by model: "codex/..." + embeddedHarness.runtime: "codex"
ACP Codex session
- key like agent:codex:acp:<uuid>
- created by /acp spawn codex or sessions_spawn({ runtime: "acp" })

How to verify in practice

Check the session key
Run /status
If you used ACP, also check /acp status

#

Rule of thumb

If you never created it with:

/acp spawn codex
or sessions_spawn(... runtime: "acp" ...)

then it is probably not ACP.

Docs:

ACP agents: https://docs.openclaw.ai/tools/acp-agents
Codex harness: https://docs.openclaw.ai/plugins/codex-harness

If you want, I can give you a tiny decision table for:

agent:codex:main
agent:codex:acp:*
model: codex/*
model: openai-codex/*

#

so you can tell exactly which path you’re on.

edgy wasp Apr 22, 2026, 11:57 AM

#

I have this

{ id: "codex", workspace: "/absolute/path/to/codex-workspace", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/absolute/path/to/codex-workspace", },

spice smeltBOT Apr 22, 2026, 11:59 AM

#

Ah, yep, with that config there’s an important nuance:

runtime: {
  type: "acp",
  acp: {
    agent: "codex",
    backend: "acpx",
    mode: "persistent",
    cwd: "/absolute/path/to/codex-workspace",
  },
}

That means the agent is configured to run through ACP.

So agent:codex:main can still be ACP-backed.

#

The correction

I oversimplified earlier: :acp: is the default isolated ACP key shape, but ACP can also be mapped onto a known session key like:

agent:codex:main

So session key alone is not enough in your case.

How to verify properly

1) Check the agent config path

If the active agent really resolves to:

runtime.type = "acp"

#

runtime.acp.agent = "codex"
runtime.acp.backend = "acpx"

then that agent is on the ACP runtime path, not the normal OpenClaw embedded path.

2) Run `/acp status`

This is the best runtime check.

If agent:codex:main is ACP-backed, /acp status for that session should show ACP runtime state instead of “no ACP session”.

3) Compare against the embedded Codex harness path

The embedded OpenClaw Codex harness is a different config shape:

#

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

That is not the same as:

runtime: {
  type: "acp",
  acp: { ... }
}

So:

#

runtime.type: "acp" → ACP external harness path
model: "codex/..." + embeddedHarness.runtime: "codex" → OpenClaw embedded Codex harness path

Practical answer for your snippet

With the snippet you pasted, yes, that is the ACP path.

The cleanest confirmation is:

open that codex agent session
run /acp status
if it reports Codex/acpx runtime state, you’ve verified it

Docs:

ACP agents: https://docs.openclaw.ai/tools/acp-agents
Codex harness: https://docs.openclaw.ai/plugins/codex-harness

If you want, I can give you a tiny “ACP vs embedded Codex vs openai-codex” cheat sheet with exact config examples for all 3.

edgy wasp Apr 22, 2026, 12:13 PM

#

this is what I have:

/acp status in main session chat return:
ACP error (ACP_SESSION_INIT_FAILED): Session is not ACP-enabled: agent:main:main

/acp spawn codex works in main session chat and create avery time a new agent spawn with
Spawned ACP sesssion agent:codex:acp:xxxxxx (persistent, backend acpx) Session is unbound

/acp doctor works from main session chat and return values, activeRuntimeSession = 1 only when an agent is spawned otherwise is 0

these parameters I don't know what are needed for
{ id: "codex", workspace: "/absolute/path/to/codex-workspace", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/absolute/path/to/codex-workspace", },

can't figure it out how to make opencla relay on codex in a non-spawned sessione one shot

#

so?

spice smeltBOT Apr 22, 2026, 12:25 PM

#

So, yes:

With this:

runtime: {
  type: "acp",
  acp: {
    agent: "codex",
    backend: "acpx",
    mode: "persistent",
    cwd: "...",
  },
}

your codex agent is configured to use Codex via ACP/acpx, not the normal OpenClaw embedded harness path.

#

Short rule

runtime.type: "acp" → ACP Codex path
embeddedHarness.runtime: "codex" + model: "codex/..." → embedded Codex harness path

Best runtime check

Run:

/acp status

in that codex agent session.

If it shows ACP runtime state, you’ve confirmed it.

So the answer is: your config is the ACP route.

edgy wasp Apr 22, 2026, 1:37 PM

#

the behavior I observed is this,

{ id: "codex", workspace: "/absolute/path/to/codex-workspace", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/absolute/path/to/codex-workspace", },

these conf simply tells to acp agent that have a persistent home, agent inizialization is only by session_spawn, then main agent can talk with him inside the session, the session persists till is deleted, after this it must be recreated.

spice smeltBOT Apr 22, 2026, 1:37 PM

#

Yep, that understanding is basically correct.

What that config does

This part:

{
  id: "codex",
  workspace: "...",
  runtime: {
    type: "acp",
    acp: {
      agent: "codex",
      backend: "acpx",
      mode: "persistent",
      cwd: "...",

#

    },
  },
}

does not by itself create a live Codex session.

It mainly says:

when this agent uses ACP,
use Codex
through acpx
with persistent mode
and default to that workspace/cwd

When the real ACP session is created

#

The actual live session appears when something starts/binds it, for example:

sessions_spawn(... runtime: "acp", agentId: "codex" ...)
/acp spawn codex
or a bindings[].type = "acp" conversation hits that agent

So your summary, cleaned up

config = persistent home/defaults
sessions_spawn or ACP binding = creates the live session
main agent can then talk to that live session with sessions_send
the ACP session persists until deleted/reset/expired/closed
if deleted, it must be created again on next spawn/bind

One small correction

It is not only sessions_spawn that can initialize it.
A bound ACP conversation can also lazily create/recreate it on first use.

#

So the short answer is:

yes, your mental model is right, except that ACP bindings can also create the session, not just sessions_spawn.

edgy wasp Apr 22, 2026, 1:38 PM

#

what are real benefit of mode: "persistent" ?

spice smeltBOT Apr 22, 2026, 1:40 PM

#

Real benefits of mode: "persistent" are mostly about continuity.

What you gain

1) Same Codex session keeps its own context

Codex remembers the prior exchange inside that ACP session, so follow-ups like:

“continue”
“fix the tests now”
“use the same branch”
“apply the feedback from before”

work much better.

2) Same workspace / repo state

You keep using the same cwd and the same evolving repo state instead of re-bootstrapping a fresh worker every time.

#

3) Less startup churn

You avoid repeatedly creating new ACP sessions, reinitializing the harness, and re-establishing context.

4) Better for iterative coding

Persistent is most useful when the workflow is:

inspect repo
make changes
run tests
revise
continue tomorrow

That’s where it actually shines.

What it does not magically give you

#

It does not create a session by itself.
It only means: when a session is created, keep/reuse it instead of treating it like disposable one-shot work.

Downsides

1) Stale context

Old assumptions can stick around.

2) Drift

The Codex session may accumulate messy history over time.

3) You need lifecycle management

If you delete/reset it, it has to be recreated.

#

Practical rule

Use persistent when Codex is acting like a long-lived coding coworker.

Use oneshot when Codex is just:

“analyze this”
“do one task”
“return result”
“throw session away”

So the short answer is:

persistent is valuable when you want continuity, iteration, and session memory.
If you only want disposable delegated jobs, it gives you much less.

dark heraldBOT Apr 22, 2026, 1:52 PM

#

edgy wasp Apr 22, 2026, 2:13 PM

#

what happens to acp session context windows is compacted by openclaw or by codex harness? There is a way o monitor this?

spice smeltBOT Apr 22, 2026, 2:13 PM

#

For ACP Codex sessions, the short answer is:

Who owns compaction?

Codex / the upstream harness owns the real context window.
OpenClaw does not compact that upstream ACP conversation for it.

OpenClaw mainly does 2 things here:

routes messages to the ACP session
keeps a local transcript mirror for channel history, /new, /reset, search, routing, etc.

So for ACP:

real working context = Codex-side
local mirror/history = OpenClaw-side

So when the ACP session gets long

#

If that Codex ACP session needs to shrink context, that is basically a Codex/harness concern, not OpenClaw’s normal native compaction flow.

That’s different from the embedded Codex harness docs, where OpenClaw explicitly says native compaction is delegated to Codex app-server.

Can you monitor it?

For ACP, only indirectly

You can monitor the session/runtime, but not the upstream context window in a rich OpenClaw-native way.

Useful checks:

/acp status
/acp sessions
gateway logs
any harness-side status/diagnostic output the adapter exposes

What OpenClaw does not really give you here

There isn’t a universal “show me current ACP token window and compaction state” dashboard for ACP sessions the way people usually imagine.

#

Practical rule

OpenClaw native / PI sessions → OpenClaw compaction logic matters
embedded Codex harness (codex/*) → Codex app-server compaction
ACP Codex session → Codex harness/session owns context + compaction

So in your case, if you are really using ACP Codex, I would assume:

Compaction is Codex-side, OpenClaw is mostly the control plane + transcript mirror.

If you want, I can make you a 3-column table for:

OpenClaw native
embedded Codex harness
ACP Codex

showing exactly who owns context, compaction, history, and session persistence.

edgy wasp Apr 22, 2026, 2:19 PM

#

ok

spice smeltBOT Apr 22, 2026, 2:19 PM

#

Nice, glad we untangled it. If you want to keep going later, I can help compare ACP Codex vs embedded Codex harness side by side.

edgy wasp Apr 22, 2026, 2:24 PM

#

why codex token acp ctx % are "unknown" in sessions?

spice smeltBOT Apr 22, 2026, 2:25 PM

#

Because OpenClaw only shows those numbers when it actually has them.

For the unknown / ?% case, it usually means one or more of these are missing:

used tokens
context window size
percent used

From the code path, OpenClaw renders:

unknown used if total usage is missing
unknown/<ctx> (?%) if it knows context size but not actual used tokens / percent

Why this happens a lot with ACP Codex

With ACP sessions, OpenClaw is mostly the control plane + transcript mirror.

So if the Codex ACP adapter / harness does not report standardized usage stats back, OpenClaw cannot calculate:

#

token totals
context window
ctx %

and it falls back to unknown.

Important point

That usually does not mean the session is broken.
It just means usage telemetry is incomplete on that ACP path.

Why embedded/native sessions look better

For native OpenClaw sessions, /status can often backfill from:

live runtime snapshot
transcript usage entry

For ACP Codex, that fallback is often much thinner.

#

So the short answer is:

unknown means OpenClaw is not receiving enough token/context telemetry from the ACP Codex session to compute it.

If you want, I can point you to the exact formatting logic and the exact fields that would need to be populated for it to stop showing unknown.

#Using codex cli via openclaw

Best next test

Also do these

If the daemon is the problem

Best fix

Use ~/.openclaw/.env

Example

Important nuance

How to verify

It does use

It does not automatically use

But...

Two sane setups

My recommendation

1) Shared repo workspace

2) Separate Codex workspace

3) Dedicated Codex agent with its own default workspace

Practical recommendation

Where the boundaries are

Important distinction

Practical recommendation

1) Safe Codex ACP config

Behavior

2) Full-power Codex ACP config

Behavior

Optional: let Codex use OpenClaw plugin tools too

After editing config

My recommendation

What this usually means

What to try

Important warning

What that means

So I’d read it like this

Best path

Important caution

About your OpenClaw version

Short version

Minimal shape

How it works

Important distinction

Simplest mental model

1) Make a separate codex agent

2) If you use a tool allowlist, include these too

3) Restart the gateway

4) Start a Codex worker session

5) Send work to that Codex session

6) Important gotchas

Recommended workflow

If it is really:

ACP sessions look like:

Important nuance

How to verify in practice

Rule of thumb

The correction

How to verify properly

1) Check the agent config path

2) Run /acp status

3) Compare against the embedded Codex harness path

Practical answer for your snippet

Short rule

Best runtime check

What that config does

When the real ACP session is created

So your summary, cleaned up

One small correction

What you gain

1) Same Codex session keeps its own context

2) Same workspace / repo state

3) Less startup churn

4) Better for iterative coding

What it does not magically give you

Downsides

1) Stale context

2) Drift

3) You need lifecycle management

Practical rule

Who owns compaction?

So when the ACP session gets long

Can you monitor it?

For ACP, only indirectly

Use `~/.openclaw/.env`

1) Make a separate `codex` agent

2) Run `/acp status`