fix: restore gateway compatibility with OpenClaw 2026.9.5

[steipete]

What does this PR do?

Restore the gateway client’s compatibility with OpenClaw 2026.9.5: identify and sign as a CLI operator, tolerate a newly created agent’s registration delay, and retry the gateway’s explicit startup admission response within the existing connection budget.

Why?

Fixes #91. Thanks @FancyKat for the precise report and successful workaround.

The browser Control UI identity triggers the gateway’s build-ID admission check. Separately, agents.create returns before its configuration hot reload becomes visible to sessions.create. A live smoke also exposed UNAVAILABLE - gateway starting; retry shortly after the HTTP health endpoint was already serving.

Changes

• Use cli identity and mode in both the connection metadata and device signature; retain gateway device approval and operator-scope enforcement.
• Retry only the exact INVALID_REQUEST / Unknown agent id response for an agent this client just created. The window lasts at most five seconds from creation, capped by the request timeout; success and deletion end eligibility, and reconnect preserves the original deadline.
• Preserve structured RPC code/message fields while retaining the existing RuntimeError text. Release pending RPC bookkeeping on cancellation and send failure as well as timeout.
• Document pairing, persistent device state, identity-disabled scope limits, startup and registration deadlines; add the changelog entry and 17 gateway regression cases.

Tests

AWS Crabbox, Python 3.14, with python -m pip install -e '.[dev]':

• Before the repair: three WebSocket regressions failed on main. The separately discovered startup-response regression also failed before its fix.
• python -m pytest -q: 548 passed, 5 skipped; one existing Gradio warning.
• python -m ruff check clawbench app.py scripts tests, changed-file pre-commit hooks, python -m pip check, wheel build and wheel runtime-data inspection passed.

Real OpenClaw 2026.9.5 (ec9c1a1), Node 24.18.1, with isolated synthetic gateway/harness state:

1. Main’s Control UI handshake was rejected as stale.
2. With local automatic pairing disabled, a fresh CLI device received NOT_PAIRED. Listing and explicitly approving that exact device through openclaw devices enabled the connection.
3. Immediate direct sessions.create calls reproduced Unknown agent id for 3/3 new agents. The patched create_session recovered for 3/3 and returned real session keys.
4. Reconnecting with the saved paired identity succeeded. Disabling device identity still left agents.create forbidden for missing operator.admin.

Passing live gateway and final wheel proof. Synthetic local state only; no model/provider calls or benchmark score claim.

Independent Codex autoreview through P2: scoped clean.

Exact head cc71bb4323dace43a62bb2a40494440f8ba9db21 passes Python 3.11 and 3.12 CI.

[clawsweeper]

Codex review: blocked before merge. Reviewed October 5, 2026, 2:38 PM ET / 18:38 UTC (Revision 2).

ClawSweeper review

What this changes

The branch makes ShellBench’s gateway client identify and sign as a CLI operator, adds bounded startup and agent-registration retries, cleans pending requests, and documents pairing with regression coverage.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⛔ Blocked before merge - 4 items remain

The repair remains necessary and has credible live gateway validation. An existing identity-disabled worker configuration loses its authentication compatibility path, so its upgrade handling needs resolution before merge.

Priority: P1
Reviewed head: cc71bb4323dace43a62bb2a40494440f8ba9db21
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Focused recovery logic and concrete runtime observations are useful, but an existing worker authentication mode lacks safe upgrade handling.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.
Evidence reviewed	10 items	Pinned introduced change: The verified main-to-head delta contains four files; it changes CLI connection metadata and signing inputs, registration recovery, startup admission retry, and request cleanup. The original head and checkout are cc71bb4. Repair remains absent from main: Live main remains e3f8d25. Its client still identifies as openclaw-control-ui with ui mode, and the introduced diff confirms session registration recovery is absent. Canonical issue and live validation: #91 remains open and is explicitly paired with this repair. The captured PR body and #91 (comment) report real OpenClaw 2026.9.5 admission failure before the patch, registration recovery for 3/3 agents afterward, NOT_PAIRED before explicit approval, paired reconnect success, and denied agents.create without operator.admin. These are reported runtime observations, not reviewer executions.
Findings	1 actionable finding	[P1] Provide an upgrade path for identity-disabled workers
Security	None	None.

How this fits together

ShellBench’s benchmark harness creates agents and sessions through OpenClaw’s WebSocket gateway. Gateway admission and session setup must succeed before benchmark tasks can run.

flowchart TD
  A[Benchmark task] --> B[Gateway client]
  C[Token and device identity] --> B
  B --> D[Gateway admission]
  D --> E[Agent creation]
  E --> F[Bounded registration retry]
  F --> G[Benchmark session]

Loading

Decision needed

Question	Recommendation
Should identity-disabled worker installations migrate to paired CLI access, or must their device-less compatibility remain supported?	Migrate to paired CLI access: Explicitly retire the browser bypass path, provide an early migration diagnostic, and verify an existing identity-disabled installation can transition to paired access.

Why: The worker explicitly supports this configuration today, while the branch changes the gateway policy it reaches; choosing its permanent support contract requires maintainer intent.

Before merge

• Provide an upgrade path for identity-disabled workers (P1) - With CLAWBENCH_DISABLE_GATEWAY_DEVICE_IDENTITY=1, the worker still enables the Control UI authentication bypass in clawbench/worker.py:1212–1217. Changing the client to CLI makes that bypass ineffective: on OpenClaw 2026.4.26, token-authenticated CLI connections without device identity lose their scopes, so agents.create fails with missing operator.admin where the previous worker configuration could run. Resolve this existing configuration’s migration or supported compatibility before switching identities unconditionally. This concern was missed in the earlier review of the same unchanged head.
• Resolve merge risk (P1) - Maintainers have not accepted retiring the identity-disabled worker authentication path or established an upgrade from that configuration to a paired CLI operator; existing runs can stop at agents.create with missing operator.admin.
• Complete next step (P2) - Decide the identity-disabled worker support contract, implement the approved migration or compatibility path, and verify fresh and upgraded installations before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] Provide an upgrade path for identity-disabled workers — clawbench/client.py:275-278

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	production +46/-8; tests +247/-0	The production growth supports structured errors and bounded recovery, with focused gateway regression coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #91
Summary: This PR explicitly owns the repair for the open gateway compatibility report.

Members:

• canonical: Gateway client fails against OpenClaw 2026.9.5: Control UI build check on connect, and sessions.create before the new agent registers #91 - The issue provides the original gateway admission and registration failures targeted by this branch.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Complete the paired-access migration (recommended)
   After maintainer approval, replace late scope failures with an actionable migration diagnostic and verify upgrading an identity-disabled worker to paired CLI access.
2. Retain supported device-less access
   Pause landing until a gateway-supported compatibility path and regression coverage preserve the existing identity-disabled worker mode.

Technical review

Best possible solution:

Keep the signed CLI repair and bounded retries, with an approved, tested migration from identity-disabled workers to paired operator access and an actionable preflight diagnostic.

Do we have a high-confidence way to reproduce the issue?

Yes: current-main identity and immediate session setup match the reported failures, and the older gateway authentication policy establishes the identity-disabled upgrade failure. This review did not execute target code.

Is this the best way to solve the issue?

Unclear overall: signed CLI access and targeted retries fit the reported bugs, but the worker’s existing identity-disabled configuration needs an explicit migration or supported compatibility path.

Full review comments:

• [P1] Provide an upgrade path for identity-disabled workers — clawbench/client.py:275-278
  With CLAWBENCH_DISABLE_GATEWAY_DEVICE_IDENTITY=1, the worker still enables the Control UI authentication bypass in clawbench/worker.py:1212–1217. Changing the client to CLI makes that bypass ineffective: on OpenClaw 2026.4.26, token-authenticated CLI connections without device identity lose their scopes, so agents.create fails with missing operator.admin where the previous worker configuration could run. Resolve this existing configuration’s migration or supported compatibility before switching identities unconditionally. This concern was missed in the earlier review of the same unchanged head.
  Confidence: 0.96
  Late finding: first raised on code an earlier review cycle already covered.

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against e3f8d25a01f4.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P1: Current gateway incompatibilities prevent benchmark tasks from reaching execution.
• merge-risk: 🚨 compatibility: Existing identity-disabled workers lose their browser-specific authentication compatibility path after the CLI identity change.
• merge-risk: 🚨 auth-provider: Those workers can connect without the operator.admin scope required to create benchmark agents.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.
• proof: sufficient: Contributor real behavior proof is sufficient. The captured body and linked issue comment report the production GatewayClient exercising real OpenClaw 2026.9.5 admission, explicit pairing, 3/3 registration recoveries, paired reconnect, and agents.create rejection without operator.admin. The portal could not be opened from this reviewer environment. Existing identity-disabled upgrade handling remains a separate compatibility blocker; no stored-data format changes are introduced.

Evidence

What I checked:

• Pinned introduced change: The verified main-to-head delta contains four files; it changes CLI connection metadata and signing inputs, registration recovery, startup admission retry, and request cleanup. The original head and checkout are cc71bb4. (clawbench/client.py:275, cc71bb4323da)
• Repair remains absent from main: Live main remains e3f8d25. Its client still identifies as openclaw-control-ui with ui mode, and the introduced diff confirms session registration recovery is absent. (clawbench/client.py:267, e3f8d25a01f4)
• Canonical issue and live validation: Gateway client fails against OpenClaw 2026.9.5: Control UI build check on connect, and sessions.create before the new agent registers #91 remains open and is explicitly paired with this repair. The captured PR body and Gateway client fails against OpenClaw 2026.9.5: Control UI build check on connect, and sessions.create before the new agent registers #91 (comment) report real OpenClaw 2026.9.5 admission failure before the patch, registration recovery for 3/3 agents afterward, NOT_PAIRED before explicit approval, paired reconnect success, and denied agents.create without operator.admin. These are reported runtime observations, not reviewer executions. (cc71bb4323da)
• Existing identity-disabled worker path: When device identity is disabled, the worker configures gateway.controlUi.allowInsecureAuth and gateway.controlUi.dangerouslyDisableDeviceAuth. Switching the client to CLI leaves these browser-specific settings ineffective; the new README acknowledges missing operator.admin but does not establish a completed upgrade path. (clawbench/worker.py:1212, cc71bb4323da)
• Authoritative older gateway compatibility contract: The PR directly consumes OpenClaw’s gateway authentication protocol, making its policy relevant. OpenClaw v2026.4.26 resolves to be8c24633aaa7ef0425ae1178f096ee8dd6226c0. Its Control UI policy applies the bypass only to Control UI clients, while token/password clients without that bypass clear unbound scopes. Thus the introduced CLI identity breaks the worker’s existing identity-disabled control path on this older gateway. (src/gateway/server/ws-connection/connect-policy.ts:95, be8c24633aaa)
• Prior paired-device warning narrowed: OpenClaw 2026.9.5 checks existing devices by key, platform/device-family pins, roles, and approved scopes. Inspection of the metadata resolver and pairing caller did not establish that changing Control UI identity to CLI alone requires reapproval when these values remain unchanged. The previous review’s blanket paired-device reapproval premise is therefore not retained. (src/gateway/server/ws-connection/connect-existing-device.ts:58, ec9c1a13db89)

Likely related people:

• scoootscooob: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• gchlebus: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Resolve the identity-disabled support contract and add its approved migration or compatibility handling.
• Record fresh paired access and upgrade from an existing identity-disabled installation on the supported gateway versions.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)

• reviewed 2026-09-24T13:35:59.185Z sha cc71bb4 :: blocked before merge. :: none