feat(whatsapp): support Baileys WebSocket URL override by RomneyDa · Pull Request #97155 · openclaw/openclaw

RomneyDa · 2026-06-27T02:16:52Z

What Problem This Solves

PR #95920 needs WhatsApp to point its normal Baileys socket at a local provider-compatible WebSocket endpoint without adding QA-specific socket factories, globals, or Crabline-aware branches to the WhatsApp plugin.

What Changed

Added OPENCLAW_WHATSAPP_WEB_SOCKET_URL as an environment override for the Baileys waWebSocketUrl option inside createWaSocket.
Added an explicit waWebSocketUrl option to createWaSocket for direct low-level callers, with explicit options taking precedence over environment.
Removed the previous monitor runtime singleton / socket factory substitution surface from the net PR diff.
Added test coverage for explicit URL, env URL, precedence, blank env behavior, and workspace .env blocking.

User Impact

Default WhatsApp behavior is unchanged. Without OPENCLAW_WHATSAPP_WEB_SOCKET_URL, OpenClaw still lets Baileys use its normal WhatsApp Web endpoint. QA or owner-controlled runtime env can point Baileys at a compatible local WebSocket endpoint.

Workspace .env remains untrusted for this control because OPENCLAW_WHATSAPP_WEB_SOCKET_URL is covered by the existing OPENCLAW_* workspace blocklist.

Evidence

pnpm exec oxfmt --check extensions/whatsapp/src/session.ts extensions/whatsapp/src/session.test.ts src/infra/dotenv.test.ts
node scripts/run-vitest.mjs run --config test/vitest/vitest.extension-whatsapp.config.ts whatsapp/src/session.test.ts whatsapp/src/connection-controller.test.ts
node scripts/run-vitest.mjs run --config test/vitest/vitest.infra.config.ts src/infra/dotenv.test.ts
pnpm tsgo:extensions:test

clawsweeper · 2026-06-27T02:18:05Z

Codex review: needs maintainer review before merge. Reviewed June 29, 2026, 1:25 PM ET / 17:25 UTC.

Summary
The PR adds a createWaSocket option and trusted OPENCLAW_WHATSAPP_WEB_SOCKET_URL environment default that forward Baileys waWebSocketUrl, with session and workspace-dotenv tests.

PR surface: Source +13, Tests +39. Total +52 across 3 files.

Reproducibility: not applicable. this is a feature/config-surface PR rather than a reported current-main bug. Source inspection confirms current main lacks the override, while the PR head forwards explicit and env-derived URLs to Baileys with focused tests.

Review metrics: 1 noteworthy metric.

Trusted Env Override: 1 added. The PR adds one operator-controlled environment surface that can redirect WhatsApp WebSocket traffic, so the boundary should be noticed before merge.

Stored data model
Persistent data-model change detected: serialized state: extensions/whatsapp/src/session.test.ts, serialized state: extensions/whatsapp/src/session.ts, unknown-data-model-change: extensions/whatsapp/src/session.test.ts, unknown-data-model-change: extensions/whatsapp/src/session.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: canonical
Canonical: #97155
Summary: This PR is the canonical WhatsApp foundation item for the split fake-provider stack; related work covers Slack and downstream QA Lab wiring rather than a duplicate implementation.

Members:

partial_overlap: feat(qa): wire Crabline WhatsApp transport #95920 - The QA Lab Crabline PR depends on this WhatsApp foundation but also contains separate QA runtime wiring, dependency, and automation changes.
adjacent_distinct: feat(slack): support alternate Web API roots #97154 - The Slack alternate API-root PR is the merged sibling foundation for the same fake-provider stack, but it changes Slack Web API routing rather than WhatsApp socket construction.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Record maintainer acceptance of the trusted WhatsApp WebSocket URL override and align the downstream QA Lab PR with this env-only seam.

Risk before merge

[P1] The PR adds a new trusted operator environment variable that can redirect WhatsApp WebSocket traffic, so maintainers should explicitly accept that endpoint-routing boundary before merge.
[P1] The downstream QA Lab Crabline PR at feat(qa): wire Crabline WhatsApp transport #95920 still describes the older socket-factory/runtime-setter seam and is based on an earlier head, so the split stack needs coordination against this final env-only shape.

Maintainer options:

Accept The Trusted Env Override (recommended)
Maintainers can land this PR after explicitly owning OPENCLAW_WHATSAPP_WEB_SOCKET_URL as a trusted process/global env control for QA and owner-operated runtimes.
Coordinate The Downstream Stack First
Hold this PR until feat(qa): wire Crabline WhatsApp transport #95920 is rebased or revised to use the env-only WebSocket URL seam instead of the older runtime-setter wording.
Reject Endpoint Routing In The Plugin
If maintainers do not want WhatsApp socket endpoint routing in the bundled plugin, close or pause this PR and keep the fake-provider integration outside the WhatsApp runtime path.

Next step before merge

[P2] Manual review is required because this maintainer-labeled PR adds a trusted endpoint-routing env surface and needs downstream stack coordination; there is no narrow automated repair to queue.

Security
Cleared: No concrete security or supply-chain defect was found; the diff adds no dependency or workflow change, and the new OPENCLAW_* override remains blocked from untrusted workspace .env.

Review details

Best possible solution:

Use this narrow Baileys waWebSocketUrl override only if maintainers accept the trusted-env operator contract, then update the downstream QA Lab PR to consume that final seam.

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

Not applicable; this is a feature/config-surface PR rather than a reported current-main bug. Source inspection confirms current main lacks the override, while the PR head forwards explicit and env-derived URLs to Baileys with focused tests.

Is this the best way to solve the issue?

Yes, conditionally; using Baileys' native waWebSocketUrl option inside the WhatsApp session module is narrower than the earlier public socket-factory seam and avoids QA-specific branches. It is only the best merge path if maintainers accept the trusted env override and downstream stack alignment.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 6de357ad4772.

Label changes

Label changes:

add merge-risk: 🚨 security-boundary: The override can route WhatsApp WebSocket session traffic to a non-default endpoint, so maintainers need to own the trusted-env security boundary even though workspace .env is blocked.

Label justifications:

P3: This is low-urgency QA/fake-provider foundation work rather than a current production WhatsApp regression.
merge-risk: 🚨 compatibility: The PR adds a new env-driven endpoint override that can change WhatsApp runtime behavior when present in trusted process/global env.
merge-risk: 🚨 security-boundary: The override can route WhatsApp WebSocket session traffic to a non-default endpoint, so maintainers need to own the trusted-env security boundary even though workspace .env is blocked.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor real-behavior proof gate does not apply because this is a MEMBER-authored, maintainer-labeled PR; PR-body test commands are useful supplemental evidence.

Evidence reviewed

PR surface:

Source +13, Tests +39. Total +52 across 3 files.

View PR surface stats

Area	Files	Added	Net
Source	1	13	+13
Tests	2	39	+39
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	3	52	+52

What I checked:

Root policy read: Root AGENTS.md was read fully; its review policy treats env/config additions and channel/runtime routing changes as compatibility-sensitive review surfaces. (AGENTS.md:29, 6de357ad4772)
Scoped extension policy read: extensions/AGENTS.md was read fully; the WhatsApp plugin stays inside the bundled plugin boundary and the revised diff no longer expands a public WhatsApp API barrel. (extensions/AGENTS.md:34, 6de357ad4772)
Current main behavior: On current main, createWaSocket builds the Baileys socket without any waWebSocketUrl option, so the requested override is not already implemented. (extensions/whatsapp/src/session.ts:175, 6de357ad4772)
PR implementation: At PR head, the session module defines OPENCLAW_WHATSAPP_WEB_SOCKET_URL, trims explicit/env string values, gives explicit options precedence, and passes waWebSocketUrl into makeWASocket. (extensions/whatsapp/src/session.ts:184, e897bdaac654)
PR tests: The PR head adds tests for explicit URL, env URL, explicit-over-env precedence, and blank env handling. (extensions/whatsapp/src/session.test.ts:418, e897bdaac654)
Workspace dotenv boundary: Current dotenv loading blocks the whole OPENCLAW_ prefix from untrusted workspace .env, and the PR head adds the WhatsApp URL key to the runtime-control blocklist completeness test. (src/infra/dotenv.ts:177, 6de357ad4772)

Likely related people:

RomneyDa: Authored the merged Slack alternate Web API root work that established the parallel trusted env endpoint-routing pattern, and authored this WhatsApp PR beyond merely reporting it. (role: adjacent trusted-env routing contributor; confidence: high; commits: 39e1be080ca0; files: src/infra/dotenv.ts, src/infra/dotenv.test.ts, extensions/slack/src/client.ts)
mcaxtr: Recent current-main history shows repeated WhatsApp connection-controller, monitor, and session lifecycle work that this socket-routing change depends on. (role: WhatsApp connection lifecycle contributor; confidence: high; commits: dd2083c7ec51, 52d9d16e1be9, 7d8b000bf78a; files: extensions/whatsapp/src/session.ts, extensions/whatsapp/src/connection-controller.ts, extensions/whatsapp/src/inbound/monitor.ts)
mmaps: Introduced the provider-credential workspace dotenv blocklist area that the new WhatsApp env override relies on for untrusted workspace protection. (role: workspace dotenv trust-boundary contributor; confidence: medium; commits: 85277c2db1fa; files: src/infra/dotenv.ts, src/infra/dotenv.test.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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.

RomneyDa · 2026-06-29T01:58:55Z

@clawsweeper re-review

clawsweeper · 2026-06-29T01:58:58Z

🦞🧹
ClawSweeper re-review requested.