Control UI
Use OpenClaw's typed UI tools for state and layout. Use browser automation only
to inspect or interact with rendered pixels.
Mental model
- A sidebar item is a session, not a dashboard page.
- Each session owns one board. The board contains tabs and widgets.
- Pinning a session keeps it in the sidebar. Sessions with a stored board appear
in the
/dashboards gallery.
screen changes connected Control UI layout and navigation. It does not read
the page or take screenshots.
sessions_list finds sessions. sessions renames, groups, pins, or archives
them. It does not edit board content.
dashboard reads and arranges the current session's board and registered
plugin widgets. show_widget authors or updates custom HTML/SVG widgets.
Do not replace these operations with shell calls or raw Gateway RPC when the
typed tool exists.
Start safely
- Identify the target session and whether the Control UI is local/direct or
published through Tailscale or another HTTPS proxy.
- If the user wants a dedicated sidebar dashboard, choose or create its
visible session before authoring any widget. A tab is only a partition
inside one session's board; it never creates a sidebar row.
- If the current turn is running in a temporary or parent session, hand the
dashboard task to the intended visible session first. Board widgets are
keyed by session and cannot be moved to another session afterward.
- Read current state before changing it:
- use
sessions_list to resolve the session;
- use
dashboard with action: "read" for the current session;
- inspect existing tabs, stable widget names, owners, sizes, and panel layout.
- If the task targets another session's board, move the work into that session.
Dashboard tools intentionally operate on the current session.
Read hosting.md before opening or repairing a remote
Control UI. Read dashboards.md before creating or
restructuring a board.
Navigate and arrange the UI
Use screen for deterministic client commands:
navigate to open a session by sessionKey;
sidebar_show / sidebar_hide for the session sidebar;
split_right / split_down, focus, and close_pane for panes;
terminal_show / terminal_hide and browser_show / browser_hide for
docked panels.
screen broadcasts to every connected Control UI that advertises UI commands;
it cannot select one browser tab. Confirm the blast radius when several clients
may be open. If it reports no capable client, ask the user to open the Control
UI and retry.
Use the in-app browser or an available browser-control tool when the task needs
DOM inspection, clicking, typing, or screenshots. Reuse the existing signed-in
Control UI tab when possible.
Build a session dashboard
- Call
dashboard read. Reuse suitable tabs and widget names.
- Create or rename tabs with
tab_create / tab_update; use short lowercase
slug IDs.
- Add content with the correct owner:
- self-contained custom HTML/SVG or registered-source content:
show_widget with pin: true;
- trusted plugin widgets:
dashboard widget_put with an advertised
pluginKind.
Do not embed Grafana or another external application in an <iframe> inside
show_widget; widget sandboxes reject child-frame URLs and navigation. Use
an ordinary user-clicked link to open the application, fetch an exact HTTPS
API through declared capabilities.netOrigins, use a Gateway data binding,
or install/use a trusted plugin widget instead.
- Use a stable
name when calling show_widget. Reusing the same name with
new widget_code updates the widget in place.
- Arrange with
widget_move, widget_resize, and tab reordering. Prefer size
presets and board order over pixel placement.
- Pin the current session with
sessions patch when it should stay prominent.
- Call
dashboard focus_tab to show the intended tab in the dashboard side
panel. If no Control UI is connected, the command returns unavailable; have
the user open the session and retry.
- Choose the presentation after focusing the tab.
set_presentation with
presentation: "expanded" expands the dashboard; "split" shows it beside
chat in the current panel layout. The human can use
Expand side panel for a full-width dashboard, Collapse to bring chat
back, or close the panel for chat alone.
Never create a fake top-level page for a dashboard. For a dedicated dashboard,
use a dedicated session, pin that session, and build its board from inside it.
Update without breaking the board
- Read first and mutate the smallest unit.
- Keep stable tab IDs and widget names unless replacement is intentional.
- Do not change a widget's content owner in place. Remove it, then recreate it
with the new owner or registered kind.
- Capability grants are bound to exact widget bytes and revision. Changed
content may require approval again.
- Resetting a conversation preserves its board. Deleting the session deletes
the board.
Verify the result
Use two layers of proof:
- State:
dashboard read shows the expected tabs, widgets, names, owners,
order, and sizes; sessions_list shows the expected session
metadata.
- Rendered UI: open the actual Control UI, confirm the correct session and
dashboard panel, then inspect or screenshot the widget frame. Exercise any
important controls.
An HTTP 200 for the shell or widget route is transport proof, not visual proof.
Do not claim the dashboard works until the sandboxed frame renders.
For widgets that fetch live data, exercise that fetch from the rendered frame.
A host-side curl does not prove the browser received the required capability
grant or accepted the endpoint's CORS and mixed-content policy.
If no browser-control or connected-client inspection is available, report the
dashboard as published but visually unverified instead of claiming success.
Recovery order
When a widget is blank or stale:
- confirm the expected session, tab, widget name, and revision with
dashboard read;
- classify the hosting path using hosting.md;
- verify the Control UI origin, the separate widget sandbox origin, and the
protocol used on every reverse-proxy hop;
- if widget JavaScript reports
Failed to fetch, verify its exact HTTPS origin
is declared and granted in capabilities.netOrigins, then check browser CORS
and mixed-content errors;
- after a Gateway restart or routing change, republish/update the widget so the
browser receives a fresh ticketed frame URL;
- reload the Control UI and verify the rendered frame, not only route status.
1---
2name: control-ui
3description: "Operate and troubleshoot the OpenClaw Control UI: navigate connected clients, organize sessions, build session dashboards, and handle direct or Tailscale-hosted Gateways."
4user-invocable: true
5metadata:
6 source: https://skillmd.com/skills/openclaw/control-ui
7---
8
9# Control UI
10
11Use OpenClaw's typed UI tools for state and layout. Use browser automation only
12to inspect or interact with rendered pixels.
13
14## Mental model
15
16- A sidebar item is a **session**, not a dashboard page.
17- Each session owns one board. The board contains tabs and widgets.
18- Pinning a session keeps it in the sidebar. Sessions with a stored board appear
19 in the `/dashboards` gallery.
20- `screen` changes connected Control UI layout and navigation. It does not read
21 the page or take screenshots.
22- `sessions_list` finds sessions. `sessions` renames, groups, pins, or archives
23 them. It does not edit board content.
24- `dashboard` reads and arranges the current session's board and registered
25 plugin widgets. `show_widget` authors or updates custom HTML/SVG widgets.
26
27Do not replace these operations with shell calls or raw Gateway RPC when the
28typed tool exists.
29
30## Start safely
31
321. Identify the target session and whether the Control UI is local/direct or
33 published through Tailscale or another HTTPS proxy.
34 - If the user wants a dedicated sidebar dashboard, choose or create its
35 visible session before authoring any widget. A tab is only a partition
36 inside one session's board; it never creates a sidebar row.
37 - If the current turn is running in a temporary or parent session, hand the
38 dashboard task to the intended visible session first. Board widgets are
39 keyed by session and cannot be moved to another session afterward.
402. Read current state before changing it:
41 - use `sessions_list` to resolve the session;
42 - use `dashboard` with `action: "read"` for the current session;
43 - inspect existing tabs, stable widget names, owners, sizes, and panel layout.
443. If the task targets another session's board, move the work into that session.
45 Dashboard tools intentionally operate on the current session.
46
47Read [hosting.md](references/hosting.md) before opening or repairing a remote
48Control UI. Read [dashboards.md](references/dashboards.md) before creating or
49restructuring a board.
50
51## Navigate and arrange the UI
52
53Use `screen` for deterministic client commands:
54
55- `navigate` to open a session by `sessionKey`;
56- `sidebar_show` / `sidebar_hide` for the session sidebar;
57- `split_right` / `split_down`, `focus`, and `close_pane` for panes;
58- `terminal_show` / `terminal_hide` and `browser_show` / `browser_hide` for
59 docked panels.
60
61`screen` broadcasts to every connected Control UI that advertises UI commands;
62it cannot select one browser tab. Confirm the blast radius when several clients
63may be open. If it reports no capable client, ask the user to open the Control
64UI and retry.
65
66Use the in-app browser or an available browser-control tool when the task needs
67DOM inspection, clicking, typing, or screenshots. Reuse the existing signed-in
68Control UI tab when possible.
69
70## Build a session dashboard
71
721. Call `dashboard read`. Reuse suitable tabs and widget names.
732. Create or rename tabs with `tab_create` / `tab_update`; use short lowercase
74 slug IDs.
753. Add content with the correct owner:
76 - self-contained custom HTML/SVG or registered-source content:
77 `show_widget` with `pin: true`;
78 - trusted plugin widgets: `dashboard widget_put` with an advertised
79 `pluginKind`.
80 Do not embed Grafana or another external application in an `<iframe>` inside
81 `show_widget`; widget sandboxes reject child-frame URLs and navigation. Use
82 an ordinary user-clicked link to open the application, fetch an exact HTTPS
83 API through declared `capabilities.netOrigins`, use a Gateway data binding,
84 or install/use a trusted plugin widget instead.
854. Use a stable `name` when calling `show_widget`. Reusing the same name with
86 new `widget_code` updates the widget in place.
875. Arrange with `widget_move`, `widget_resize`, and tab reordering. Prefer size
88 presets and board order over pixel placement.
896. Pin the current session with `sessions patch` when it should stay prominent.
907. Call `dashboard focus_tab` to show the intended tab in the dashboard side
91 panel. If no Control UI is connected, the command returns unavailable; have
92 the user open the session and retry.
938. Choose the presentation after focusing the tab. `set_presentation` with
94 `presentation: "expanded"` expands the dashboard; `"split"` shows it beside
95 chat in the current panel layout. The human can use
96 **Expand side panel** for a full-width dashboard, **Collapse** to bring chat
97 back, or close the panel for chat alone.
98
99Never create a fake top-level page for a dashboard. For a dedicated dashboard,
100use a dedicated session, pin that session, and build its board from inside it.
101
102## Update without breaking the board
103
104- Read first and mutate the smallest unit.
105- Keep stable tab IDs and widget names unless replacement is intentional.
106- Do not change a widget's content owner in place. Remove it, then recreate it
107 with the new owner or registered kind.
108- Capability grants are bound to exact widget bytes and revision. Changed
109 content may require approval again.
110- Resetting a conversation preserves its board. Deleting the session deletes
111 the board.
112
113## Verify the result
114
115Use two layers of proof:
116
1171. **State:** `dashboard read` shows the expected tabs, widgets, names, owners,
118 order, and sizes; `sessions_list` shows the expected session
119 metadata.
1202. **Rendered UI:** open the actual Control UI, confirm the correct session and
121 dashboard panel, then inspect or screenshot the widget frame. Exercise any
122 important controls.
123
124An HTTP 200 for the shell or widget route is transport proof, not visual proof.
125Do not claim the dashboard works until the sandboxed frame renders.
126For widgets that fetch live data, exercise that fetch from the rendered frame.
127A host-side `curl` does not prove the browser received the required capability
128grant or accepted the endpoint's CORS and mixed-content policy.
129If no browser-control or connected-client inspection is available, report the
130dashboard as published but visually unverified instead of claiming success.
131
132## Recovery order
133
134When a widget is blank or stale:
135
1361. confirm the expected session, tab, widget name, and revision with
137 `dashboard read`;
1382. classify the hosting path using [hosting.md](references/hosting.md);
1393. verify the Control UI origin, the separate widget sandbox origin, and the
140 protocol used on every reverse-proxy hop;
1414. if widget JavaScript reports `Failed to fetch`, verify its exact HTTPS origin
142 is declared and granted in `capabilities.netOrigins`, then check browser CORS
143 and mixed-content errors;
1445. after a Gateway restart or routing change, republish/update the widget so the
145 browser receives a fresh ticketed frame URL;
1466. reload the Control UI and verify the rendered frame, not only route status.