- Launch the TUI with
openclaw tui— it connects to your running gateway automatically - Three panels: Agents (status and health), Channels (active connections), Logs (real-time output)
- Tab cycles panels, Enter selects, R refreshes, Q quits — press ? for the full shortcut list
- You can send messages to agents directly from the TUI without opening a messaging client
- TUI wins on SSH servers and headless environments; the dashboard wins for shared team visibility
Most builders discover the OpenClaw TUI by accident — they run openclaw tui expecting a help menu and suddenly they're looking at a full live monitoring dashboard inside their terminal. Five minutes with the keyboard shortcuts and you'll never go back to tailing log files manually.
What the OpenClaw TUI Actually Is
The TUI (Terminal User Interface) is a fully interactive, keyboard-driven control panel built into the OpenClaw CLI. It renders inside your terminal using text-based graphics — no browser, no web server, no JavaScript. Everything updates in real time as your gateway processes events.
Under the hood, the TUI connects to your local gateway over the same WebSocket interface that agents use. It reads status streams, log events, and channel state, then renders them across three panels simultaneously. As of early 2025, the TUI is bundled with OpenClaw v1.4+ and requires no separate installation.
Here's what makes it genuinely useful: latency. When you're debugging a broken channel or an agent that stopped responding, tailing a log file means switching windows, running grep, waiting for output. The TUI shows everything in one place with zero switching cost.
The TUI doesn't start the gateway — it connects to one. Run openclaw gateway start (or ensure your systemd service is active) before launching openclaw tui. If the gateway isn't reachable, the TUI will show a connection error at the bottom status bar.
Launching the TUI
Starting the TUI is one command:
# Start TUI connecting to default gateway (localhost:8080)
openclaw tui
# Connect to a remote gateway
openclaw tui --gateway https://your-gateway.example.com
# Connect with explicit token (overrides config file)
openclaw tui --token your-gateway-tokenThe TUI reads your gateway URL and token from the same config file as the rest of the CLI — typically ~/.openclaw/config.yaml. If you've already configured OpenClaw for your setup, running bare openclaw tui is all you need.
The screen initializes in about one second as the TUI handshakes with the gateway and fetches initial state. You'll see the three-panel layout appear, populated with your current agent and channel data.
The Three Panels Explained
The TUI divides your terminal into three columns. Understanding what each panel shows is the difference between using it as a monitoring tool and using it as a control surface.
Agents Panel (Left)
The left panel lists every agent currently registered with your gateway. Each entry shows the agent name, current status (online / offline / error), the model it's using, and time since last activity. A red indicator means the agent hasn't sent a heartbeat in the configured interval — which typically means it's crashed or the process died.
Select an agent with Enter to see its full configuration inline: soul.md path, identity.md path, enabled skills, memory settings, and the channels it's connected to.
Channels Panel (Center)
The center panel shows all active message channels. Each channel entry displays the channel ID, channel type (Telegram, WhatsApp, API, etc.), connection health, and message volume in the last 60 seconds. Channels highlighted in yellow are experiencing elevated latency. Channels in red have lost connection to the upstream platform.
Logs Panel (Right)
The right panel streams live log output from your gateway and all connected agents. Log lines are color-coded by severity: white for INFO, yellow for WARN, red for ERROR. Press L to cycle through log level filters — this is how you cut through noise when debugging a specific issue.
In a busy multi-agent setup, the log panel fills fast. Press L repeatedly to cycle: ALL → WARN → ERROR → ALL. When you're chasing a specific error, filter to ERROR first — you'll see exactly what's failing without scrolling through thousands of INFO lines.
Keyboard Shortcuts Reference
The TUI is keyboard-only. Learning eight shortcuts gives you 90% of the functionality.
| Key | Action |
|---|---|
| Tab | Cycle to next panel |
| Shift+Tab | Cycle to previous panel |
| ↑ ↓ | Navigate within current panel |
| Enter | Select item / open detail view |
| R | Force refresh all panel data |
| L | Cycle log level filter |
| F | Open filter input for current panel |
| M | Open message input for selected channel |
| Esc | Close dialog / cancel input |
| Q / Ctrl+C | Quit the TUI |
Press ? at any time inside the TUI to see the full shortcut reference overlay. It covers every key including the ones you'll only use occasionally — like E to export the current log view to a file.
TUI vs Web Dashboard: When to Use Each
Both exist for a reason. Knowing which to reach for stops you from fighting the wrong tool.
The TUI wins when you're SSH'd into a server, when you want zero latency feedback during active debugging, when you want to watch logs and agent status simultaneously without any browser overhead, or when you're working on a headless machine with no display server.
The dashboard wins when you need to share status with teammates who aren't comfortable with a terminal, when you need visual charts and historical metrics rather than a real-time stream, when you're checking in from a phone or tablet, or when you want to grant read-only monitoring access without giving someone CLI access to your server.
The practical answer: use both. TUI during active development and debugging sessions. Dashboard for ongoing operations monitoring and team communication. They access the same underlying gateway data — choose based on the situation, not habit.Common TUI Mistakes
- Running the TUI before starting the gateway — the TUI shows a connection error and many people assume something is broken. Start the gateway first, then open the TUI.
- Quitting with Ctrl+Z instead of Q — Ctrl+Z suspends the process into the background without closing the connection. Use Q or Ctrl+C to exit cleanly. Run
jobsto check for suspended TUI processes if your terminal feels slow. - Not using the filter (F) when looking for a specific agent — in a 20-agent setup, scrolling the agents panel is painful. Press F, type the agent name, and the list filters instantly.
- Ignoring the status bar at the bottom — the bottom bar shows gateway connection latency, total message throughput, and any active warnings. It's the first thing to check when something feels slow.
- Running the TUI on a terminal narrower than 120 columns — the three-panel layout collapses badly on narrow terminals. Set your terminal to at least 120×40 for the full layout.
Frequently Asked Questions
How do I open the OpenClaw TUI?
Run openclaw tui from your terminal after installing OpenClaw. The TUI connects to your running gateway automatically using your config file settings. If the gateway isn't running, start it first with openclaw gateway start — the TUI will display a connection error otherwise.
What are the main panels in the OpenClaw TUI?
The TUI has three panels: Agents (left) showing all registered agents and their status, Channels (center) showing active message channels and health, and Logs (right) showing real-time gateway and agent log output. Use Tab or arrow keys to move between panels.
What keyboard shortcuts does the OpenClaw TUI support?
Core shortcuts: Tab cycles panels, Enter selects, Q or Ctrl+C quits, R refreshes, L toggles log level filter, F opens a filter input, and Esc closes dialogs. Arrow keys navigate within panels. Press ? inside the TUI for the full shortcut reference.
Can I send messages to agents from the TUI?
Yes. Select a channel in the Channels panel and press M to open the message input. Type your message and press Enter to send. The agent's response appears in the channel view in real time — useful for quick tests without switching to a messaging client.
Is the TUI better than the OpenClaw web dashboard?
TUI wins for server environments without a browser, SSH sessions, and low-latency monitoring. The dashboard wins for visual metrics, multi-user access, and team visibility. Most power users run both — TUI during active development, dashboard for ongoing monitoring.
Why does the TUI show "Connection refused" on startup?
This means the TUI cannot reach your gateway. Check that the gateway is running with openclaw status. Verify the gateway URL in your config matches where the gateway is actually listening. If running locally, ensure port 8080 (or your custom port) is not blocked by a firewall.
T. Chen designs and deploys multi-agent OpenClaw systems for production environments. Has built monitoring setups for teams running 30+ concurrent agents across Telegram, WhatsApp, and API channels, and contributed operational tooling guides to the OpenClaw community.