OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

openclaw tui

openclaw tui

Open the terminal UI connected to the Gateway, or run it in local embedded mode.

bash
openclaw tui [target]

target can be a Control UI session URL, a compact host/agent/ref, a bare short reference such as movies-a1166b81, or a literal agent:... session key. A URL or host target authoritatively selects that Gateway; a bare reference uses the configured or default Gateway. You can also paste a Control UI URL directly as openclaw <url> and place the TUI options before or after it, for example openclaw <url> --token <token> --deliver.

The bare-URL form accepts --token, --password, --tls-fingerprint, --deliver, --thinking, --message, --timeout-ms, and --history-limit. URL-valued messages work in either position, including openclaw --message https://example.com/article <url>. Use openclaw tui <url> when you need another TUI option; --local, --url, and --session conflict with a session URL.

Related guide: TUI

Options

Flag Default Description
--local false Run against the local embedded agent runtime instead of a Gateway.
--url <url> gateway.remote.url from config Gateway WebSocket URL.
--token <token> (none) Gateway token if required.
--password <pass> (none) Gateway password if required.
--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. Inside an agent workspace it auto-selects that agent unless prefixed.
--deliver false Deliver assistant replies through configured channels.
--thinking <level> (model default) Thinking level override.
--message <text> (none) Send an initial message after connecting.
--timeout-ms <ms> agents.defaults.timeoutSeconds Agent timeout. Invalid values log a warning and are ignored.
--history-limit <n> 200 History entries to load on attach.

Aliases: openclaw chat and openclaw terminal invoke this command with --local implied.

Notes

  • --local cannot combine with --url, --token, --password, or --tls-fingerprint.
  • Pass only one Gateway target. A URL target cannot combine with --url, and any positional target cannot combine with --session or local mode.
  • A URL or host target never reuses configured credentials or OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD. It uses the stored device token for that exact Gateway origin, or explicit --token/--password credentials. On first contact, pass one of those credentials once, approve the pairing request in that Gateway's Control UI, and retry; see Devices.
  • Session URLs must stay credential-free. Userinfo and sensitive query or fragment parameters such as token and password are rejected.
  • Short references resolve through the Gateway. If a short reference is ambiguous, the CLI prints candidate names and longer ID prefixes without attaching to either session.
  • With no URL/host target or explicit --url, tui resolves configured Gateway auth SecretRefs for token/password auth when possible (env/file/exec/store providers).
  • When the configured remote Gateway is behind an identity-aware proxy, tui resolves gateway.remote.edgeAuth SecretInputs and sends those headers only to that configured Gateway scope. URL or host targets for other origins never inherit them.
  • With no explicit URL or port, tui follows the active local Gateway port recorded by the running Gateway. Explicit --url, OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_PORT, and remote Gateway config keep precedence.
  • Launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless --session is explicitly agent:<id>:...).
  • Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
  • Local mode requires exclusive ownership of the configured state directory. It refuses to start while a Gateway or another embedded writer owns that state; run without --local to use the active Gateway, or stop it first with openclaw gateway stop.
  • Local mode adds /auth [provider] to the TUI command surface.
  • Plugin approval gates still apply in local mode: tools that require approval prompt for a decision in the terminal, nothing is silently auto-approved.
  • ask_user questions appear as interactive prompts in both modes. Esc collapses a prompt without answering; /question reopens it.
  • Gateway mode accepts secrets requests in a masked input with a read-only allowed-host list. Local mode cannot fulfill store-bound requests; use openclaw secrets store or the Control UI with a running Gateway.
  • Session goals appear in the footer and can be managed with /goal.

Session target errors

Failure Recovery
The Gateway predates short-link resolution Copy the full session key from that Gateway's Control UI.
Session missing or short ref ambiguous For the configured/local Gateway, run openclaw sessions list; for a URL/host target, choose a longer or full key in that Gateway's Control UI.
Gateway unreachable The error names the selected origin. For a *.ts.net host, connect Tailscale and confirm the Gateway is reachable on the tailnet.
Identity-aware proxy rejected the upgrade Configure gateway.remote.edgeAuth for the configured remote Gateway; the error includes the relevant remote-access docs link.
Stored device token revoked or rotated Rotate it with openclaw devices rotate --device <deviceId> --role operator, then reconnect.
TLS certificate pin mismatch The original TLS fingerprint error passes through unchanged; verify the configured or explicit pin before retrying.

Examples

bash
openclaw chatopenclaw tui --localopenclaw tuiopenclaw tui https://gateway.example/dashboard/main/movies-a1166b81openclaw https://gateway.example/dashboard/main/movies-a1166b81 --token <token>openclaw tui movies-a1166b81openclaw tui --url ws://127.0.0.1:18789 --token <token>openclaw tui --session main --deliveropenclaw chat --message "Compare my config to the docs and tell me what to fix"# when run inside an agent workspace, infers that agent automaticallyopenclaw tui --session bugfix

Config repair loop

Use local mode to have the embedded agent inspect the current config, compare it against the docs, and help repair it from the same terminal.

If openclaw config validate is already failing, run openclaw configure or openclaw doctor --fix first; openclaw chat does not bypass the invalid-config guard.

bash
openclaw chat

Then inside the TUI:

text
!openclaw config file!openclaw docs gateway auth token secretref!openclaw config validate!openclaw doctor

Apply targeted fixes with openclaw config set or openclaw configure, then rerun openclaw config validate. See TUI and Config.

Was this useful?
On this page

On this page