面板和停靠栏

Surfaces that dock beside the current page instead of replacing it.

OpenClaw system care¶

Open Settings → Ask OpenClaw to talk to the system setup and repair agent. To open it alongside your current page, click Home in the sidebar footer and select the Ask OpenClaw tab, or use the Ask OpenClaw command-palette action. The full page and dockable panel share one machine-wide conversation whose durable history lives on the Gateway. Closing the UI never cancels a turn; reopening Ask OpenClaw shows the completed conversation. The panel docks on the right or bottom, remembers its placement and size in the browser profile, and hides itself while the full page is open.

If no AI provider is configured, Ask OpenClaw offers Connect an AI provider. If a configured runtime fails to start or verify, the conversation stays visible with the actual error and Retry. Sending stays disabled until verification succeeds. Retry checks the runtime without resending your earlier message or clearing your draft.

Onboarding suggestions can focus the recommended answer when nothing else has focus. If you have already focused the composer or another control, arriving suggestions leave your keyboard focus there.

Each chat message carries the Control UI page you are currently viewing as an untrusted ambient hint, so requests like "configure this channel" or "why is this page empty?" resolve against the page you are looking at.

Guided channel setup, workspace skills setup, web-search provider setup, and local Gateway setup run as hosted wizards inside the chat. Wizard questions stay in the conversation, secret steps mask input in the browser, and successful config-backed flows are audited and re-validated. If a chosen web-search provider needs a plugin install and that install fails, setup stops and reports the failure instead of pretending the provider is configured.

For Gateway setup, say configure gateway to choose the port, bind address, token or password auth, and Tailscale exposure. Before the first question, the web surface warns that applying the saved settings requires a restart that may disconnect the chat or require a new Control UI sign-in. The wizard changes config only; say restart gateway when you are ready to apply it. It manages only a local Gateway, so remote mode changes stay in openclaw onboard or openclaw configure.

Say import memory to copy detected local memory into the existing default agent workspace. This flow does not change config or import credentials or skills, needs no Gateway restart, and distinguishes confirmed imports, nothing to import, provider failures, and failures where some files may already have been copied. Finish onboarding first if the default workspace does not exist. See Import assistant memory for the broader page that can target another agent or replace existing imports, and openclaw setup for the operation and approval contract.

Outside onboarding, this page can show at most one dismissible event chip per visit. It stays silent for routine Gateway traffic and reacts only to health snapshots that report a disabled configuration reloader, a configured channel disconnect/degradation, a failed channel probe, or unavailable channel credentials. A newer event replaces the pending chip only when it is more severe; dismissing or using the chip silences event prompts for that visit. Clicking the chip sends its diagnosis question as a real openclaw.chat message, so the transcript records the request and OpenClaw performs the diagnosis. Onboarding never shows these event chips.

Home dock¶

Use the Home button in the sidebar footer, or in the toolbar when the sidebar is collapsed, to open the selected agent's main conversation alongside your current page. Select the Ask OpenClaw tab in the same dock for system setup and repair. When the same Home conversation is already open as the page, the dock stays hidden rather than showing it twice.

Your Home draft and attachments follow the conversation between the page and dock. Files still being prepared keep their progress and Remove action, and Send waits until preparation finishes.

Home can include a bounded, quoted work-context reference with your message. Before sending, that reference follows the page's agent, session, title, and visible file, not merely the Home conversation receiving it. You can remove it before sending.

Sent messages show Context attached below your words instead of displaying the generated context as message text. Open it to inspect the captured session, page, agent, workspace, file, or selection; Technical details shows the snapshot as JSON. The snapshot is frozen when you send, including through queues and retries. Copying or editing your message does not include the generated reference. It remains reference data, not instructions or permission to access another conversation. Older messages without a recorded attachment are left unchanged.

Operator terminal¶

The operator terminal is enabled by default; set gateway.terminal.enabled: false to opt out. The terminal requires an operator.admin connection and opens a host PTY in the active agent workspace. New tabs follow the currently selected chat agent.

When the terminal is disabled or your connection lacks admin access, the main terminal page shows an unavailable notice and a New session button to return to the composer.

On Linux and macOS, a Gateway running on Bun uses Bun's native PTY without a Node runtime only on builds providing Bun.Terminal.pause() and resume(), such as the OpenClaw Bun fork builds that also carry the macOS child-exit fix. Other Bun releases use a Node helper for terminal I/O. Keep Node available on the Gateway's PATH; OpenClaw skips Bun's node shim, and an unavailable Node executable produces a startup error with installation guidance. Windows keeps node-pty. See Bun compatibility.

Enablement changes hot-apply without restarting the Gateway. Disabling closes attached, detached, and conversation-owned terminals and cancels pending opens. Re-enabling allows fresh sessions; closed sessions do not return. Reload the Control UI page to pick up the updated content security policy.

Use Ctrl + backtick to toggle the Terminal tab in the selected Chat pane's unified side panel. You can also open Terminal from the panel's + menu. The shared panel docks right or bottom, resizes with the browser viewport, can expand over the Chat pane, and keeps multiple shell tabs. The dock remains available for ad-hoc operator shells. Starting a native CLI from New session, or opening a Claude Code or Codex catalog session in the terminal, opens the main terminal page, keeping the sidebar and application chrome while replacing the composer. See Gateway configuration for gateway.terminal.enabled and the optional gateway.terminal.shell override.

Terminal sessions appear as tabs in the Chat side-panel header; choosing Terminal again in the panel's + menu opens another shell, while sessions, upload, and dock-to-bottom actions sit in the header. A Terminal moved to the main area keeps its own tab strip.

The unified panel also hosts Browser, Files, Review, Side chat, and capability-dependent Desktop and Discussion tabs. Its open or minimized state, active tab, tab order, width, dock, and expanded state are stored per session in the current browser profile, so switching sessions or reloading restores each session's own working layout. A chat conversation without a saved panel layout does not inherit panels open in another session. Drag tabs to reorder them, close a tab without closing the other tools, or use the panel close button to minimize the whole panel.

The side-panel divider follows the pointer and arrow-key direction in both left-to-right and right-to-left layouts.

Chat and each tool have their own named region for assistive navigation. Swapping Chat with a tool keeps each tab associated with its own content, including when the same conversation is open in multiple split panes.

A connected Desktop viewer stays connected for 30 seconds while its tab is hidden, so a quick switch to Chat and back restores the same desktop and sizing mode. Input and remote resizing pause while hidden. After 30 seconds, the viewer disconnects and reconnects when reopened. Closing the Desktop tab, changing its session or machine, or losing the Gateway connection releases it immediately. Hiding Desktop during a mouse or touch drag also disconnects it so pressed remote buttons cannot linger. Disconnect keeps it disconnected until you choose Reconnect. Desktop uses one centered loading indicator while resolving its source and connecting.

When you open a chat, the panel automatically reveals an available desktop assigned to that exact session and the browser tab from its latest successful browser-tool result, when that tab is still running. Discovery only reads existing resources: it never starts a browser, provisions a desktop, or attaches an unrelated global or child-session resource. Session and inventory events, plus new browser results, refresh discovery while the chat is visible. Resources without explicit session metadata remain available through the manual panel controls.

Automatic reveals reuse the existing panel and keep an already-selected tool in front. Automatically discovered tabs stay out of the saved layout, including after resizing or docking, so reloading validates the resource again before opening it. Narrow screens use the same bottom-docked layout as manually opened panels. Minimizing the panel or closing a Browser or Desktop tab disables further automatic reveals for that session in the current browser profile, including after reload; the + menu can still open them manually.

Owner-authorized, unsandboxed agents can use the terminal tool to list, read, resize, or close terminals an operator already opened from the same Chat session's Terminal panel. Agents cannot open shells, and access remains exact-session scoped: an agent cannot inspect or control standalone operator terminals or terminals belonging to another session. Terminal input follows the effective session and host-exec permission policy: Full access (full, or YOLO) sends it immediately; Guarded (guarded) and Workspace (workspace, including accept-only or Guardian-reviewed flows) require an explicit, one-time approval for that exact input; Read only (read-only) or tools.exec.mode: "deny" forbids input entirely. Approving one input never grants unrestricted access to the terminal.

Drag one or more files onto the active terminal, or use the paperclip button to choose files. OpenClaw stages each file on the machine that owns the PTY and pastes shell-quoted absolute paths at the cursor; it never presses Enter or executes the input. A compact batch indicator shows the current file and completed count. Cancel stops the remaining batch without pasting paths; a failed transfer stays visible so you can retry from that file without re-uploading completed files. Choose Insert uploaded paths to finish a failed batch using only its completed files, then select any remaining files separately. If the batch stays open until its early uploads may have expired, cancel it and choose the files again.

Images, PDFs, archives, and other file types are accepted up to 16 MiB per file. New uploads must fit within shared limits of 256 MiB and 64 files per staging directory, including files from other terminal tabs and previous processes. When either limit is reached, move or remove staged files, or wait for cleanup, then retry. Existing unexpired files are not evicted to make room, including uploads retained above these limits after an upgrade. Staged files use a private system-temporary directory on POSIX hosts (directory mode 0700, file mode 0600) or a directory under the user-profile ACL boundary on Windows, plus a 24-hour cleanup timer, so move or copy anything you need to keep.

Renaming staged files or retrying failed cleanup does not restart an already scheduled cleanup deadline.

If staging stays locked after a process crash, locate the relative lock directory named in the error on the machine that owns the terminal: the Gateway host for a local terminal or the paired node for a node terminal. On Windows, resolve it under the home directory of the account running that Gateway or node host. On POSIX hosts, resolve it under that process's system temporary directory; check its service environment because TMPDIR, TMP, or TEMP can differ from your shell's settings. Then stop all Gateway and node-host processes using that staging root, remove only the named lock directory, and restart them. This leaves staged files intact. An incomplete lock record is never cleared automatically because it cannot prove that another writer has stopped.

Path insertion supports PowerShell, cmd.exe, and recognized POSIX shells (sh, Bash, Dash, Ash, Ksh, Zsh, and Fish), including Git Bash on Windows. Other shell overrides are refused because their quoting rules cannot be inferred safely; run the Gateway inside WSL for a native WSL terminal and Linux upload paths. cmd.exe paths containing % or ! are also refused because that shell expands those characters even inside double quotes.

Paired-node Codex, Claude Code, OpenCode, and Pi terminals also support uploaded-path insertion, including Windows paths with spaces and apostrophes. The inserted input remains editable and is never automatically submitted.

Claude Code and Codex sessions discovered in the sessions sidebar open their native CLI in the main terminal page. In Settings › Chat, set Open Codex/Claude threads in to Terminal to make a normal row click open codex resume or claude --resume; the default remains the read-only OpenClaw viewer. A row's right-click or kebab menu always offers both choices, and the viewer header includes Open in terminal when that session is eligible.

Catalog-opening requests already queued by an older version finish once in the dock after upgrading. New requests use the main terminal page; the page does not persist catalog-opening intents.

Eligibility is per session and per host. Gateway-local sessions start the provider-owned resume command on the Gateway host. Paired-node sessions start an allowlisted provider command on the owning node and relay only that PTY's output, input, and resize events; this does not expose a general node shell or accept browser-supplied commands. File uploads use the separate, size-bounded terminal.upload node command and remain bound to the already-open terminal session. Approve the node pairing upgrade when that command first appears. Nodes that do not advertise the matching terminal-resume command, including embedded worker bridges without duplex streaming, keep the viewer available and show terminal opening as unavailable; older nodes can still run a terminal but cannot receive dragged files.

Standalone operator sessions, including the main terminal page and terminal focus presentation, are connection-owned. Leaving the main terminal route does not close its PTY; returning to its terminal session URL reattaches it. The main page and the dock keep separate terminal tabs. A page reload, laptop sleep, or network blip detaches one on the Gateway instead of killing it, and the same browser tab reattaches on reconnect with recent output replayed. Detached connection-owned sessions are killed after gateway.terminal.detachedSessionTimeoutSeconds (default 300 seconds; 0 restores kill-on-disconnect). Attaching one of these sessions remains tmux-style take-over.

Closing a connecting tab cancels that opening or attachment request. Other tabs and queued requests remain available, and a late response does not reopen the cancelled tab or display its error.

Conversation-owned sessions opened from a Chat session's Terminal panel are not bound to a browser connection. terminal.attach adds each browser as a viewer without taking ownership, and closing an established viewer tab detaches only that browser. Conversation-owned PTYs remain until the exact-session agent closes them, their shell exits, the session is archived, policy disables them, or the Gateway shuts down. terminal.list marks each entry as connection- or agent-owned.

Resetting an Incognito session closes its conversation-owned terminals and cancels pending terminal opens before deleting the session.

All Gateway terminal PTYs are process-local. A Gateway restart ends them; the PTY sessions and their scrollback are not recovered after the new process starts.

The main terminal page at /terminal is also available as a focus presentation. The iOS and Android apps embed this page in their Terminal screens, reusing the stored gateway credentials; availability follows the same gateway.terminal.enabled and operator.admin gate, and the page shows a notice when the connected Gateway does not offer the terminal. Focus presentation removes the application chrome; it does not invoke browser fullscreen.

Browser panel¶

Ask your agent to "open the browser sidebar" or "show the browser side panel" to reveal this panel. When the screen tool is available, the agent uses browser_show (browser_hide to hide it). sidebar_show and sidebar_hide control the session list instead. Opening the Browser panel does not create or expand a Browser dashboard.

The Control UI ships a Browser tab in the unified Chat side panel that renders the Gateway-controlled browser (the same one agents drive through the browser tool) in any regular web browser - no native webview required. It appears in the panel's + menu when the connected Gateway advertises browser.request to an operator.admin connection; the globe action in Files toggles it. In a regular web browser, choosing Browser again while its panel tab is already open creates another Agent browser tab. The panel shows a live screencast, with screenshot fallback when streaming is unavailable, plus tabs, an editable URL bar, back/forward/reload, and open-in-your-browser, and forwards clicks, wheel scrolling, and basic typing to the remote page. The remote page follows the shared panel: opening it, resizing it, or switching tabs resizes the remote browser viewport to the panel's available space, so the snapshot fills the panel instead of rendering at whatever size an agent last used.

While the panel or a Browser dashboard is visible, a later remote resize also resynchronizes the page to the available space. Hidden panels leave the remote viewport alone. A browser that cannot honor a requested size is not repeatedly resized while its reported dimensions remain unchanged.

Browser tabs appear directly in the Chat side-panel header, with the URL toolbar below. Each tab shows its page favicon when automatic favicon fetching is enabled and an icon is available. Closing the last browser tab leaves the Browser panel open so you can create another tab with +. When Browser is moved to the main area, its tabs appear above its own toolbar.

While an Agent browser preview refreshes, the current page stays visible and the reload icon spins in the toolbar. A loading skeleton appears only before the first page image is available. If refreshing fails, the panel keeps the previous image and shows the error above it.

To paste into an Agent browser tab or Browser dashboard, click the page's input field and press ⌘V on macOS or Ctrl+V on Windows/Linux, or right-click the field and choose Paste. Plain text is inserted at the remote cursor, including password fields and fields inside frames. Pasting does not submit the form or copy your clipboard to the Gateway's system clipboard. This requires a managed browser; Chrome MCP existing-session profiles do not support it.

In the macOS app, the same panel also hosts Mac tabs, rendered natively by WebKit, alongside Agent browser tabs from the Gateway. Mac tabs are available without browser.request; Agent browser tabs retain the Gateway and operator-access requirements above. External links clicked in the dashboard open as Mac tabs in the chat side panel, or in the shell-level Browser dock on non-chat routes. While Settings is open, external links open in the default browser because the Browser panel is hidden. Mac tabs have a tab strip, URL bar, back/forward/reload/stop, open-in-default-browser, and close controls. Mac tabs show the page’s own icon. Mac tabs belong to the chat session that opened them: another session starts with its own empty Browser panel, and returning restores the original session’s tabs. The window retains those tabs until they are closed or the window ends. Opening the same link reuses its existing tab only within that session, including a retained original URL after a redirect. The non-chat Browser dock has its own tabs. Login cookies remain shared within the window. Selecting another tab while a link is opening keeps your selection when the open request completes.

Session-local Mac tabs require both the Mac app and Gateway-served Control UI to support session ownership. During staggered upgrades, older app/UI combinations keep their existing shared-tab behavior so browsing continues to work. Tabs created without session ownership remain window-shared until closed or the window ends; new tabs become session-local once both sides are updated.

Outside the macOS app, enable Open links in Control UI browser under Settings → Infrastructure → Browser to route external HTTP(S) links into new Agent browser tabs in this panel. The browser-local preference is off by default and appears only while the panel is available. It is hidden in the macOS app because unmodified external dashboard links open as Mac tabs outside Settings. Older Control UI bundles that send legacy inline requests open the default browser. Same-origin links, links marked for download, Shift/Alt clicks, file/editor links, email and phone links, right-click actions, and explicit open-in-your-browser actions keep their existing behavior.

In the macOS app, modified clicks open the default browser; right-click an external dashboard link for Open in Browser Panel, Open in Default Browser, or Copy Link. New-window links inside a Mac tab open another Mac tab in the opener’s session, while pointer-activated downloads hand off to the default browser. Non-displayable responses hand off only for pointer-activated main-frame navigation; other non-displayable responses are cancelled silently.

Each Agent browser tab keeps one stable identity across in-place navigation and target replacement, so its selected state, keyboard focus, URL, page snapshot, and browser actions stay aligned even when the Gateway returns tabs in a different order.

To save an asset opened in the panel, click Download file beside the pencil and pointer icons. The icon becomes a spinner while downloading, and the preview stays open without a progress or success message below the toolbar. Mac tabs show a Save dialog and use the tab's signed-in browser session. Agent tabs use their Browser profile's session to save the displayed asset, then deliver the file through the Gateway's authenticated media route; the dashboard does not fetch external asset URLs. Agent downloads follow the Browser profile's download support and network policy. Remote browser-node transfers retain their existing 10 MiB per-file limit. If the download fails, the panel shows an error with an option to use Open in your browser instead. Blank and loading tabs cannot be downloaded.

Chromium does not expose native download redirects for policy inspection. Agent profiles with the default network policy, private-network restrictions, or hostname allow/block restrictions therefore reject this toolbar operation before starting any download traffic. Use Open in your browser to save these assets instead. This restriction does not affect Mac tabs and their native Save dialog.

Two capture modes package page context for the agent. For Mac tabs, either mode captures a one-shot snapshot of the live WebKit page. Navigating the captured tab to a different URL exits capture mode and restores its live view:

• Annotate (pencil): draw freehand markup over the page. Send to chat composites the strokes into the screenshot and adds one structured annotation card to the active chat composer. The card keeps its generated page and region context with the image instead of inserting it into your editable draft.
• Inspect (pointer): hover to see the element under the cursor (selector, accessible name, role, size); click to add those details and a highlighted screenshot through the same card flow. Removing an annotation card removes only that image and its generated context, preserves your draft and other attachments, and offers a short-lived Undo. For Agent browser tabs, Inspect, wheel scrolling, and back/forward need browser.evaluateEnabled (on by default).

One composer accepts up to four browser annotation cards and 8,000 total characters of generated annotation context. When it reaches either limit, the browser panel keeps the current capture so you can remove a card and retry; Undo also preserves the limit instead of evicting another card.

Staged images, files, pasted images, large pasted text, browser annotations, and mixed attachment packages stay with their composer and session across route changes, split-pane remounts, hard reloads, and application restarts. The browser-local retention, scope, and disposal rules described under New session page also apply to existing-session composers. If attachments exceed the durable cap, the current tab keeps them and shows the storage warning; the text remains restart-recoverable, but those attachments do not. If the browser refuses storage entirely, the current tab keeps the live composer and shows the same warning, but that draft cannot be recovered after restart.

GitHub side panel¶

The bundled GitHub plugin contributes this reader and its hover previews. It is enabled by default. Disabling the plugin removes these contributions and leaves GitHub links as ordinary external links. Other plugins can contribute the same docked reader surface through the Plugin SDK.

Click a GitHub issue, pull request, or commit link to read it in a browser-style tab beside the conversation. Each tab has a GitHub icon, a title, and a close control; the address bar and Open on GitHub link stay visible. Opening the same item from chat selects its existing tab. Links inside the reader and URLs entered in the address bar navigate the current tab, with independent Back and Forward history. The + button opens a new tab. Up to ten tabs stay in memory, including their loaded documents while you switch between them.

Opening or loading an item keeps keyboard focus where you are typing. The + button focuses the address bar so you can enter a new URL.

The reader shows descriptions, issue and pull-request discussion comments, commit comments, published inline PR review comments with file/line and diff context, and expandable file diffs. Comment timestamps link to their source on GitHub. Markdown images and standalone HTML image attachments display inline; full-size links remain available when an image cannot load. Inline image requests use the reader plugin's anonymous image resolver when available; GitHub attachments therefore work without browser CORS headers. Readers without an image resolver use anonymous CORS and omit cross-origin credentials and referrers. Scripts and embedded app widgets never run in these documents.

The resizable panel is read-only and supports public repositories. Long discussions and large patches are bounded and marked as incomplete. Refresh fetches the current item again. On phones, the reader follows the shared panel’s responsive layout and expansion controls. Use Open on GitHub for the full page, private repositories, or actions such as posting a comment and merging. Cmd/Ctrl-click and middle-click on document links retain normal browser behavior; middle-clicking a tab closes it. Connections that do not advertise the detail capability keep opening links normally.