OpenClaw's Gateway Handshake Example Never Passed Its Own Validation — Now It Does

If you've ever tried to build a custom client for OpenClaw's gateway and found yourself reading source code instead of documentation, you weren't doing it wrong — the docs were. A quiet but significant update to protocol.md has landed in the OpenClaw repository, correcting a schema path that pointed to a file that doesn't export what the docs claimed it did, rewriting a Hello-OK handshake example that would have been rejected on contact, and finally spelling out the authentication precedence rules that developers have been piecing together from client.ts for months.

The Schema Path That Led Nowhere

OpenClaw's gateway protocol documentation previously directed developers to src/gateway/protocol/schema.ts as the source of truth for the PROTOCOL_VERSION constant. The file exists — it just doesn't export that constant. The actual location is src/gateway/protocol/schema/protocol-schemas.ts, a subtle but important distinction for anyone trying to pin their client implementation to the correct version.

It's the kind of error that doesn't break anything in the main project — the runtime knows where to find its own constants. But for third-party developers writing clients from documentation alone, it meant a detour through the source tree to figure out why their imports failed.

A Handshake Example That Shook Hands With Nobody

Perhaps the most striking fix is to the Hello-OK exchange example — the very first thing a client sends to a gateway after opening a WebSocket connection. The previous version in the docs was a minimal JSON snippet that omitted required fields. That might have been fine as a conceptual illustration, except the gateway schema enforces additionalProperties: false, meaning any message missing required fields is rejected outright.

The updated example now includes every schema-required field: server, features, snapshot, and a complete policy block with the correct maxBufferedBytes value of 52,428,800 (50 MiB). Copy it, send it, and the gateway will actually respond.

“The previous Hello-OK example would fail schema validation due to additionalProperties: false constraints. That's not a documentation shortcut — that's a documentation bug.”

Authentication Precedence: No Longer a Code-Reading Exercise

The gateway's authentication system supports multiple token sources — password forwarding, bootstrap tokens, stored device tokens — and until now, the rules governing which one takes priority were only reliably documented in the selectConnectAuth function inside client.ts.

The rewritten section now explicitly states three rules that were previously implicit:

• Password forwarding is independent — it operates on its own path regardless of other token sources.
• Bootstrap suppression triggers when any token resolves — if a stored token or device token is available, the bootstrap flow is skipped entirely.
• Device-token auto-promotion on retry is trust-gated — it only applies to loopback connections or endpoints with pinned TLS fingerprints, a nuance that matters for security-conscious deployments.

For operators running OpenClaw behind reverse proxies or in multi-tenant configurations, these distinctions determine whether a reconnecting client silently re-authenticates or drops to a bootstrap prompt. Getting it wrong means either a degraded user experience or, worse, an unintended auth escalation path.

The Missing Constants Table

The update also adds something the protocol reference has never had: a dedicated client constants table. It documents the reference client's timeouts, exponential backoff values, tick-timeout close codes, and maximum payload sizes — each linked back to its source location in the codebase.

This is the kind of reference material that saves hours of debugging. Without it, a client author implementing reconnection logic has to guess at backoff ceilings and payload limits, or dig through the reference client's source to find the values. Now they're in a table.

Why This Matters

OpenClaw's gateway is the backbone of every self-hosted deployment. It handles the WebSocket connections between messaging channels (Telegram, Discord, WhatsApp) and the AI models doing the actual work. The protocol documentation is, for many developers, the only thing standing between them and a working custom integration.

When that documentation contains a schema path to the wrong file, a handshake example that fails on first contact, and authentication rules that require reading the implementation to understand, the effective barrier to building on OpenClaw rises sharply. This update lowers it back down.

It's not a flashy feature release or a breaking-change migration. It's the kind of housekeeping that makes an open-source project actually usable by the people it claims to serve — the ones building on it, not just the ones maintaining it.