Launch OpenClaw TUI: Terminal Interface Quick Start Guide

You are deep in your terminal, writing code or managing servers, and you need to consult your AI agent. Switching to a web browser feels like a chore that breaks your focus. You want a tool that stays in your environment and responds as fast as you type.

The TUI (Terminal UI) is built for exactly this. It gives you a powerful interface for interacting with your agents without ever leaving your command line.

Quick start

Getting started is simple. First, you need to have your Gateway running.

1. Start the Gateway.

openclaw gateway

2. Open the TUI.

openclaw tui

3. Type a message and press Enter.

If you are connecting to a Remote Gateway, use this command:

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

Use --password if your Gateway uses password auth.

What you see

The interface is designed to give you all the information you need at a glance:

• Header: Shows your connection URL, the current agent, and the current session.
• Chat log: This is where you see user messages, assistant replies, system notices, and tool cards.
• Status line: Displays the connection and run state (connecting, running, streaming, idle, or error).
• Footer: A dense info bar showing connection state, agent, session, model, settings (think/fast/verbose/reasoning), token counts, and delivery status.
• Input: A text editor that supports autocomplete to help you type faster.

Mental model: agents + sessions

Understanding how the TUI organizes your work is key. It uses two main concepts:

• Agents are unique slugs (like main or research). The Gateway provides this list.
• Sessions belong to the current agent.

Session keys follow a specific format: agent:<agentId>:<sessionKey>.

• If you type /session main, the TUI automatically expands it to agent:<currentAgent>:main.
• If you want to switch explicitly, you can type /session agent:other:main.

Session scope works in two ways:

• per-sender (default): Each agent can have many sessions.
• global: The TUI always uses the global session, and the picker might be empty.

You can always check the footer to see which agent and session are active.

Sending + delivery

When you type a message, it goes to the Gateway. However, delivery to providers is turned off by default. You have to tell the TUI when you want the assistant to actually reply.

You can turn delivery on by:

• Typing /deliver on
• Using the Settings panel
• Starting the TUI with openclaw tui --deliver

Pickers + overlays

The TUI includes several overlays to help you manage your configuration:

• Model picker: View available models and set a session override.
• Agent picker: Choose a different agent to talk to.
• Session picker: See the sessions available for your current agent.
• Settings: A quick way to toggle delivery, tool output expansion, and thinking visibility.

Keyboard shortcuts

Speed is the whole point of a TUI. Use these shortcuts to move faster:

• 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 (this reloads history)

Slash commands

Commands give you direct control over the session.

Core commands:

• /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 Gateway slash commands, such as /context, are forwarded to the Gateway and appear as system output. You can find more details in the Slash commands documentation.

Local shell commands

You can run local shell commands directly from the TUI. Just prefix a line with !.

The TUI will ask for permission once per session before running local commands. If you decline, ! stays disabled for that session. These commands run in a fresh, non-interactive shell in the TUI’s working directory. Note that there is no persistent environment or directory change between commands.

Local shell commands have OPENCLAW_SHELL=tui-local set in their environment. If you type a lone !, it is treated as a normal message. Leading spaces will not trigger a local execution.

Tool output

When an agent calls a tool, it appears as a card showing the arguments and results.

• Use Ctrl+O to toggle between collapsed and expanded views.
• While a tool is running, you will see partial updates streaming into the card.

Terminal colors

The TUI is built to look good in any environment. It keeps the assistant’s text in your terminal’s default foreground color so it is readable on both dark and light backgrounds.

If the auto-detection fails for your light terminal, set OPENCLAW_THEME=light before you launch. To force the dark palette, use OPENCLAW_THEME=dark.

History + streaming

When you connect, the TUI pulls the latest history. By default, it loads the last 200 messages. Responses from the agent stream in real-time, updating in place until they are finished. The TUI also tracks agent tool events to provide detailed tool cards.

Connection details

The TUI identifies itself to the Gateway using mode: "tui". If the connection drops, you will see a system message when it reconnects. Any gaps in events during the disconnection are highlighted in the log.

Options

You can customize the TUI behavior with these CLI flags:

• --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 ms (defaults to agents.defaults.timeoutSeconds)

Note that when you set --url, the TUI won’t look for credentials in your config or environment. You must pass --token or --password explicitly.

Troubleshooting

If you aren’t seeing any output after sending a message, try these steps:

• Run /status in the TUI to see if the Gateway is connected or busy.
• Check the Gateway logs with openclaw logs --follow.
• Verify the agent is ready with openclaw status and openclaw models status.
• Make sure delivery is enabled with /deliver on or the --deliver flag.
• Use --history-limit <n> if you need to load more than the default 200 entries.

Connection troubleshooting

• “disconnected”: Check if the Gateway is running and verify your --url, --token, or --password.
• No agents in picker: Run openclaw agents list and check your routing configuration.
• Empty session picker: This happens if you are in global scope or haven’t created any sessions yet.

Related

• Control UI — web-based control interface
• CLI Reference — full CLI command reference

Next steps

• Learn more about Slash commands
• Explore the CLI Reference

Need help getting everything configured? Check out the AI Setup Assistant.