OpenClaw TUI Guide: Testing Your Agent From the Terminal Before It Reaches a Real Channel

openclaw tui opens a chat with your agent in the terminal, and by default nothing it says leaves that terminal. That one default makes it the safest place to try a new skill before your agent answers anyone on Telegram.

The pages that rank for this are the official CLI reference (short, mostly a flag table), the longer TUI page in the web docs, and a Stanza course lesson of about 850 words. All three cover the same ground: start the Gateway, run openclaw tui, pick a session, learn a few shortcuts. They treat the TUI as a chat window. I use it as a test bench, and the flags that matter for that job (--session, --deliver, --local) get a table row each in the reference and a sentence or two in the web docs. That is what this guide is about.

Three ways in

openclaw tui                      # connect to the running Gateway
openclaw chat                     # embedded runtime, no Gateway (same as tui --local)
openclaw tui --url wss://gw.example:18789 --token <token>

openclaw terminal is another alias. In my copy of the CLI (2026.10.5) both chat and terminal print the same help page as tui, so the difference is only whether --local is implied. Use the Gateway form for real testing, because that is the process your channels talk to. Use chat when the Gateway won't start and you need a terminal that can still reach the config, which is a different job entirely and gets its own section below.

Give every experiment its own session

openclaw tui --session prompt-test-oct27

The default session key is main. That is the session your agent has been building context in for weeks, and if you paste a half-finished system prompt idea into it, the agent carries that into tomorrow's real conversations. Session keys expand to agent:<agentId>:<sessionKey>, so a throwaway key like the one above stays isolated under the same agent. Inside the TUI, /new starts a fresh isolated session and /session agent:research:main jumps to another agent explicitly.

The session picker (Ctrl+P) shows at most 50 sessions from the current agent, and only ones updated in the last 7 days. Your scratch session from three weeks ago is still there. Type /session <key> to reach it, or list everything with the sessions CLI. When a test session has done its job, the session reset guide covers /reset versus starting over.

Delivery is off, and you can't turn it on mid-session

Messages you type always go to the Gateway. Sending the assistant's reply back out to a chat provider is a separate step, and it is off unless you launch with --deliver. There is no slash command to flip it. You quit and relaunch.

I like this more than the docs seem to. It means the test bench and the live run are two different commands you type on purpose, and I keep them that way:

# rehearsal: nothing leaves the terminal
openclaw tui --session release-notes-dryrun

# the real thing, once the rehearsal looked right
openclaw tui --session release-notes --deliver

The flip side catches people. If you ask the agent to post something and nothing shows up in Slack, check the launch command before you debug the channel. The docs' own troubleshooting list ends with exactly that check.

Make the agent show its work

The point of a rehearsal is seeing what the agent did, along with what it said. These are the commands I actually type in a test session:

/verbose full        # more detail per turn (on | full | off)
/usage cost          # token and cost readout (off | tokens | full | cost | reset)
/trace on            # execution tracing
/think high          # off | minimal | low | medium | high | default
/model <provider/model>

Ctrl+O expands tool cards so you see the arguments the agent passed instead of a collapsed "ran exec" line. Ctrl+T shows or hides thinking. Watch the /usage number on a skill you plan to run from cron every hour. A turn that costs a few cents here costs the same few cents 24 times a day there, and the cost optimization guide has the levers if it surprises you.

One warning about secondhand sources. The Stanza lesson describes thinking levels as none, brief, and detailed, and lists shortcuts like Ctrl+N. Neither matches the current docs. When a shortcut does nothing, trust /help over any tutorial, this one included.

/btw (alias /side) asks a side question without adding it to the session's future context. Use it to ask "why did you call that tool?" without that question shaping the next turn you are trying to test.

The ! prefix runs on your machine, not the agent's

Start a line with ! and the TUI runs it as a shell command on the host where the TUI is running. It asks once per session for permission, runs a fresh non-interactive shell in the TUI's working directory, and sets OPENCLAW_SHELL=tui-local. This is not the agent's exec tool, and your exec approvals don't gate it. If you are connected to a remote Gateway, !ls lists your laptop.

A lone ! is sent as an ordinary message.

Remote Gateways and the credential trap

Set --url and the TUI stops reading credentials from config and environment variables altogether. Pass --token or --password on the command line, plus --tls-fingerprint if the Gateway pins its certificate. Leave them off and you get an error, which is better than silently authenticating with the wrong profile's token. If you omit --url, the TUI uses gateway.remote.url from config and the normal credentials. For a Gateway on another box, the Tailscale guide is the cleaner network path.

You can also pass a Control UI session URL (or a short ref like movies-a1166b81) as the target. Session URLs have to be credential-free, and an ambiguous short ref prints candidates instead of attaching. Going the other direction, openclaw dashboard --no-open prints the Control UI URL without launching a browser, and openclaw resume --handoff takes a handoff payload copied from the Control UI back into the terminal.

openclaw chat when the Gateway is down

Local mode runs the embedded agent runtime and needs exclusive ownership of the state directory. If the Gateway, or another embedded writer, already owns it, openclaw chat refuses to start. That surprises people who try it as a quick second window next to a running Gateway. It is meant for the opposite situation: the Gateway won't come up, and you need to look at config from the same terminal. --local can't be combined with --url, --token, or --password, and Gateway-only features are missing. /auth works here and nowhere else.

Before you reach for it, run openclaw doctor. Doctor often names the reason the Gateway is down in a single line, which beats poking at config by hand.

When the TUI shows nothing

Run /status first. If the header says disconnected, the problem is the connection, so check that the Gateway is running and that your --url, --token, or --password are right. If it's connected and still silent, tail the Gateway with openclaw logs --follow in another pane (the logging guide explains what you're reading) and confirm the agent has a working model with openclaw models status. An empty agent picker usually means routing, so start with openclaw agents list. Light terminal theme making the output hard to read? Set OPENCLAW_THEME=light.

Final verdict

Open a named scratch session, leave --deliver off, and turn on /verbose full and /usage cost until the agent does the thing twice in a row without surprises. Then relaunch with --deliver and a real session key. Delivery already defaults to off. The session doesn't, since a bare openclaw tui drops you into main, and that is the one default I wish OpenClaw had picked differently.