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

* 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>
2026-05-01 06:36:23 +08:00 · 2026-04-22 00:12:59 -06:00
parent 4fbd314e1f
commit 561f2e52c7
4 changed files with 139 additions and 3 deletions
--- a/docs/.i18n/glossary.zh-CN.json
+++ b/docs/.i18n/glossary.zh-CN.json
@@ -195,6 +195,10 @@
    "source": "Doctor",
    "target": "Doctor"
  },
+  {
+    "source": "Config",
+    "target": "配置"
+  },
  {
    "source": "Memory Wiki",
    "target": "Memory Wiki"
--- a/docs/cli/config.md
+++ b/docs/cli/config.md
@@ -379,3 +379,31 @@ gateway.
 openclaw config validate
 openclaw config validate --json
 ```
+
+After `openclaw config validate` is passing, you can use the local TUI to have
+an embedded agent compare the active config against the docs while you validate
+each change from the same terminal:
+
+If validation is already failing, start with `openclaw configure` or
+`openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config
+guard.
+
+```bash
+openclaw chat
+```
+
+Then inside the TUI:
+
+```text
+!openclaw config file
+!openclaw docs gateway auth token secretref
+!openclaw config validate
+!openclaw doctor
+```
+
+Typical repair loop:
+
+- Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
+- Apply targeted edits with `openclaw config set` or `openclaw configure`.
+- Rerun `openclaw config validate` after each change.
+- If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.
--- a/docs/cli/tui.md
+++ b/docs/cli/tui.md
@@ -1,14 +1,17 @@
 ---
-summary: "CLI reference for `openclaw tui` (terminal UI connected to the Gateway)"
+summary: "CLI reference for `openclaw tui` (Gateway-backed or local embedded terminal UI)"
 read_when:
  - You want a terminal UI for the Gateway (remote-friendly)
  - You want to pass url/token/session from scripts
+  - You want to run the TUI in local embedded mode without a Gateway
+  - You want to use openclaw chat or openclaw tui --local
 title: "tui"
 ---

 # `openclaw tui`

-Open the terminal UI connected to the Gateway.
+Open the terminal UI connected to the Gateway, or run it in local embedded
+mode.

 Related:

@@ -16,15 +19,48 @@ Related:

 Notes:

+- `chat` and `terminal` are aliases for `openclaw tui --local`.
+- `--local` cannot be combined with `--url`, `--token`, or `--password`.
 - `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
 - When 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 adds `/auth [provider]` inside the TUI command surface.

 ## Examples

 ```bash
+openclaw chat
+openclaw tui --local
 openclaw tui
 openclaw tui --url ws://127.0.0.1:18789 --token <token>
 openclaw tui --session main --deliver
+openclaw chat --message "Compare my config to the docs and tell me what to fix"
 # when run inside an agent workspace, infers that agent automatically
 openclaw tui --session bugfix
 ```
+
+## Config repair loop
+
+Use local mode when the current config already validates and you want the
+embedded agent to inspect it, compare it against the docs, and help repair it
+from the same terminal:
+
+If `openclaw config validate` is already failing, use `openclaw configure` or
+`openclaw doctor --fix` first. `openclaw chat` does not bypass the invalid-
+config guard.
+
+```bash
+openclaw chat
+```
+
+Then inside the TUI:
+
+```text
+!openclaw config file
+!openclaw docs gateway auth token secretref
+!openclaw config validate
+!openclaw doctor
+```
+
+Apply targeted fixes with `openclaw config set` or `openclaw configure`, then
+rerun `openclaw config validate`. See [TUI](/web/tui) and [Config](/cli/config).
--- a/docs/web/tui.md
+++ b/docs/web/tui.md
@@ -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