TUI

Quick Start

1. Enter the root interface (if the application was installed in the root directory using root privileges).

xxxxxxxxxx
sudo su

2. Start the Gateway. (Typically, the Gateway starts automatically, so running this command is not necessary.)

xxxxxxxxxx
openclaw gateway

3. Open the TUI.

xxxxxxxxxx
openclaw tui

4. Enter a message and press Enter.

Remote Gateway:

xxxxxxxxxx
openclaw tui --url ws://<host>:<port> --token <gateway-token>

If your Gateway uses password authentication, use --password.

What You See

• Title bar: Connection URL, current agent, current session.

• Chat log: User messages, assistant replies, system notifications, tool cards.

• Status line: Connection/running status (connecting, running, streaming, idle, error).

• Footer: Connection status + agent + session + model + think/verbose/reasoning + token count + delivery status.

• Input: Text editor with autocomplete.

Mental Model: Agent + Session

• An agent is a unique identifier (e.g., main, research). The Gateway exposes a list.

• Sessions belong to the current agent.

• Session keys are stored as agent:<agentId>:<sessionKey>.

  • If you type /session main, TUI expands it to agent:<currentAgent>:main.

  • If you type /session agent:other:main, you explicitly switch to that agent's session.

• Session scope:

  • per-sender (default): Multiple sessions per agent.

  • global: TUI always uses the global session (selector may be empty).

• Current agent + session is always visible in the footer.

Send + Deliver

• Messages are sent to the Gateway; by default they are not delivered to the provider.

• To enable delivery:

  • /deliver on

  • Or the settings panel

  • Or launch with openclaw tui --deliver

Selectors + Overlays

• Model selector: Lists available models and sets session override.

• Agent selector: Select a different agent.

• Session selector: Shows only sessions for the current agent.

• Settings: Toggle delivery, 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 selector

• Ctrl+G: Agent selector

• Ctrl+P: Session selector

• 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 control:

• /think <off|minimal|low|medium|high>

• /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 session)

• /abort (abort active run)

• /settings

• /exit

Other Gateway slash commands (e.g., /context) are forwarded to the Gateway and appear as system output. See Slash Commands.

Local Shell Commands

• Lines prefixed with ! run local shell commands on the TUI host.

• TUI prompts once per session to allow local execution; denying disables ! for that session.

• Commands run in a fresh non-interactive shell in the TUI working directory (no persistent cd/env variables).

• A standalone ! sends it as a regular message; leading whitespace does not trigger local execution.

Tool Output

• Tool calls display as cards with parameters + results.

• Ctrl+O toggles between collapsed/expanded view.

• While a tool is running, partial updates stream to the same card.

History + Streaming

• On connect, TUI loads the latest history (default 200 messages).

• Streaming responses update in place until completion.

• TUI also listens to agent tool events for richer tool cards.

Connection Details

• TUI registers with the Gateway as mode: "tui".

• Reconnecting shows a system message; gaps in events appear in the log.

Options

• --url <url>: Gateway WebSocket URL (defaults to config or ws://127.0.0.1:<port>)

• --token <token>: Gateway token (if required)

• --password <password>: Gateway 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 milliseconds (defaults to agents.defaults.timeoutSeconds)

Troubleshooting

No output after sending a message:

• Run /status in TUI to confirm Gateway is connected and idle/busy.

• Check Gateway logs: openclaw logs --follow.

• Confirm agents can run: openclaw status and openclaw models status.

• If you expect messages to appear in the chat channel, enable delivery (/deliver on or --deliver).

• --history-limit <n>: Number of history entries to load (default 200)

Troubleshooting

• disconnected: Ensure Gateway is running and your --url/--token/--password are correct.

• No agents in selector: Check openclaw agents list and your routing config.

• Empty session selector: You may be in global scope or don't have any sessions yet.

For more about TUI, see: TUI - OpenClaw