Repository navigation
[Enhancement]: OpenClaw adapter: browser dashboard and chat #541
Description
OpenClaw's name: the Control UI, served by OpenClaw's Gateway.
Current specification. This section consolidates the P0 specification on #547 and the clarifications that were posted here as comments, now hidden as outdated. @kaofelix's original description follows, collapsed; where they differ, this section wins. The shared requirements (S, L, P, T, A, C) and open questions (Q) are defined in #547's description.
P0: OpenClaw's Control UI
OpenClaw's Control UI is its browser dashboard and chat. Today the adapter writes "controlUi": {"enabled": false} with no setting to change it, and the Gateway's token exists only in the Gateway process's environment, so a consumer such as NVIDIA NemoClaw can neither offer the UI nor hand a person its sign-in token (NVIDIA/NemoClaw#13360, NVIDIA/NemoClaw#13973).
Settings
| Setting | Default | Description |
|---|---|---|
interfaces.dashboard |
absent (UI off) | Present turns the Control UI on unless enabled: false (S1). |
interfaces.dashboard.port |
required | The Gateway's base port, which serves the Control UI on loopback. At most 65425, so base+110 stays valid. Setting it together with port_range is invalid and rejected during planning. |
interfaces.dashboard.public_origins |
none | Extra browser origins. The adapter writes http://127.0.0.1:<port>, http://localhost:<port> and these to gateway.controlUi.allowedOrigins. OpenClaw accepts any loopback origin regardless, with the token still required, so this matters for non-loopback origins (S5, Q6). |
The descriptor's settings_schema.properties.interfaces lists only dashboard, with additionalProperties: false there and on dashboard (S8).
Ports
With interfaces.dashboard.port, start fails if base or base+2 is taken, using the port check in S2. The whole range from base to base+110 is reserved for OpenClaw's derived ports, including the browser relay at base+10, without being checked (Q7). The README documents the reserved range.
Lifecycle
- The Gateway is the agent's own server, so the runtime check covers it (L4).
startfails if it doesn't finish, from checking theopenclawcommand to the Gateway passing its health check, withinstartup_timeout_seconds: one deadline, default 60, maximum 75 (L2, L3). - In P0,
prepare_service()andattach_service()rejectinterfaceswith a stable error before starting anything (L1); service binding is [Enhancement]: Epic: deferred until after GTC DC: interface contract items and other harnesses #566. stopremovesdashboard.tokenfirst, then stops the Gateway (L5).
Token and sign-in
- The token is generated at each start and written owner-only to
<artifact root>/.fabric/openclaw/runtimes/<runtime-id>/interfaces/dashboard.tokenonce the Gateway passes health (P3, T1). It stays out of the service handle, plans and logs. - A person signs in with OpenClaw's
#token=URL, which the README documents (T4).
Acceptance criteria
- With
interfaces.dashboard, the Gateway serves the Control UI on its exact loopback port, and a browser at a default origin or a listed public origin signs in with the stored token. - The token file is owner-only, outside the service handle, absent when the UI is off, and removed at
stop. - An unlisted non-loopback origin is rejected by OpenClaw, and the README states that OpenClaw accepts any loopback origin, with the token still required (Q6).
- The descriptor, generated catalog and README document the settings, the reserved range from base to base+110, and sign-in.
- Tests cover the generated
openclaw.json, invalid values (includingportwithport_range, andportabove 65425), and the token file's mode. - With the OpenClaw version Fabric pins (2026.9.34 on
main; the prototype used 2026.9.4), a Fabric-started Gateway serves the UI and a browser chat message gets a model reply.
Resolved questions
Settled on #547 on 2026-10-30:
- Q6: OpenClaw accepts any loopback origin even with an explicit
allowedOriginslist (finding 1, on 2026.9.4 and 2026.9.34). Accepted for P0 and documented; exact-origin enforcement is to be raised with OpenClaw upstream. - Q7: the browser relay binds base+10 (finding 2). The whole range from base to base+110 is reserved.
- Shared: Q1, the token is written only after the Gateway passes health; Q2, if core kills the adapter host, the token can stay, which the README documents (L7).
Original description by @kaofelix
Affected area
Harness adapter; Schemas or configuration; Consumer integration; Documentation or examples
Problem or opportunity
OpenClaw's Control UI is its browser dashboard and chat. The adapter writes "controlUi": {"enabled": false} and has no setting to change it, so a consumer that runs OpenClaw for people, such as NVIDIA NemoClaw, can't offer it. NemoClaw removed its dashboard examples and documentation until the adapter supports this (NVIDIA/NemoClaw#13360).
A second gap follows once the UI is on: its sign-in credential is a one-time token that exists only in the Gateway process's environment as OPENCLAW_GATEWAY_TOKEN. openclaw.json refers to it by name, and the adapter's service handle never contains it. A consumer has no way to hand it to a person (NVIDIA/NemoClaw#13973).
Proposed enhancement
Add optional harness.settings.interfaces.dashboard, in the shape #540 proposes for Hermes:
| Setting | Default | Description |
|---|---|---|
interfaces.dashboard.enabled |
absent (UI off) | Serve the Control UI. |
interfaces.dashboard.allowed_origins |
none | Browser origins OpenClaw accepts, written to gateway.controlUi.allowedOrigins. A consumer that exposes the port at its own URL supplies it. |
When enabled, the adapter keeps the Gateway on loopback with token authentication, as today. It writes the generated token to an owner-only (0600) file in a directory the consumer can read, and the settings name that directory the way #540 names state_dir. The token still stays out of the service handle, plans, and logs.
Public contract and compatibility impact
- Rust API: none expected.
- Python API: none.
- Schemas or adapter contract: the OpenClaw descriptor gains the settings above. Whether managed runtimes that don't use a service reject or ignore them is left to review.
- Harness or consumer integrations: consumers choose the port with
port_rangeand the origin withallowed_origins. - Backward compatibility: additive; the default keeps the UI off.
Alternatives considered
- A generic
native_configpassthrough. It would let a consumer set any OpenClaw option, but it widens the contract and lets a configuration conflict with Fabric-owned settings, as the adapter's current checks prevent. - Consumer-side patching. NemoClaw would have to edit adapter-owned configuration, which its policy forbids (Pin a Fabric release without patches or workarounds NemoClaw#13318).
- Leaving the token in the environment. A consumer can't read it from outside the process.
Acceptance criteria
- With
interfaces.dashboard.enabled, the Gateway serves the Control UI on its loopback port, and a browser at a listed origin signs in with the stored token. - The token file is owner-only, outside the service handle, and absent when the UI is off.
- An origin that isn't listed is rejected by OpenClaw.
- The descriptor, generated catalog, and README document the settings.
- Tests cover the generated
openclaw.json, invalid values, and the token file's mode. - With real OpenClaw 2026.9.4, a Fabric-started Gateway serves the UI and a browser chat message gets a model reply.
Additional context
Checked on a DGX Spark with OpenShell 0.1.6 and OpenClaw 2026.9.4: changing the single controlUi line in the adapter (_openclaw_config) to enabled: true with allowedOrigins made the UI load in headless Chromium, sign in with the generated token, and answer a chat message through a local vLLM. OpenShell exposed the port at its service URL.
Related: NVIDIA/NemoClaw#13360, NVIDIA/NemoClaw#13973, #540 (the Hermes counterpart).
Duplicate check
- I searched the existing issues and did not find a duplicate.
Activity
cv commentedon Oct 30, 2026
cv commentedon Oct 30, 2026
cv commentedon Oct 30, 2026
cv commentedon Oct 30, 2026
docs(skills): add a verify skill for hand-written YAML deployments (#…
jyaunches commentedon Oct 30, 2026
Should authenticated
openclaw tuiturns and reconnect be an explicit acceptance criterion here, or tracked as a separate story?Our Spark capability tests found that the native TUI exists, but we could not exercise authenticated turns or reconnect because the adapter did not expose the Gateway token to the caller. This issue addresses that token handoff, while its acceptance criteria currently qualify browser sign-in and browser chat.
Could we clarify whether P0 also promises that a user can launch
openclaw tuiagainst the Fabric-managed Gateway, authenticate with the provided token, complete a turn, then disconnect and reconnect successfully? If that is outside this issue, a linked story would make the intended terminal coverage explicit. This asks about reconnecting to a running Gateway, not conversation restoration after runtime or sandbox replacement.build(fabric): pin Fabric with the P0 interface adapters, OpenClaw 20…
[-][Enhancement]: OpenClaw adapter: serve the Control UI[/-][+][Enhancement]: OpenClaw adapter: browser dashboard and chat[/+]