TUI Guide: Gateway & Local Modes

Quick start

Gateway mode

Launch the Gateway.

openclaw gateway

Bring up the TUI.

openclaw tui

Enter a message and hit Enter.

Remote Gateway:

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

When your Gateway relies on password authentication, use --password.

Local mode

Launch the TUI without a Gateway:

openclaw chat
# or
openclaw tui --local

openclaw chat and openclaw terminal both point to the same command as openclaw tui --local.
--local cannot be used alongside --url, --token, or --password.
Running in local mode taps into the embedded agent runtime directly. Most local tools function as expected, but anything tied to Gateway-only features will not work.
Calling openclaw on its own, with no subcommand, selects a target automatically: a fresh install with no configuration triggers inference onboarding; invalid configuration brings up classic doctor guidance; a configured Gateway that is reachable opens this TUI shell in gateway mode; otherwise a configured local model launches it in local mode.

What you see

Header: connection URL, active agent, active session.
Chat log: user input, assistant responses, system notifications, tool cards.
Status line: connection or run state (connecting, running, streaming, idle, error).
Footer: agent, session, model, goal state, think/fast/verbose/trace/reasoning, token counts, and deliver.
Input: a text editor featuring autocomplete.

Mental model: agents + sessions

Agents are unique slugs, for example main or research. The Gateway provides the list.
Sessions are tied to the agent currently in use.
Session keys are saved under agent:<agentId>:<sessionKey>.
- Typing /session main causes the TUI to expand it into agent:<currentAgent>:main.
- Typing /session agent:other:main moves you explicitly to that agent's session.
Session scope:
- per-sender (the default): every agent can have multiple sessions.
- global: the TUI consistently relies on the global session, and the picker may show nothing.
The footer always displays the current agent and session.
When a session has a goal, the footer shows its compact state as Pursuing goal, Goal paused (/goal resume), Goal blocked (/goal resume), or Goal achieved.
If launched without --session, the gateway-mode TUI resumes the most recently selected session for the same gateway, agent, and session scope, provided that session is still around. Supplying --session, /session, /new, or /reset keeps the choice explicit.

Sending + delivery

Every message is sent to the Gateway, or to the embedded runtime in local mode; pushing the assistant's reply back out to a chat provider is a separate step that is off by default.
The TUI functions as an internal source surface, much like WebChat, rather than a generic outbound channel. Harnesses that need tools.message for visible replies can satisfy the active TUI turn with a targetless message.send; explicit provider delivery still goes through normal configured channels and never falls back to lastChannel.
Delivery is locked in for the entire TUI session when it starts: launch with openclaw tui --deliver to enable it. No /deliver slash command or Settings toggle exists to change it mid-session; you must restart the TUI to alter it.

Pickers + overlays

Model picker: view available models and assign a session override.
Agent picker: switch to a different agent.
Session picker: displays up to 50 sessions for the current agent that were updated in the last 7 days. Use /session <key> to jump to an older known session.
Settings (/settings): control tool output expansion and thinking visibility. This panel does not manage delivery.

Keyboard shortcuts

Enter: send message
Shift+Enter or Ctrl+J: insert a newline without sending
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 (forwarded by the Gateway; shows session/model summary)
/gateway-status (alias /gwstatus; shows Gateway connection status directly)
/agent <id> (or /agents)
/session <key> (or /sessions)
/model <provider/model> (or /models)

Session controls:

/think <off|minimal|low|medium|high> (higher tiers may add levels like xhigh/max depending on the model)
/fast <status|auto|on|off>
/verbose <on|full|off>
/trace <on|off>
/reasoning <on|off|stream>
/usage <off|tokens|full|reset> (reset/inherit/clear/default clears the session override)
/goal <objective> | /goal [status] | /goal start <objective> | /goal edit <objective> | /goal pause|resume|complete|block|clear
/btw <side question> (alias: /side; asks without changing future session context)
/elevated <on|off|ask|full> (alias: /elev)
/activation <mention|always>
/queue <steer|followup|collect|interrupt> [debounce:<duration>] [cap:<n>] [drop:<summarize|old|new>]
/queue default (or /queue reset) clears the session override

Session lifecycle:

/new (spawn a fresh, isolated session under a new key; does not affect other TUI clients on the old session)
/reset (reset the current session key in place)
/abort (abort the active run)
/stop (stop the active or queued run)
/settings
/exit (or /quit)

Local mode only:

/auth [provider] opens the provider auth/login flow inside the TUI.

Local mode implements the same queue modes inside the embedded runtime. A mid-run prompt follows the session's /queue policy: steer injects when the runtime can accept it, followup waits for a separate turn, collect combines pending prompts, and interrupt stops the current run before starting the new one. Explicit /steer <message> is Gateway-only; use /queue steer plus a normal message in local mode.

OpenClaw:

/openclaw [request] returns from the normal agent TUI to the OpenClaw setup/repair chat, optionally forwarding one request.

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).
Local shell commands receive OPENCLAW_SHELL=tui-local in their environment.
A lone ! is sent as a normal message; leading spaces do not trigger local exec.

OpenClaw setup and repair helper

OpenClaw is the ring-zero setup/repair assistant, exposed as openclaw setup after the configured default model passes a live inference check. If inference is unavailable, an interactive invocation returns to inference onboarding and automation fails with repair guidance. It runs inside the same local TUI shell as openclaw tui --local, backed by an AI agent restricted to OpenClaw's typed, approval-gated operations:

openclaw setup                       # start interactively
openclaw setup -m "status"           # run one request and exit
openclaw setup -m "set default model openai/gpt-5.2" --yes   # apply a config write

Persistent config writes need approval: either confirm interactively or pass --yes.
--json prints the startup overview as JSON instead of starting the chat.
From inside OpenClaw, an open-tui request (for example, asking to talk to a normal agent) exits OpenClaw and opens the regular agent TUI; use /openclaw there to come back.

Use local mode when the current config already validates and you want the embedded agent to inspect it on the same machine, compare it against the docs, and help repair drift without depending on a running Gateway.

If openclaw config validate is already failing, start with openclaw configure or openclaw doctor --fix first; openclaw chat still needs a loadable config to start.

Typical loop:

Start local mode:

openclaw chat

Ask the agent what you want checked, for example:

Compare my gateway auth config with the docs and suggest the smallest fix.

Run local shell commands to gather concrete evidence and verify results:

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

Make targeted edits with openclaw config set or openclaw configure, then execute !openclaw config validate again.
When Doctor proposes an automatic repair or migration, inspect it and then launch !openclaw doctor --fix.

Advice:

Choose openclaw config set or openclaw configure instead of directly modifying openclaw.json.
From the same machine, openclaw docs "<query>" queries the live documentation index.
For structured schema and SecretRef/resolvability errors, openclaw config validate --json comes in handy.

Tool output

Tool invocations appear as cards that include arguments and outcomes.
Press Ctrl+O to switch between collapsed and expanded states.
While tools are executing, live updates flow into the same card.

Terminal colors

Assistant body text uses the terminal's default foreground color in the TUI, so readability holds on both dark and light backgrounds.
If auto-detection misreads a light background, configure OPENCLAW_THEME=light before starting openclaw tui.
To bring back the original dark theme, set OPENCLAW_THEME=dark.

History + streaming

Upon connection, the TUI pulls the most recent history (200 messages by default).
Streaming output updates in place until it finalizes.
Messages posted to the same session from another client show up automatically.
Agent tool events are also monitored by the TUI, producing richer tool cards.

Connection details

The TUI connects using client id openclaw-tui under the broad ui client mode, which is the same mode Control UI and WebChat employ for Gateway policy.
A system message appears on reconnect; gaps in events get logged.

Options

--local: Execute against the local embedded agent runtime
--url <url>: Gateway WebSocket URL, falling back to gateway.remote.url from config or ws://127.0.0.1:<port> on loopback
--token <token>: Gateway token, when one is needed
--password <password>: Gateway password, when one is needed
--tls-fingerprint <sha256>: Expected TLS certificate fingerprint for a pinned wss:// Gateway
--session <key>: Session key, defaulting to main or global for global scope
--deliver: Forward assistant replies to the provider, off by default
--thinking <level>: Override the thinking level for outbound sends
--message <text>: Send a starting message right after connecting
--timeout-ms <ms>: Agent timeout measured in ms, defaulting to agents.defaults.timeoutSeconds
--history-limit <n>: Number of history entries to load, defaulting to 200

Warning

Setting --url prevents the TUI from falling back to config or environment credentials. You must supply --token or --password explicitly, along with --tls-fingerprint when a pinned certificate is in use. Omitting explicit credentials triggers an error. In local mode, avoid passing --url, --token, --password, or --tls-fingerprint.

Troubleshooting

No output appears after sending a message:

Use /status inside the TUI to verify the Gateway is connected and either idle or busy.
Inspect the Gateway logs with openclaw logs --follow.
Make sure the agent can execute by running openclaw status and openclaw models status.
If chat channel messages are expected, verify the TUI launched with --deliver, since this cannot be enabled later without a restart.

Connection troubleshooting

disconnected: verify the Gateway is up and your --url/--token/--password are accurate.
No agents listed in the picker: inspect openclaw agents list and your routing setup.
Empty session picker: you may be in global scope or have no sessions yet.

Control UI, a web interface for managing the system
Config, view, check, and modify openclaw.json
Doctor, step-by-step fixes and migration verification
CLI Reference, complete documentation of every CLI command