openclaw tui Command Reference: Gateway and Local Terminal UI
Reference for launching the openclaw TUI, either connected to a Gateway or in local embedded mode. Covers target selection, flags, and URL usage for developers and operators.
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
Launch the Gateway-connected terminal interface, or start it in local embedded mode.
openclaw tui [target]
target accepts a Control UI session URL, a compact host/agent/ref, a short
reference like movies-a1166b81, or an explicit agent:... session key. When you
supply a URL or host, that Gateway is selected directly; otherwise, a bare
reference falls back to the configured or default Gateway. A Control UI URL
can also be pasted directly as openclaw <url>, with TUI flags following it, such as
openclaw <url> --token <token> --deliver.
The bare-URL variant supports --token, --password, --tls-fingerprint,
--deliver, --thinking, --message, --timeout-ms, and --history-limit.
For additional TUI options, use openclaw tui <url>; note that --local, --url,
and --session clash with a session URL.
See the guide: TUI
Options
| Flag | Default | Description |
|---|---|---|
--local | false | Use the local embedded agent runtime rather than a Gateway. |
--url <url> | gateway.remote.url from config | WebSocket URL for the Gateway. |
--token <token> | (none) | Gateway token, when one is needed. |
--password <pass> | (none) | Gateway password, when one is needed. |
--tls-fingerprint <sha256> | gateway.remote.tlsFingerprint | TLS certificate fingerprint expected for a pinned wss:// Gateway. |
--session <key> | main (or global when scope is global) | Session key. Within an agent workspace, it picks that agent automatically unless prefixed. |
--deliver | false | Route assistant responses through configured channels. |
--thinking <level> | (model default) | Override the thinking level. |
--message <text> | (none) | Send a first message once connected. |
--timeout-ms <ms> | agents.defaults.timeoutSeconds | Agent timeout. Invalid values trigger a warning and are disregarded. |
--history-limit <n> | 200 | Number of history entries to fetch on attach. |
Aliases: openclaw chat and openclaw terminal run this command with
--local assumed.
Notes
--localis incompatible with--url,--token,--password, or--tls-fingerprint.- Specify exactly one Gateway target. A URL target cannot be paired with
--url, and any positional target cannot be paired with--sessionor local mode. - A URL or host target does not reuse stored credentials or
OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD. It relies on the device token saved for that exact Gateway origin, or on explicit--token/--passwordcredentials. On the first connection, provide one of those credentials once, approve the pairing request in that Gateway's Control UI, and try again; refer to Devices. - Session URLs must contain no credentials. Userinfo and sensitive query or fragment parameters like
tokenandpasswordare refused. - Short references are resolved via the Gateway. When a short reference is unclear, the CLI lists candidate names and longer ID prefixes without connecting to either session.
- Without a URL/host target or explicit
--url,tuiresolves configured Gateway auth SecretRefs for token/password auth when feasible (env/file/exec/storeproviders). - When the configured remote Gateway sits behind an identity-aware proxy,
tuiresolvesgateway.remote.edgeAuthSecretInputs and forwards those headers solely to that configured Gateway scope. URL or host targets for other origins never receive them. - With no explicit URL or port,
tuiuses the active local Gateway port that the running Gateway records. Explicit--url,OPENCLAW_GATEWAY_URL,OPENCLAW_GATEWAY_PORT, and remote Gateway config take precedence. - When launched from within a configured agent workspace directory, TUI auto-selects that agent as the default session key (unless
--sessionis explicitlyagent:<id>:...). - Local mode runs the embedded agent runtime directly. Most local tools function, but Gateway-only features are not available.
- Local mode needs exclusive access to the configured state directory. It will not start while a Gateway or another embedded writer holds that state; run without
--localto use the active Gateway, or halt it first withopenclaw 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.
- Session goals show in the footer and can be handled 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
openclaw chat
openclaw tui --local
openclaw tui
openclaw tui https://gateway.example/dashboard/main/movies-a1166b81
openclaw https://gateway.example/dashboard/main/movies-a1166b81 --token <token>
openclaw tui movies-a1166b81
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
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.
openclaw chat
Then inside the TUI:
!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.