github/openclaw
1
1
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-02-19 18:39:20 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
ff948a6dd7bb0ae1cd257541c1bb6715e07e91c5
openclaw/docs/tui.md
Gustavo Madeira Santana a13ff55bd9 Security: Prevent gateway credential exfiltration via URL override (#9179) 
* Gateway: require explicit auth for url overrides

* Gateway: scope credential blocking to non-local URLs only

Address review feedback: the previous fix blocked credential fallback for
ALL URL overrides, which was overly strict and could break workflows that
use --url to switch between loopback/tailnet without passing credentials.

Now credential fallback is only blocked for non-local URLs (public IPs,
external hostnames). Local addresses (127.0.0.1, localhost, private IPs
like 192.168.x.x, 10.x.x.x, tailnet 100.x.x.x) still get credential
fallback as before.

This maintains the security fix (preventing credential exfiltration to
attacker-controlled URLs) while preserving backward compatibility for
legitimate local URL overrides.

* Security: require explicit credentials for gateway url overrides (#8113) (thanks @victormier)

* Gateway: reuse explicit auth helper for url overrides (#8113) (thanks @victormier)

* Tests: format gateway chat test (#8113) (thanks @victormier)

* Tests: require explicit auth for gateway url overrides (#8113) (thanks @victormier)

---------

Co-authored-by: Victor Mier <victormier@gmail.com>
2026-02-04 18:59:44 -05:00

5.2 KiB
Raw Blame History

summary, read_when, title
summary read_when title
Terminal UI (TUI): connect to the Gateway from any machine
You want a beginner-friendly walkthrough of the TUI
You need the complete list of TUI features, commands, and shortcuts
TUI

TUI (Terminal UI)

Quick start

  1. Start the Gateway.
openclaw gateway
  1. Open the TUI.
openclaw tui
  1. Type a message and press Enter.

Remote Gateway:

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

Use --password if your Gateway uses password auth.

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/verbose/reasoning + token counts + deliver.
  • Input: text editor with autocomplete.

Mental model: agents + sessions

  • Agents are unique slugs (e.g. main, research). The Gateway exposes the list.
  • Sessions belong to the current agent.
  • Session keys are stored as agent:<agentId>:<sessionKey>.
    • If you type /session main, the TUI expands it to agent:<currentAgent>:main.
    • If you type /session agent:other:main, you switch to that agent session explicitly.
  • Session scope:
    • per-sender (default): each agent has many sessions.
    • global: the TUI always uses the global 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:
    • /deliver on
    • or the Settings panel
    • or start with openclaw tui --deliver

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:

  • /help
  • /status
  • /agent <id> (or /agents)
  • /session <key> (or /sessions)
  • /model <provider/model> (or /models)

Session controls:

  • /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 the session)
  • /abort (abort the active run)
  • /settings
  • /exit

Other Gateway slash commands (for example, /context) 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 cd/env).
  • A lone ! is sent as a normal message; leading spaces do not trigger local exec.

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.

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 mode: "tui".
  • Reconnects show a system message; event gaps are surfaced 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 ms (defaults to agents.defaults.timeoutSeconds)

Note: 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.

Troubleshooting

No output after sending a message:

  • Run /status in the TUI to confirm the Gateway is connected and idle/busy.
  • Check the Gateway logs: openclaw logs --follow.
  • Confirm the agent can run: openclaw status and openclaw models status.
  • If you expect messages in a chat channel, enable delivery (/deliver on or --deliver).
  • --history-limit <n>: History entries to load (default 200)

Troubleshooting

  • disconnected: ensure the Gateway is running and your --url/--token/--password are correct.
  • No agents in picker: check openclaw agents list and your routing config.
  • Empty session picker: you might be in global scope or have no sessions yet.
Reference in New Issue View Git Blame Copy Permalink