Use this file to discover all available pages before exploring further.
TUI
Quick start
Gateway mode
- Start the Gateway.
- Open the TUI.
- Type a message and press Enter.
Remote Gateway:
openclaw tui --url ws://<host>:<port> --token <gateway-token>
Use
if your Gateway uses password auth.
Local mode
Run the TUI without a Gateway:
openclaw chat
# or
openclaw tui --local
Notes:
- and are aliases for .
- cannot be combined with , , or .
- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
- and also use this TUI shell, with Crestodian as the local setup and repair chat backend.
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/trace/reasoning + token counts + deliver.
- Input: text editor with autocomplete.
Mental model: agents + sessions
- Agents are unique slugs (e.g. , ). The Gateway exposes the list.
- Sessions belong to the current agent.
- Session keys are stored as
agent:<agentId>:<sessionKey>
- If you type , the TUI expands it to
agent:<currentAgent>:main
- If you type
/session agent:other:main
- Session scope:
- (default): each agent has many sessions.
- : the TUI always uses the session (the picker may be empty).
- The current agent + session are always visible in the footer.
Sending + delivery
- Messages are sent to the Gateway; delivery to providers is off by default.
- Turn delivery on:
- or the Settings panel
- or start with
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:
Session controls:
/think <off|minimal|low|medium|high>
/reasoning <on|off|stream>
/elevated <on|off|ask|full>
/activation <mention|always>
Session lifecycle:
- or (reset the session)
- (abort the active run)
Local mode only:
- opens the provider auth/login flow inside the TUI.
Other Gateway slash commands (for example,
) are forwarded to the Gateway 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 /env).
- Local shell commands receive in their environment.
- A lone is sent as a normal message; leading spaces do not trigger local exec.
Repair configs from the local TUI
Use local mode when the current config already validates and you want the
embedded agent to inspect it on the same machine, compare it against the docs,
and help repair drift without depending on a running Gateway.
If
is already failing, start with
or
first.
does not bypass the invalid-
config guard.
Typical loop:
- Start local mode:
- Ask the agent what you want checked, for example:
Compare my gateway auth config with the docs and suggest the smallest fix.
- Use local shell commands for exact evidence and validation:
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
- Apply narrow changes with or , then rerun
!openclaw config validate
- If Doctor recommends an automatic migration or repair, review it and run .
Tips:
- Prefer or over hand-editing .
- searches the live docs index from the same machine.
openclaw config validate --json
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 before launching .
- To force the original dark palette instead, set .
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 with the Gateway as .
- Reconnects show a system message; event gaps are surfaced in the log.
Options
- : Run against the local embedded agent runtime
- : Gateway WebSocket URL (defaults to config or )
- : Gateway token (if required)
- : Gateway password (if required)
- : Session key (default: , or when scope is global)
- : Deliver assistant replies to the provider (default off)
- : Override thinking level for sends
- : Send an initial message after connecting
- : Agent timeout in ms (defaults to
agents.defaults.timeoutSeconds
- : History entries to load (default )
warning
When you set `--url`, the TUI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error. In local mode, do not pass `--url`, `--token`, or `--password`.
Troubleshooting
No output after sending a message:
- Run in the TUI to confirm the Gateway is connected and idle/busy.
- Check the Gateway logs: .
- Confirm the agent can run: and .
- If you expect messages in a chat channel, enable delivery ( or ).
Connection troubleshooting
- : ensure the Gateway is running and your are correct.
- No agents in picker: check and your routing config.
- Empty session picker: you might be in global scope or have no sessions yet.
Related