vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 11:00:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(tui): document local config repair flow (#69995) (thanks @fuller-stack-dev)

Browse Source 
* docs(tui): document local config repair flow

* docs(tui): clarify local TUI examples

* docs(config): gate local TUI repair flow

* docs(tui): fix local repair docs

---------

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
This commit is contained in:
fuller-stack-dev
2026-04-22 00:12:59 -06:00
committed by GitHub
parent 4fbd314e1f
commit 561f2e52c7
4 changed files with 139 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/web/tui.md
View File

@@ -1,5 +1,5 @@
---
summary: "Terminal UI (TUI): connect to the Gateway from any machine"
summary: "Terminal UI (TUI): connect to the Gateway or run locally in embedded mode"
read_when:
- You want a beginner-friendly walkthrough of the TUI
- You need the complete list of TUI features, commands, and shortcuts
@@ -10,6 +10,8 @@ title: "TUI"
## Quick start
### Gateway mode
1. Start the Gateway.
```bash
@@ -32,6 +34,22 @@ openclaw tui --url ws://<host>:<port> --token <gateway-token>
Use `--password` if your Gateway uses password auth.
### Local mode
Run the TUI without a Gateway:
```bash
openclaw chat
# or
openclaw tui --local
```
Notes:
- `openclaw chat` and `openclaw terminal` are aliases for `openclaw tui --local`.
- `--local` cannot be combined with `--url`, `--token`, or `--password`.
- Local mode uses the embedded agent runtime directly. Most local tools work, but Gateway-only features are unavailable.
## What you see
- Header: connection URL, current agent, current session.
@@ -108,6 +126,10 @@ Session lifecycle:
- `/settings`
- `/exit`
Local mode only:
- `/auth [provider]` opens the provider auth/login flow inside the TUI.
Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
## Local shell commands
@@ -118,6 +140,48 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
- 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.
## Repair configs from the local TUI
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` does not bypass the invalid-
config guard.
Typical loop:
1. Start local mode:
```bash
openclaw chat
```
2. Ask the agent what you want checked, for example:
```text
Compare my gateway auth config with the docs and suggest the smallest fix.
```
3. Use local shell commands for exact evidence and validation:
```text
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
```
4. Apply narrow changes with `openclaw config set` or `openclaw configure`, then rerun `!openclaw config validate`.
5. If Doctor recommends an automatic migration or repair, review it and run `!openclaw doctor --fix`.
Tips:
- Prefer `openclaw config set` or `openclaw configure` over hand-editing `openclaw.json`.
- `openclaw docs "<query>"` searches the live docs index from the same machine.
- `openclaw config validate --json` is useful when you want structured schema and SecretRef/resolvability errors.
## Tool output
- Tool calls show as cards with args + results.
@@ -143,6 +207,7 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
## Options
- `--local`: Run against the local embedded agent runtime
- `--url <url>`: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:<port>`)
- `--token <token>`: Gateway token (if required)
- `--password <password>`: Gateway password (if required)
@@ -155,6 +220,7 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate
Note: when you set `--url`, the TUI does not fall back to config or environment credentials.
Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
In local mode, do not pass `--url`, `--token`, or `--password`.
## Troubleshooting
@@ -174,4 +240,6 @@ No output after sending a message:
## Related
- [Control UI](/web/control-ui) — web-based control interface
- [Config](/cli/config) — inspect, validate, and edit `openclaw.json`
- [Doctor](/cli/doctor) — guided repair and migration checks
- [CLI Reference](/cli) — full CLI command reference