visualize

visualize 是做什麼的？

Use show_widget when seeing or interacting with a result helps the user reason about it. This includes code architecture, execution traces, performance, comparisons, simulations, UI mockups, and session dashboards. Use prose, a normal Markdown table, or a supported Mermaid block when that already explains the answer. A request to implement an application still needs changes in its project; a widget can illustrate the design but does not complete the implementation.

Choose the surface

• Code work and one-off explanations: prefer inline when available this turn. Show the actual owners, relationships, measured values, or states relevant to the question. Distinguish proposed designs and illustrative data from observed behavior. Several diagrams for a code task do not by themselves call for a dashboard.
• Persistent dashboards: use pin: true for an explicit dashboard request or multiple non-code visualizations that belong together. Read the current board first and reuse its names and tabs. Use the control-ui skill when organizing sessions, tabs, placement, or dashboard presentation.
• Native reports: prefer the tool's report input with pin: true for dashboard text, metrics, tables, simple charts, and links. Omit widget_code, kind, capabilities, and presentation.target. Reports do not render inline.
• Custom widgets: use widget_code for interactive HTML/SVG. Reuse an explicit name with pin: true to replace a pinned widget's content. A same-name update cannot change its content owner; inspect before converting HTML to a report.

Use only tools, source kinds, and presentation targets advertised in this turn. On a pinned-only surface, set pin: true and omit presentation.target. If the tool is unavailable, explain the limitation instead of inventing a render call. Restart recovery can be pinned-only even when the original turn supported inline widgets; follow the current tool schema instead of earlier delivery instructions.

Author the content

Send the markup itself in widget_code. Use an HTML or SVG fragment, optionally including <style> and <script>; OpenClaw supplies the document shell, theme, and host bridges. Do not send a file path, Markdown fence, full HTML document, or another application's visualization directive. title is host metadata: start with useful content rather than repeating the title or drawing dashboard chrome.

Keep a useful initial state in the markup. Use local JavaScript for selections, filters, parameter changes, and animation. Give the root a unique ID and scope styles and selectors to it. Insert labels and external data with textContent instead of interpolating untrusted strings into markup or executable code.

Keep source compact: widget_code is limited to 262,144 characters, pinned HTML to 256 KiB after wrapping, and Discord source to 48 KiB. Aggregate large datasets and load a suitable library instead of embedding its distribution in the call.

Libraries and fonts

Scripts, ES modules, stylesheets, and fonts can load from these HTTPS origins:

• https://cdnjs.cloudflare.com
• https://cdn.jsdelivr.net
• https://esm.sh
• https://unpkg.com
• https://fonts.googleapis.com
• https://fonts.gstatic.com
• https://fonts.bunny.net

Use version-pinned library URLs. For example, load D3 with <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/d3.min.js" crossorigin="anonymous"></script> before the inline script that uses d3. Use a module script for ESM imports. Transitive imports, font files, and redirects must also stay on allowed origins. No library, icon set, or font is preloaded. Choose native SVG/CSS for simple visuals; load a library when its scales, layout, or interaction justify it.

Provide readable fallback content and a visible failure state if an asset fails to load. Avoid eval-based libraries; unsafe-eval, remote frames, and arbitrary resource hosts remain unavailable. Images must be embedded as data URLs or drawn locally. CDN URLs are for public assets, never private data or credentials.

CDN loading does not grant fetch, WebSocket, or host API access. Retrieve data with the agent's available tools and embed the needed observations for inline visuals. Use dashboard capabilities for refreshable data, as described below.

Composition and theme

For code explanations, emphasize the relationship being discussed: aligned lanes for concurrent work, labeled edges for ownership and data flow, or shared scales for performance comparisons. Keep source details that support the conclusion; avoid decorative metrics or diagrams of unrelated modules.

For dashboards, make each widget useful on its own and keep related measures comparable. Show data freshness, units, loading, empty, and error states where they affect interpretation. Preserve the last successful data when refresh fails. Use a mockup's product context for its inner controls while retaining the host's theme for the surrounding surface.

OpenClaw styles native headings, controls, tables, and code. It provides .card, .row, .metric, .muted, .badge with .ok/.warn/.danger/.info, and button.primary. Use these when they fit; do not assume another host's classes. Colors and typography use --text, --text-strong, --muted, --surface, --card, --elevated, --border, --border-strong, --accent, --accent-fill, --accent-fg, --ok, --warn, --danger, --info, --radius, --font-body, and --font-mono. Keep the outer background transparent and avoid extra cards around a whole plot. Pair colors with labels or shapes. Canvas libraries need resolved computed colors and redraws when the host theme changes.

Fit the actual container, including narrow chat and resized dashboard columns. Use fluid widths, wrapping controls, and stacked panels; reserve horizontal scrolling for code, tables, or diagrams that require exact geometry. Size SVGs from their container and keep labels readable instead of shrinking a desktop layout. Include axes and units for plots, accessible names, visible control labels, keyboard operation, and touch targets. Honor reduced-motion preferences.

Conversation and dashboard actions

Keep presentation-only changes local. A clearly labeled user-clicked control can call openclaw.prompt.send(text) to ask the agent to investigate selected values. Include those values and the requested action. In the Control UI, prompts need a real user activation in the visible, focused widget; text must be nonempty, at most 4,000 characters, and cannot start with /. Do not trigger prompts on load or on every filter change, and do not assume the widget can read the agent reply. Native renderers do not provide the Control UI conversation bridge.

Only pinned dashboard widgets have the ticket-bound data and action APIs:

• openclaw.data.read(bindingId, params?) reads an advertised Gateway binding.
• openclaw.action.run(actionId, params?) invokes an advertised action.
• openclaw.cron.trigger(jobId) requires cron.trigger:<jobId>.
• openclaw.state.emit(payload) emits a bounded session notice.

Use the current tool schema for binding/action IDs and their parameter shapes. Declare required grants in capabilities.tools. For browser API fetches, declare exact HTTPS origins in capabilities.netOrigins; the browser still requires CORS. Use host bindings for authenticated data; never embed tokens in HTML. Inline previews do not inherit dashboard grants. Check capabilityState and report pending or rejected access; saving a widget does not prove a data read. Updated content may require approval again.

Use normal dashboard links with target="_blank" rel="noopener noreferrer". window.open and nested external iframes do not work. For Control UI links, read openclaw.host.controlUiBaseUrl at click time; it is null before dashboard initialization and outside that host.

Verify and deliver

Fix reported inline-script syntax errors and call the tool again. Script errors thrown after an inline widget renders in the Control UI are reported back to this session. Agent browser tools normally run a separate profile without the viewer's Control UI session, so opening the chat there reaches sign-in, not the widget; do not use them to inspect inline widgets. When a browser or device tool can load the rendered surface itself, verify libraries and fonts loaded, important controls work, and content fits the intended width and theme. For live dashboards, exercise the data read in the actual pinned frame. Strict embed mode disables scripts. Report any concrete visual or platform verification gap; successful hosting alone proves neither rendering nor data access.

Follow result.presentation when present. A status: "pinned" result means the widget is on the session dashboard. Use the available dashboard tool to focus its tab in the current session. Do not navigate to widget hosting URLs in the Browser panel as a substitute for presentation.

Keep the final prose focused on the useful conclusion or remaining limitation, without repeating the entire visual. Do not promise PNG exports preserve externally loaded styles or fonts without checking the exported image.