acpx 0.4.x Can Fail to Create Claude ACP Sessions Silently: What Breaks, How to Verify, and the Safest Rollback

A fresh OpenClaw bug report describes a failure mode that is worse than a loud crash: [email protected] and [email protected] may report success while creating no Claude ACP session at all.

Source issue: openclaw/openclaw#60970

For operators, the dangerous part is not just “session creation failed.” The dangerous part is that the command can exit 0 with no output, while sessions list still shows nothing and the gateway logs only say ensureSession returned no events.

That kind of silent failure is exactly how teams waste time chasing the wrong layer.

What is being reported

According to the issue report:

• acpx claude sessions new --name test exits successfully
• no session ID is returned
• acpx claude sessions list shows No sessions
• OpenClaw sessions_spawn(runtime: "acp", agentId: "claude", ...) fails because it cannot obtain a valid ACP session identifier
• rolling back from [email protected] to [email protected] restores expected behavior immediately

Environment details from the report include:

• Ubuntu 24.04
• OpenClaw 2026.4.2
• Claude Code 2.1.92
• OAuth authentication with Claude Max scopes

The report also notes that direct Claude Code usage still works, which matters because it narrows the likely breakage boundary.

Why this hurts real deployments

This is not a cosmetic CLI bug.

In many OpenClaw setups, ACP session creation is the front door for:

• thread-bound coding runs
• one-shot ACP tasks launched through sessions_spawn
• background implementation work delegated to Claude Code
• operator workflows that expect a session to exist before any useful output appears

When session creation fails silently, teams often misdiagnose the problem as one of these:

• bad Claude authentication
• broken OpenClaw routing
• malformed sessions_spawn parameters
• a temporary gateway glitch

But if the regression is actually inside acpx 0.4.x, debugging the wrong layer only delays recovery.

What makes this different from other ACP session bugs

This report is specifically about the creation path.

That is different from cases where:

• a run completes but sessions_history looks empty for a while
• an idle session later becomes hard to wake via sessions_send
• a transcript exists on disk but session APIs lag behind

Here, the issue appears earlier: the ACP session may never be created in a usable form at all.

That distinction matters operationally because your runbook should change depending on the failure point.

Fast verification checklist

If Claude ACP work suddenly stops after moving to acpx 0.4.x, verify the basics in this order.

1) Check whether a session is actually being created

Run:

acpx claude sessions new --name test
acpx claude sessions list

If the first command exits 0 with no session ID, and the second still says No sessions, treat that as a real creation failure rather than a display problem.

2) Compare gateway logs with CLI behavior

The report shows OpenClaw logs like:

[plugins] acpx ensureSession returned no events after sessions ensure
[plugins] acpx ensureSession returned no events after sessions new

If you see the same pattern, the gateway is likely not getting the session events it expects from the ACP backend.

3) Separate Claude auth from ACP session creation

The issue reporter confirmed direct Claude Code use still worked.

That is a useful branch test:

• if direct Claude usage works
• but acpx claude sessions new creates nothing

then the problem is less likely to be “Claude login is broken everywhere” and more likely to be in the acpx session-creation path.

Safest workaround right now

The lowest-risk workaround in the report is straightforward:

npm install -g [email protected]

Then make sure your OpenClaw ACP plugin expects the same version and restart the gateway using your normal change-control process.

The practical point is simple: if 0.3.1 works and 0.4.x does not, rollback is usually safer than inventing local patches under pressure.

A plausible root-cause boundary

The report does not prove the exact implementation bug, but it gives a useful boundary for investigation.

The failure looks consistent with a change in one of these areas:

• how acpx 0.4.x launches Claude Code
• how it expects session events back from the backend
• how it handles auth-sensitive launch flags during session bootstrap
• how it converts a successful child-process exit into session identifiers visible to both CLI and OpenClaw

One clue in the report is the suspicion around launch behavior changes such as --bare, because bare mode can affect OAuth-backed Claude environments.

That still needs upstream confirmation, so operators should treat it as a lead, not a fact.

Four checks before rolling back to [email protected]

If you landed here from search, the hardest decision is usually whether to roll back immediately. Use these four signals before treating every Claude ACP failure as an acpx 0.4.x regression.

The point is to turn rollback from a guess into an entrypoint check. If session creation never produces a usable object, prompt, routing, and history debugging are probably happening one layer too late.

What to collect before filing “same bug” confirmations

If you are hitting the same regression, high-signal evidence helps more than a short “me too” comment.

Useful evidence includes:

• acpx --version
• OpenClaw version
• Claude Code version
• whether direct Claude CLI use works
• output of acpx claude sessions list
• gateway logs around ensureSession
• whether rolling back to [email protected] restores normal behavior

That combination makes it much easier to confirm whether multiple reports share the same break point.

Bottom line

If your Claude ACP workflows suddenly stopped starting after adopting acpx 0.4.x, do not assume the problem is your prompt, your router, or your OAuth state.

Based on the current report, the more likely explanation is simpler: session creation itself may be silently broken in acpx 0.4.0 and 0.4.1.

Until upstream behavior is clarified or fixed, rolling back to [email protected] is the most practical way to restore session-based Claude ACP work.

Search-intent comparison: silent ACP session creation failure vs empty-history after a run already exists

Operators often merge these failures together because both can look like “Claude ACP did nothing.” But the recovery path changes completely depending on whether a session ever existed.

Treat this as a session creation failure if:

• acpx claude sessions new exits without returning a usable session ID
• acpx claude sessions list still shows no active sessions
• gateway logs complain that ensureSession returned no events

Treat this as an existing-session visibility problem if:

• the run actually executed work
• transcript files already exist on disk
• sessions_history or another projection API is what looks empty or stale

This distinction matters for search intent too. People searching for acpx 0.4 session not created are usually not asking how to re-read transcripts. They are trying to determine whether the orchestration entrypoint itself is broken.

What should the next operator inherit in the handoff note

After mitigation, leave a short note with these four items:

1. the exact acpx version that failed and the rollback version that recovered
2. whether direct Claude Code still worked during the incident
3. one representative ensureSession log line or CLI output proving the failure mode
4. whether OpenClaw ACP flows recovered immediately after rollback or required an extra gateway restart

That handoff note prevents the next operator from reopening the wrong branch of the ACP troubleshooting tree.

FAQ for high-intent search triage

Why should this be checked before an “empty ACP history” theory?

Because the break point here is earlier. This page is about session creation itself failing, not about a session that already exists but is being projected poorly.

With this failure mode, you will often see:

• acpx claude sessions new exits but returns no usable session ID
• acpx claude sessions list still shows no sessions
• the gateway logs only ensureSession returned no events

By contrast, transcript or history visibility bugs usually still leave some evidence that a session existed or work actually ran.

During on-call mitigation, should you rollback first or keep digging logs first?

If production work is blocked and your minimal repro shows 0.4.x cannot create sessions while 0.3.1 restores behavior immediately, rollback is usually the better first move.

The reason is practical:

• this regression blocks the Claude ACP entrypoint itself
• silent failures waste operator time in the wrong layer
• restoring session creation is often worth more than staying broken while gathering perfect logs

If someone searches for “acpx claude sessions new exit 0 but no session”, what are the first three checks?

Start with these three:

1. whether sessions new returned a usable session ID
2. whether sessions list still says No sessions
3. whether gateway logs include ensureSession returned no events

That trio is the fastest way to narrow the issue to a broken creation path instead of treating it as a generic Claude failure.

How do you distinguish direct Claude login trouble from acpx session bootstrap failure?

Use the simplest branch test possible.

Treat it as more likely Claude login or account state trouble if:

• direct Claude Code usage also fails
• OAuth prompts loop, expire, or never complete
• acpx and direct Claude commands both break in similar ways

Treat it as more likely acpx session bootstrap failure if:

• direct Claude Code usage still works
• acpx claude sessions new exits cleanly but creates nothing
• acpx claude sessions list remains empty
• OpenClaw only reports ensureSession returned no events

That split matters because the operator action is different. Login problems usually send you toward auth repair. Bootstrap failures usually send you toward version rollback or ACP backend regression checks.

What is the lowest-risk rollback checklist for operators who need Claude ACP back fast?

If on-call work is blocked, use a short rollback checklist instead of improvising:

1. record the currently installed acpx version
2. downgrade to [email protected]
3. confirm acpx claude sessions new --name test now returns a real session ID
4. confirm acpx claude sessions list no longer shows No sessions
5. restart the OpenClaw gateway if your environment does not recover immediately

Why is a silent session-creation bug more dangerous than a loud crash for automation teams?

Because a loud crash narrows attention quickly, while a silent success-looking failure keeps people debugging the wrong layer.

With this regression, teams can burn hours checking prompts, gateway routing, OAuth scope, or OpenClaw task parameters even though the real break is earlier: the Claude ACP session was never created in usable form.

For automation-heavy teams, that difference matters because queued work can appear merely delayed when the orchestration entrypoint is actually dead.

What proof should you capture before declaring the rollback successful?

Do not stop at “the command no longer errors.” Capture proof that the whole entry path works again:

• acpx claude sessions new --name test returns a usable session ID
• acpx claude sessions list shows the new session instead of No sessions
• one OpenClaw ACP task can now start normally
• ensureSession returned no events no longer appears for the same reproduction path
• leave a handoff note with the failing version, recovered version, and one confirming log line

That bundle of evidence is what turns rollback from guesswork into a reliable incident closure note.

This keeps the mitigation focused on restoring session creation, not on over-debugging a broken release while production work stays blocked.

Why can sessions_spawn(runtime: "acp") fail even when Claude Code itself still opens normally?

Because OpenClaw is not judging success by “did the Claude binary launch at all.” It is judging success by whether the ACP layer returns a real session object that OpenClaw can target afterward.

In this regression, the likely split is:

• Claude Code can still start under the hood
• but acpx 0.4.x fails to surface a usable session ID or session event
• so sessions_spawn(runtime: "acp") cannot attach follow-up work to anything durable

That is why operators can see a confusing state where direct Claude usage looks fine, but OpenClaw orchestration still behaves as if nothing was created.

What should you check before blaming OpenClaw routing or prompt content?

Before changing prompts, routing, or gateway config, verify the creation path itself:

1. run acpx claude sessions new --name test
2. confirm whether a real session ID is returned
3. run acpx claude sessions list
4. compare with gateway logs for ensureSession returned no events

If creation already fails at this layer, prompt changes and router tweaks will not restore Claude ACP work. They are downstream of the broken entrypoint.

Which search queries should this page answer directly?

This page performs best when it captures operators who already suspect the Claude ACP session was never created, rather than broad “Claude is broken” traffic.

High-intent queries worth answering explicitly include:

• acpx claude sessions new exit 0 but no session
• acpx 0.4.1 no sessions
• ensureSession returned no events
• Claude ACP silent session creation failure
• OpenClaw sessions_spawn claude no session id

If your incident looks closer to those phrases, investigate session creation failure before spending time on transcript visibility, history projection, or UI lag theories.

If you arrived from Feishu stop failures, Kimi resets, or release evaluation

Those paths can all feel like “OpenClaw sessions are out of control,” but an ACPX silent-session failure breaks earlier: the Claude ACP session never becomes a usable object. Route the intent first:

• A Feishu thread keeps running and /stop or /new does not interrupt it: start with the Feishu /stop troubleshooting page, where the interrupt event is not reaching the execution layer.
• An ordinary user message immediately shows a /new or /reset banner: start with the Kimi-Claw forced reset issue, where session lifecycle may be recreated incorrectly.
• After an upgrade, a Claude ACP task starts with no session ID at all: then use this page and confirm with acpx claude sessions new, sessions list, and ensureSession returned no events.
• You hit it while evaluating a version, migration, or safety/cost risk: finish the checks in the 2026.3.13 release evaluation, migration guide, and safety/cost page first.

The goal is to separate “run will not stop,” “session was reset,” “post-upgrade instability,” and “ACP session was never created.” Only the last bucket should push you toward rolling back to [email protected] first.

Exact searches this ACPX silent session failure page should answer next

Use this section when a reader lands from a narrow ACPX 0.4.x query and needs to decide whether the run failed before session creation, inside the harness, or after the caller lost the run id.

• ACPX 0.4.x silent session creation failure: check whether the agent session was created at all before debugging model output or prompt content.
• OpenClaw ACPX run starts but no session appears: inspect the harness response, session directory, and gateway logs before retrying the same run.
• fix ACPX silent session failure after upgrade: verify the ACPX package version, runtime adapter config, and first session creation event in one smoke test.

Turn silent-session traffic into a creation-path acceptance checklist

If you arrived because ACPX 0.4.x silently fails to create a session, do not only check whether the frontend shows an error. Split the creation path into four acceptance points: whether the request is actually sent, whether the session id is persisted, whether the runtime returns a ready state, and whether the UI swallows the failure reason. Each point should leave a reproducible log or status code.

The minimal checklist includes one session/create request record, the returned payload, a backend session-list snapshot, and the frontend toast or console output. That routes ACPX incident traffic toward creation paths, state persistence, and UI error visibility instead of leaving it at a single silent-failure symptom.

Related reading

• ACP transcript exists but session APIs may return empty history
• Troubleshooting OpenClaw agents
• OpenClaw complete installation guide

Source

• Issue: openclaw/openclaw#60970