@@ -1,5 +1,5 @@
11---
2-summary: "Terminal UI (TUI): connect to the Gateway from any machine"
2+summary: "Terminal UI (TUI): connect to the Gateway or run locally in embedded mode"
33read_when:
44 - You want a beginner-friendly walkthrough of the TUI
55 - You need the complete list of TUI features, commands, and shortcuts
@@ -10,6 +10,8 @@ title: "TUI"
10101111## Quick start
121213+### Gateway mode
14+13151. Start the Gateway.
14161517```bash
@@ -32,6 +34,22 @@ openclaw tui --url ws://<host>:<port> --token <gateway-token>
32343335Use `--password` if your Gateway uses password auth.
343637+### Local mode
38+39+Run the TUI without a Gateway:
40+41+```bash
42+openclaw chat
43+# or
44+openclaw tui --local
45+```
46+47+Notes:
48+49+- `openclaw chat` and `openclaw terminal` are aliases for `openclaw tui --local`.
50+- `--local` cannot be combined with `--url`, `--token`, or `--password`.
51+- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
52+3553## What you see
36543755- Header: connection URL, current agent, current session.
@@ -108,6 +126,10 @@ Session lifecycle:
108126- `/settings`
109127- `/exit`
110128129+Local mode only:
130+131+- `/auth [provider]` opens the provider auth/login flow inside the TUI.
132+111133Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
112134113135## Local shell commands
@@ -118,6 +140,48 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
118140- Local shell commands receive `OPENCLAW_SHELL=tui-local` in their environment.
119141- A lone `!` is sent as a normal message; leading spaces do not trigger local exec.
120142143+## Repair configs from the local TUI
144+145+Use local mode when the current config already validates and you want the
146+embedded agent to inspect it on the same machine, compare it against the docs,
147+and help repair drift without depending on a running Gateway.
148+149+If `openclaw config validate` is already failing, start with `openclaw configure`
150+or `openclaw doctor --fix` first. `openclaw chat` does not bypass the invalid-
151+config guard.
152+153+Typical loop:
154+155+1. Start local mode:
156+157+```bash
158+openclaw chat
159+```
160+161+2. Ask the agent what you want checked, for example:
162+163+```text
164+Compare my gateway auth config with the docs and suggest the smallest fix.
165+```
166+167+3. Use local shell commands for exact evidence and validation:
168+169+```text
170+!openclaw config file
171+!openclaw docs gateway auth token secretref
172+!openclaw config validate
173+!openclaw doctor
174+```
175+176+4. Apply narrow changes with `openclaw config set` or `openclaw configure`, then rerun `!openclaw config validate`.
177+5. If Doctor recommends an automatic migration or repair, review it and run `!openclaw doctor --fix`.
178+179+Tips:
180+181+- Prefer `openclaw config set` or `openclaw configure` over hand-editing `openclaw.json`.
182+- `openclaw docs "<query>"` searches the live docs index from the same machine.
183+- `openclaw config validate --json` is useful when you want structured schema and SecretRef/resolvability errors.
184+121185## Tool output
122186123187- Tool calls show as cards with args + results.
@@ -143,6 +207,7 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
143207144208## Options
145209210+- `--local`: Run against the local embedded agent runtime
146211- `--url <url>`: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:<port>`)
147212- `--token <token>`: Gateway token (if required)
148213- `--password <password>`: Gateway password (if required)
@@ -155,6 +220,7 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
155220156221Note: when you set `--url`, the TUI does not fall back to config or environment credentials.
157222Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
223+In local mode, do not pass `--url`, `--token`, or `--password`.
158224159225## Troubleshooting
160226@@ -174,4 +240,6 @@ No output after sending a message:
174240## Related
175241176242- [Control UI](/web/control-ui) — web-based control interface
243+- [Config](/cli/config) — inspect, validate, and edit `openclaw.json`
244+- [Doctor](/cli/doctor) — guided repair and migration checks
177245- [CLI Reference](/cli) — full CLI command reference
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。