Skip to main content

​
openclaw tui

Open the terminal UI connected to the Gateway, or run it in local embedded mode.
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 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. Use openclaw tui <url> when you need another TUI option; --local, --url, and --session conflict with a session URL. Related guide: TUI

​
Options

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.
  • Session goals appear in the footer and can be managed with /goal.

​
Session target errors

​
Examples

​
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.
Then inside the TUI:
Apply targeted fixes with openclaw config set or openclaw configure, then rerun openclaw config validate. See TUI and Config.