openclaw tui command: start Gateway-backed or local terminal UI
Reference for the openclaw tui command. Learn how to launch the terminal UI in Gateway or local embedded mode, with options for URL, token, password, and TLS fingerprint.
Read this when
- You want a terminal UI for the Gateway (remote-friendly)
- You want to pass url/token/session from scripts
- You want to run the TUI in local embedded mode without a Gateway
- You want to use openclaw chat or openclaw tui --local
openclaw tui
Start the terminal UI connected to the Gateway, or launch it in local embedded mode.
Related documentation: TUI
Options
| Flag | Default | Description |
|---|---|---|
--local | false | Use the local embedded agent runtime instead of connecting to a Gateway. |
--url <url> | gateway.remote.url from config | WebSocket address for the Gateway. |
--token <token> | (none) | Gateway token, when authentication requires one. |
--password <pass> | (none) | Gateway password, if authentication demands it. |
--tls-fingerprint <sha256> | gateway.remote.tlsFingerprint | Expected TLS certificate fingerprint for a pinned wss:// Gateway. |
--session <key> | main (or global when scope is global) | Session key. Within an agent workspace, it defaults to that agent unless a prefix is given. |
--deliver | false | Send assistant responses through any configured channels. |
--thinking <level> | (model default) | Override the thinking level. |
--message <text> | (none) | Transmit a starting message after the connection is established. |
--timeout-ms <ms> | agents.defaults.timeoutSeconds | Agent timeout period. Invalid values produce a warning and are disregarded. |
--history-limit <n> | 200 | Number of history entries loaded when attaching. |
Aliases: openclaw chat and openclaw terminal run this command with
--local assumed.
Notes
--localis incompatible with--url,--token,--password, and--tls-fingerprint.tuiresolves configured Gateway auth SecretRefs for token or password authentication when feasible (env/file/execproviders).- Without an explicit URL or port,
tuiuses the active local Gateway port that the running Gateway recorded. Explicit--url,OPENCLAW_GATEWAY_URL,OPENCLAW_GATEWAY_PORT, and remote Gateway configuration take priority. - When started inside a configured agent workspace directory, the TUI automatically selects that agent for the default session key (unless
--sessionis explicitlyagent:<id>:...). - Local mode works directly with the embedded agent runtime. Most local tools function, but Gateway-only capabilities are absent.
- Local mode adds
/auth [provider]to the TUI command surface. - Plugin approval gates remain active in local mode: tools needing approval prompt for a decision in the terminal, nothing is silently auto-approved.
- Session goals display in the footer and can be handled with
/goal.
Examples
openclaw chat
openclaw tui --local
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
openclaw chat --message "Compare my config to the docs and tell me what to fix"
# when run inside an agent workspace, infers that agent automatically
openclaw tui --session bugfix
Config repair loop
Employ local mode so the embedded agent inspects the current config, compares it against the documentation, and assists in fixing it from the same terminal.
If openclaw config validate is already failing, execute openclaw configure or
openclaw doctor --fix first; openclaw chat does not bypass the
invalid-config guard.
openclaw chat
Then within the TUI:
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
Apply targeted corrections with openclaw config set or openclaw configure, then
rerun openclaw config validate. Refer to TUI and
Config.