Skip to main content

TUI (Terminal UI)

caution

The TUI (Terminal UI) requires the OpenClaw desktop client to be installed locally. It can connect to your ClawCentral tenant at wss://<your-tenant>.clawcentral.io/gateway/ws using device credentials paired via Admin UI → Nodes. ClawCentral's primary web interface is the Control UI at https://<your-tenant>.clawcentral.io.

Quick start​

Connect the TUI to your ClawCentral tenant:

openclaw tui --url wss://<your-tenant>.clawcentral.io/gateway/ws

Use device credentials paired via Admin UI → Nodes. If you are using a token:

openclaw tui --url wss://<your-tenant>.clawcentral.io/gateway/ws --token <your-token>

Use --password if your setup uses password auth.

What you see​

  • Header: connection URL, current agent, current session.
  • Chat log: user messages, assistant replies, system notices, tool cards.
  • Status line: connection/run state (connecting, running, streaming, idle, error).
  • Footer: connection state + agent + session + model + think/fast/verbose/reasoning + token counts + deliver.
  • Input: text editor with autocomplete.

Mental model: agents + sessions​

  • Agents are unique slugs (e.g. main, research). The Gateway exposes the list.
  • Sessions belong to the current agent.
  • Session keys are stored as agent:<agentId>:<sessionKey>.
    • If you type /session main, the TUI expands it to agent:<currentAgent>:main.
    • If you type /session agent:other:main, you switch to that agent session explicitly.
  • Session scope:
    • per-sender (default): each agent has many sessions.
    • global: the TUI always uses the global session (the picker may be empty).
  • The current agent + session are always visible in the footer.

Sending + delivery​

  • Messages are sent to the agent; delivery to external channels is off by default.
  • Turn delivery on:
    • /deliver on
    • or the Settings panel
    • or start with openclaw tui --deliver

Pickers + overlays​

  • Model picker: list available models and set the session override.
  • Agent picker: choose a different agent.
  • Session picker: shows only sessions for the current agent.
  • Settings: toggle deliver, tool output expansion, and thinking visibility.

Keyboard shortcuts​

  • Enter: send message
  • Esc: abort active run
  • Ctrl+C: clear input (press twice to exit)
  • Ctrl+D: exit
  • Ctrl+L: model picker
  • Ctrl+G: agent picker
  • Ctrl+P: session picker
  • Ctrl+O: toggle tool output expansion
  • Ctrl+T: toggle thinking visibility (reloads history)

Slash commands​

Core:

  • /help
  • /status
  • /agent <id> (or /agents)
  • /session <key> (or /sessions)
  • /model ``<provider/model>``` (or /models`)

Session controls:

  • /think <off|minimal|low|medium|high>
  • /fast <status|on|off>
  • /verbose <on|full|off>
  • /reasoning <on|off|stream>
  • /usage <off|tokens|full>
  • /elevated <on|off|ask|full> (alias: /elev)
  • /activation <mention|always>
  • /deliver <on|off>

Session lifecycle:

  • /new or /reset (reset the session)
  • /abort (abort the active run)
  • /settings
  • /exit

Other slash commands (for example, /context) are forwarded to the agent and shown as system output. See Slash commands.

Local shell commands​

  • Prefix a line with ! to run a local shell command on the TUI host.
  • The TUI prompts once per session to allow local execution; declining keeps ! disabled for the session.
  • Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent cd/env).
  • Local shell commands receive OPENCLAW_SHELL=tui-local in their environment.
  • A lone ! is sent as a normal message; leading spaces do not trigger local exec.

Tool output​

  • Tool calls show as cards with args + results.
  • Ctrl+O toggles between collapsed/expanded views.
  • While tools run, partial updates stream into the same card.

Terminal colors​

  • The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
  • If your terminal uses a light background and auto-detection is wrong, set OPENCLAW_THEME=light before launching openclaw tui.
  • To force the original dark palette instead, set OPENCLAW_THEME=dark.

History + streaming​

  • On connect, the TUI loads the latest history (default 200 messages).
  • Streaming responses update in place until finalized.
  • The TUI also listens to agent tool events for richer tool cards.

Connection details​

  • The TUI registers as mode: "tui".
  • Reconnects show a system message; event gaps are surfaced in the log.

Options​

  • --url <url>: WebSocket URL (e.g. wss://<your-tenant>.clawcentral.io/gateway/ws)
  • --token <token>: token (if required)
  • --password <password>: password (if required)
  • --session <key>: Session key (default: main, or global when scope is global)
  • --deliver: Deliver assistant replies to the provider (default off)
  • --thinking <level>: Override thinking level for sends
  • --timeout-ms <ms>: Agent timeout in ms
  • --history-limit <n>: History entries to load (default 200)

Note: when you set --url, pass --token or --password explicitly. Missing explicit credentials is an error.

Troubleshooting​

No output after sending a message:

  • Run /status in the TUI to confirm the connection is active and idle/busy.
  • If you expect messages in a chat channel, enable delivery (/deliver on or --deliver).

Connection troubleshooting:

  • disconnected: ensure the WebSocket URL is correct and your device credentials or token are valid.
  • No agents in picker: check your agent configuration in Admin UI.
  • Empty session picker: you might be in global scope or have no sessions yet.