How to Run Codex and Claude Code Through OpenClaw with ACP

If you are searching for openclaw codex, the shortest honest answer is this: OpenClaw can run Codex and Claude Code through ACP, but ACP is not the same thing as a native sub-agent and it is not just a prettier wrapper around a side process.

ACP changes the runtime boundary.

Instead of asking OpenClaw to do the deep work itself, you let OpenClaw act as the control plane for an external harness session. That means you can spawn Codex or Claude Code through OpenClaw, keep the session attached to a thread, steer it later, resume it, inspect it, and close it from the same conversational surface.

That sounds subtle until you actually operate it. Then it becomes the difference between “I launched a coding CLI somewhere” and “I have a controllable coding session inside my agent workflow.”

What this page is based on

• local OpenClaw ACP docs and slash-command docs
• real operator use of sessions_spawn(runtime: "acp")
• the March 10 enablement incident where config changes were not enough and an explicit gateway restart was required before ACP spawns actually worked
• the real non-interactive permission caveat in ACP sessions

Control panel

• What ACP means inside OpenClaw
• How to run Codex and Claude Code through OpenClaw with ACP
• ACP vs sub-agents
• ACP vs a separate side process
• Where ACP is better
• Where ACP is worse or sharper
• What broke when we enabled ACP in practice
• The practical decision rule
• Troubleshooting and next reads

This page is a tutorial/support page, not a broad OpenClaw owner page and not a generic Codex-versus-Claude-Code argument. The mechanics playbook and gold-page checklist shaped it on purpose: early trust block, early control panel, skimmer path first, explicit failure modes, and internal links with real jobs instead of random recirculation.

What ACP means inside OpenClaw

ACP stands for Agent Client Protocol. Inside OpenClaw, it is the runtime path for running external harness agents such as Codex, Claude Code, Pi, OpenCode, Gemini CLI, and similar tools through an ACP backend.

The important practical point is not the acronym. The important point is what OpenClaw becomes when ACP is enabled.

With native delegation, OpenClaw is delegating to its own sub-agent runtime. With ACP, OpenClaw is coordinating an external harness runtime.

Today that usually means harness targets like codex and claude, but the same runtime path can also cover tools such as Pi, Gemini CLI, OpenCode, and other ACP-backed agents when the backend is configured to allow them.

That changes the workflow in four important ways:

1. the target runtime is external to OpenClaw’s native sub-agent system
2. the session has its own ACP identity and lifecycle
3. OpenClaw can bind that session to a thread-capable chat surface
4. the operator gets explicit control actions like status, steer, close, and resume

A simple mental model looks like this:

You -> OpenClaw -> ACP runtime -> Codex / Claude Code

Or more explicitly:

chat surface -> OpenClaw control plane -> ACP backend -> external coding harness

That is why ACP matters.

It is not just “OpenClaw launches Codex.” A shell script can launch Codex. ACP matters because OpenClaw stays in the middle as the operator-facing control layer.

If you want the broader architectural context for why OpenClaw is valuable as a control plane at all, read OpenClaw Gateway Architecture: Why Presence Beats Intelligence. If you want the broader authority-page version of how the system is put together, start with OpenClaw Source Code Teardown: How OpenClaw Actually Works. And if you want the surrounding operator stack this sits inside, the practical companion page is The OpenClaw Stack for AI Developer Tools.

How to run Codex and Claude Code through OpenClaw with ACP

If you only need the skimmer version of openclaw codex, this is the section to bookmark: the spawn surface is simple, but the value comes from the session model around it.

This is the practical part most people actually want.

The OpenClaw spawn path for ACP is sessions_spawn with runtime: "acp".

A minimal example looks like this:

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

What each field means in practice:

• runtime: "acp" tells OpenClaw to use the ACP runtime instead of the native sub-agent runtime
• agentId: "codex" picks the external harness target
• thread: true asks OpenClaw to bind the session to a thread when the current channel supports it
• mode: "session" asks for a persistent session instead of a one-shot run

That same shape works for openclaw claude code flows too. The difference is just the ACP target:

{
  "task": "Review the repo structure and propose the smallest safe refactor",
  "runtime": "acp",
  "agentId": "claude",
  "thread": true,
  "mode": "session"
}

A practical reading of those examples:

• use Codex when you want Codex’s own harness/runtime behavior under OpenClaw control
• use Claude Code when you want Claude Code’s harness/runtime behavior under OpenClaw control
• do not pretend those two harnesses are identical just because the OpenClaw spawn surface looks similar

OpenClaw also exposes an operator command layer for ACP sessions. A practical cookbook block looks like this:

/acp spawn codex --mode persistent --thread auto
/acp status
/acp steer tighten logging and continue
/acp close

That gives you a useful working loop:

1. spawn the ACP session
2. work inside the bound thread
3. inspect state when needed
4. steer the session without discarding its context
5. close it when the work is done

If your job is the broader coding-agent operating pattern around this, the next-step page is AI Coding Agent Workflow: Guardrails, Delegation, Review. This page is narrower: how ACP changes the runtime path for external harnesses.

OpenClaw Codex and ACP vs sub-agents

This is where most confusion comes from.

ACP sessions and sub-agents are both ways to delegate work, but they are not the same runtime and they are not interchangeable.

OpenClaw’s own docs draw the line clearly:

• ACP = external harness runtime managed through an ACP backend
• sub-agent = OpenClaw-native delegated run

Here is the compact comparison block that matters in practice:

Area	ACP session	Sub-agent run	Separate side process
Runtime	External harness via ACP backend	OpenClaw-native sub-agent runtime	Outside OpenClaw entirely
Session key shape	agent:<agentId>:acp:<uuid>	agent:<agentId>:subagent:<uuid>	whatever the external tool uses
Main controls	/acp ...	/subagents ...	shell / harness UI
Best use	external harness power with OpenClaw control	native delegated work inside OpenClaw	raw execution without OpenClaw as control plane
Thread continuity	strong when channel bindings are supported	different session path; no ACP controls	manual / tool-specific
Sandbox story	host-side runtime	native OpenClaw runtime	host-side or tool-specific

That table matters because people often collapse the first two rows into “both are child agents.”

Yes, both are delegated work. No, they are not the same operating surface.

A sub-agent is the right choice when you want OpenClaw-native delegation and simpler runtime expectations. ACP is the right choice when you want OpenClaw to control an external harness session specifically.

This is why /acp ... and /subagents ... are separate control surfaces. OpenClaw is telling you, very explicitly, that you are operating two different classes of session.

ACP vs a separate side process

Now for the other confusion point.

You can absolutely run Codex or Claude Code beside OpenClaw as a separate side process. People do this all the time. In small cases it works fine.

But the operator experience is not the same.

A side process gives you raw execution. ACP gives you raw execution plus an agent-side control plane.

That sounds abstract, so here is the practical difference.

With a side process:

• you launch the tool yourself
• the tool owns its own lifecycle
• OpenClaw may know about the result only because you paste it back
• thread continuity is manual
• steering is whatever the external harness provides directly

With ACP:

• OpenClaw spawns the session
• OpenClaw can bind the conversation to that session
• OpenClaw can report status on that session
• OpenClaw can steer the session through its own command surface
• OpenClaw can close the session and clean up the binding
• OpenClaw can resume an existing ACP session when the harness supports it

That is why the strongest short definition is this:

A separate process gives you execution. ACP gives you execution plus operator control plus conversational continuity.

If you do not need the control plane, a side process can be enough. If you do need OpenClaw to stay in charge of the workflow, ACP is the cleaner path.

Where ACP is better

ACP is genuinely stronger in a few specific situations.

1. When you want external harness depth without losing OpenClaw as orchestrator

This is the real headline benefit.

Codex and Claude Code can stay in their own runtime shape, with their own session semantics and capabilities, while OpenClaw stays in the loop as the conversational control surface.

That is stronger than merely launching a tool from a shell because OpenClaw can keep the work inside the same operator workflow.

2. When you want thread-bound persistent sessions

This is one of the highest-leverage practical advantages.

On thread-capable surfaces, OpenClaw can bind an ACP session to a thread so follow-up messages continue talking to the same harness session. That turns the thread into a durable work lane instead of a one-shot instruction drop.

This is especially useful for longer coding sessions, review loops, or repo work that benefits from continuity.

3. When you want explicit lifecycle controls

The ACP command family is not decorative. It is the whole point.

Useful controls include:

• /acp status
• /acp steer
• /acp close
• /acp sessions
• /acp doctor

Those are operator controls, not just convenience syntax.

4. When you want resume behavior

When the target harness supports it, ACP can resume an existing session through resumeSessionId. That is extremely different from the vague “just ask the model again” pattern that weaker workflows rely on.

If you care about real continuity, resume support is a serious advantage.

Where ACP is worse or sharper

ACP is not the default answer for everything. It has real edges.

ACP runs on the host, not inside the OpenClaw sandbox

This is a major boundary, and it should be stated early and plainly.

OpenClaw’s ACP docs are explicit here: ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox.

That leads to a few practical consequences:

• sandboxed requester sessions cannot spawn ACP sessions
• sandbox: "require" is unsupported for ACP runtime
• if you need strict sandbox-enforced execution, use runtime: "subagent" instead

This is one of the cleanest “use ACP when / don’t use ACP when” rules in the whole system.

ACP permission prompts are non-interactive

This is the other sharp edge that matters immediately in real use.

ACP sessions run non-interactively. There is no TTY sitting there to accept permission prompts for file writes or shell execution.

The acpx plugin therefore exposes permission settings that matter a lot:

• permissionMode
• nonInteractivePermissions

OpenClaw’s docs call out the dangerous default combination clearly enough: with permissionMode=approve-reads and nonInteractivePermissions=fail, any write or exec that triggers a permission prompt can fail with AcpRuntimeError: Permission prompt unavailable in non-interactive mode.

That is not a theoretical caveat. It is a real operator footgun.

If your ACP session is expected to edit files or run commands, the permission policy has to match that reality.

ACP adds backend and plugin complexity

Native sub-agents are conceptually simpler because they live inside the OpenClaw-native runtime model.

ACP adds:

• backend enablement
• plugin wiring
• allowed-agent policy
• runtime option handling
• more host-side operational complexity

That does not make ACP bad. It just means it is the more powerful, sharper tool.

What can break first

The failure modes most worth remembering are:

• ACP backend missing or disabled
• target agent not allowed by policy
• thread binding unsupported on the current surface
• non-interactive permission failures on writes or exec
• assuming config changes are live before a real restart has happened

What broke when we enabled ACP in practice

This is the section that keeps the page honest.

On March 10, we enabled ACP runtime in the OpenClaw config with an acpx backend, set a default ACP agent, allowlisted the target harnesses, and enabled the plugin-side non-interactive permissions needed for coding runs.

That was not enough.

The real lesson was this:

config reload was not enough while operations were active; an explicit gateway restart was required before sessions_spawn(runtime="acp") actually worked.

That is the kind of detail a lot of tool pages quietly skip because it is messy. But it is exactly the detail that makes a support/tutorial page useful.

The sequence in practice was:

1. ACP runtime config was updated
2. acpx was enabled
3. permissions were set for coding runs
4. the system still did not behave like ACP was actually live
5. an explicit gateway restart finally made the new runtime path available

That matters because ACP is a runtime path, not just a line in a config file.

It also reinforces the permission caveat above: you do not just need ACP enabled, you need the permission model aligned with the kind of work you are going to ask the harness to do.

If your ACP session needs to edit files, run test commands, or touch the shell, the non-interactive permission policy has to be configured with that in mind.

The practical decision rule for OpenClaw Codex and ACP

This is the compact operator rule I would actually keep.

Use ACP when:

• you want OpenClaw to control an external coding harness session
• you want thread-bound persistent sessions
• you want status, steer, close, and resume through OpenClaw
• you want Codex or Claude Code in their own runtime, but still inside your OpenClaw workflow

Use sub-agents when:

• you want OpenClaw-native delegated execution
• you need sandbox-enforced behavior
• you want the simpler runtime path
• you do not specifically need an external harness control plane

Use a direct side process when:

• you just need raw execution quickly
• you do not care whether OpenClaw is the control plane
• the session does not need thread continuity, session steering, or OpenClaw-side lifecycle management

That is really the whole thing.

The most useful mental model is not “ACP is the advanced version.” The most useful mental model is:

• sub-agents = native delegation
• ACP = external harness orchestration
• side process = raw external execution

Each one is good at a different job.

Troubleshooting and next reads

If openclaw codex or openclaw claude code is not behaving the way you expect, check these first:

1. Is ACP actually enabled?

   • backend plugin installed and enabled
   • acp.enabled=true
   • dispatch enabled if you expect normal message routing

2. Is the target agent allowed?

   • the requested agentId must be in the ACP allowlist

3. Are you expecting sandbox behavior from a host-side runtime?

   • ACP runs on the host
   • if you need enforced sandboxing, use sub-agents instead

4. Are permission prompts failing silently or early?

   • ACP is non-interactive
   • permission policy must allow the sort of work you are requesting

5. Did you actually restart the gateway after changing ACP config?

   • the March 10 failure says this deserves to be on the checklist

For adjacent depth, these are the right internal links, each with a job:

• Prerequisite / operator environment: OpenClaw Mac mini Setup Tutorial
• Next-step / broader implementation workflow: AI Coding Agent Workflow: Guardrails, Delegation, Review
• Adjacent depth / architecture context: OpenClaw Gateway Architecture: Why Presence Beats Intelligence
• Authority page / broader OpenClaw frame: OpenClaw Source Code Teardown: How OpenClaw Actually Works

And for external references that actually matter here:

• OpenClaw ACP agents docs
• OpenClaw slash commands docs
• Agent Client Protocol
• ClaudeAgentSDK workspace teardown if you want a neighboring example of Starkslab thinking about external agent runtimes

Conclusion

If your search started with openclaw codex, the answer is not just that OpenClaw can launch Codex.

The answer is that ACP lets OpenClaw stay the operator-facing brain while Codex or Claude Code do deep work in their own runtime.

That is why ACP is worth understanding.

It is not a synonym for sub-agents. It is not just a side process with nicer branding. It is a control-plane upgrade for external harness sessions.

Use ACP when the job is external harness power plus conversational control. Use sub-agents when the job is native delegated execution. Use a direct side process when you only need raw execution and nothing else.

That distinction is the part that actually makes openclaw claude code and openclaw codex legible in practice.