Map the Gateway and its operating surfaces

Verifiedon 2026-07-302026.7.1-2

The useful mental model

OpenClaw is a long-lived Gateway with clients and operating surfaces around it, not a collection of independent chat bots. The Gateway owns provider connections, the typed WebSocket API, routing, and session data. Gateway owns routing and sessions. A session key selects context; it is not authority. A CLI, Control UI, macOS app, or automation is a control-plane client: it asks the Gateway to inspect state or start work. A node is a different role on the same WebSocket surface; it connects as role: node and declares device capabilities. A channel is an ingress or egress adapter, not the owner of the conversation.

That distinction changes how you investigate. If a message arrives through Telegram, do not draw “Telegram → model” and stop. Draw the channel connection, Gateway routing decision, selected session, agent workspace, model provider, any tool or node boundary, and the configured reply route. Each arrow is a place where identity, data, policy, or an external side effect may differ. A reviewable map exposes those arrows before anyone changes configuration.

The canonical architecture receipt for this lesson is the OpenClaw document at the exact revision reviewed on 2026-07-30: Gateway architecture at revision 2e26244. The companion Gateway protocol source is useful when your map needs to show the first connect frame, request/response envelopes, or server-push events. Both are primary sources, not screenshots or summaries.

A map is also an ownership ledger. Put the operator who can approve a change next to the arrow, not in a separate appendix. If the model provider receives prompt content, mark that transfer even when the provider is “trusted.” If a node can access a camera, filesystem, browser, or location, list the declared capability and the workflow that can invoke it. If the course artifact cannot answer those questions, it is an inventory of names rather than an operating map. The map should make uncertainty cheap: write unknown, requires receipt, or not in scope instead of filling a gap with a plausible assumption.

Worked example: correct a misleading map

Suppose a redacted inventory says “support chat uses Slack, OpenClaw, and a browser.” That sentence hides at least four decisions. Which component receives the Slack event? Which Gateway session receives it? Is the browser a paired node or an unrelated operator browser? Does the response go back to Slack, or is it copied into another channel? Who approves a browser side effect?

Rewrite the description as a traceable inventory:

The map should say “browser node is paired and currently read-only for this workflow,” not “browser is trusted.” Trust is scoped to a role, credential, workflow, and owner. A node can be correctly paired and still be too powerful for a support-room request.

Lab: build a bounded operating map

Use a disposable or purely fictional system. Draw six to eight boxes: inbound channel, Gateway, session, agent/workspace, model provider, tool or node, and outbound recipient. Add an owner and a redacted identity label to every box. Draw arrows in both directions where a result returns; a one-way arrow is not enough if the system stores a transcript or emits a delivery event.

For every arrow, record four fields:

1. Data: message text, attachment metadata, tool arguments, result, or delivery status.
2. Identity: channel account, paired device, provider credential, or named operator—not a secret value.
3. Decision: what policy, approval, sandbox, or channel rule permits the next step.
4. Stop rule: what makes the operator stop, ask, or escalate before an external action.

Example output for a synthetic request is: Slack room → Gateway (allowlisted room) → session key (routing only) → agent context (attachment redacted) → model proposal (read-only lookup) → policy check → mock lookup result → Slack response (delivery unverified). That is more useful than claiming “the bot answered safely.”

surface: gateway
owner: platform-operator
identity: gateway-auth (value omitted)
inbound: allowlisted channel events
outbound: approved channel reply
data: redacted message + session metadata
stop: no owner approval or unclear recipient => do not send

Failure cases and rollback

The most common failure is a diagram that lists products but not authority. “Slack is trusted” is not a boundary: a room may contain forwarded text, attachments, or a compromised account. Another failure is drawing a node as if it were a second Gateway. The node is a paired execution surface; the Gateway still supplies the control plane and policy context. A third failure is writing real tokens, phone numbers, private hostnames, or raw transcript excerpts into a shared map.

If any of those occurs, do not change the deployment to make the picture fit. Stop, delete the sensitive draft, rebuild from a redacted inventory, and ask the Gateway owner to resolve unknown ownership. If a proposed connection cannot be evidenced, label it “unverified” and attach the source receipt rather than inventing a link. This rollback is intentionally a document rollback: the lab changes no running system.

Source receipt and understanding check

This lesson was reviewed against OpenClaw stable 2026.7.1-2, revision 2e26244cec32e61f6117740d3ea273b1ecb54efc, on 2026-07-30. Read the architecture document for component ownership and the security model before exposing a new surface. The receipt does not approve a deployment; it records the source boundary for this teaching exercise.

Answer these without looking at your map: Which component is the source of truth for sessions? Which surfaces are merely clients? What capability has a node explicitly declared? If your diagram says that a session ID authenticates an operator, correct it: routing context is not an authorization boundary.