TUI — Terminal User Interface

+15 Mana ✨
OpenClaw TUI(DOCUMENTATION)

Introduction

The OpenClaw TUI (Terminal User Interface) provides a rich terminal-based client for interacting with your gateway. It supports session management, thinking level configuration, multi-agent switching, and real-time streaming — all from your terminal.

Key Concepts

  • TUI Client: A terminal-based interface that connects to an OpenClaw gateway for interactive conversations.
  • Session Management: Create, resume, and switch between conversation sessions within the TUI.
  • Thinking Levels: Configure how much reasoning the agent shows: none, brief, detailed.
  • Gateway Connection: The TUI connects to a gateway via its host and port, supporting both local and remote gateways.

Real World Context

A DevOps engineer SSHs into a production server to investigate an issue. They launch the OpenClaw TUI to interact with their deployment agent directly from the server's terminal. No web browser or desktop app needed — just a terminal connection.

Deep Dive

Launch the TUI and connect to a gateway:

bash
# Connect to local gateway
openclaw tui

# Connect to remote gateway
openclaw tui --host gateway.example.com --port 18789

# Connect with a specific agent
openclaw tui --agent deployer

The openclaw tui command opens the terminal interface. Without arguments, it connects to localhost:18789. The --host and --port flags specify a remote gateway. The --agent flag selects which agent to converse with.

Within the TUI, keyboard shortcuts manage the session:

Keybindings:
  Ctrl+N    New session
  Ctrl+S    Switch session
  Ctrl+T    Change thinking level
  Ctrl+A    Switch agent
  Ctrl+C    Cancel current generation
  Ctrl+D    Exit TUI

Thinking levels control the visibility of agent reasoning:

bash
# In the TUI, press Ctrl+T to cycle through:
# none     → Agent shows only the final response
# brief    → Agent shows a one-line reasoning summary
# detailed → Agent shows full chain-of-thought reasoning

Thinking levels help with debugging — detailed mode shows exactly why the agent made each decision, while none mode keeps the output clean for production use.

Session management lets you maintain multiple conversations:

bash
# Sessions are listed with:
# [1] Deployment debugging (active)
# [2] Code review - PR #42
# [3] Infrastructure planning

# Press Ctrl+S and select a session number to switch

Each session maintains its own conversation history, context, and state.

Common Pitfalls

  1. Forgetting to specify the agent — Without --agent, the TUI connects to the default agent, which may not be what you want.
  2. Terminal encoding issues — The TUI uses Unicode for its interface. Ensure your terminal supports UTF-8 encoding.

Best Practices

  1. Use thinking levels for debugging — Switch to detailed when the agent's behavior is unexpected, then back to none for normal use.
  2. Name sessions descriptively — Use Ctrl+N to create named sessions like "PR review" or "deploy check" for easy switching.

Summary

  • The TUI provides a full-featured terminal client for OpenClaw gateways
  • Connect to local or remote gateways with optional agent selection
  • Session management supports multiple concurrent conversations
  • Thinking levels (none, brief, detailed) control reasoning visibility
  • Keyboard shortcuts provide quick access to all TUI features
✓ Completed