Summary

When using a third-party dashboard/webchat against OpenClaw Gateway over LAN, the connection can fail with origin not allowed and/or missing scope: operator.read|operator.write, making session list/history/send unavailable even though gateway is healthy.

Steps to reproduce

1. Run OpenClaw Gateway on LAN (gateway.bind=lan) and open dashboard from a non-loopback origin (e.g. http://192.168.2.195:18789 / custom dashboard URL).
2. Connect using webchat client defaults (client id often webchat).
3. Observe connection behavior and try sessions.list, chat.history, chat.send.

Expected behavior

• Third-party dashboard should either:
  • connect successfully with clear documented requirements, or
  • fail with deterministic, actionable guidance before partial connect attempts.
• No ambiguous state where UI appears connected but operator scope methods fail unexpectedly.

Actual behavior

Observed intermittent/route-dependent failures:

• origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)
• missing scope: operator.read
• missing scope: operator.write
• UI shows Disconnected from gateway. and session selector becomes unusable (Main Session only).

Workaround currently required:

• add exact dashboard URL to gateway.controlUi.allowedOrigins
• use client.id=openclaw-control-ui for successful operator scope path

OpenClaw version

2026.2.25

Operating system

Debian 13 (x86_64)

Install method

Source build + systemd user service (openclaw-gateway)

Logs, screenshots, and evidence

Key log excerpts from /tmp/openclaw/openclaw-2026-02-27.log:

... reason=origin not allowed ... code=1008 reason=origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins)

... webchat connected ... client=webchat webchat v1.67.1
... res ✗ sessions.list ... errorMessage=missing scope: operator.read
... res ✗ agent.identity.get ... errorMessage=missing scope: operator.read
... res ✗ chat.history ... errorMessage=missing scope: operator.read

... webchat connected ... client=openclaw-control-ui webchat v1.67.2
... (subsequent operator flows succeed)

Impact and severity

• Affected: users integrating third-party dashboard/control UI over LAN.
• Severity: High for dashboard workflows (blocks session browsing/sending until workaround).
• Frequency: Reproducible when origin/client-id combination is not aligned.
• Consequence: connection confusion, unusable session management, and broken message operations.

Additional information

Likely documentation/UX gap + strict policy interaction:

• origin allowlist requirement is strict (good), but failure mode is easy to hit and not obvious in third-party dashboards.
• operator scope appears dependent on client identity path (webchat vs openclaw-control-ui).

Suggested improvements:

1. Explicit docs for third-party dashboards: required allowedOrigins and client-id expectations.
2. Clearer server-side error messages for scope failures (include remediation hint).
3. Optional compatibility mode/flag for trusted custom dashboards with explicit risk warning.