diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 1d1989f53fc..bec8c0b88e2 100644 --- 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" diff --git a/docs/cli/config.md b/docs/cli/config.md index df2ebe89c3d..8a869c2bae8 100644 --- 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. diff --git a/docs/cli/tui.md b/docs/cli/tui.md index f289cfbe9b2..b6bba271bea 100644 --- 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::...`). +- 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 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). diff --git a/docs/web/tui.md b/docs/web/tui.md index d643c6f10d6..d146cf27792 100644 --- 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://: --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 ""` 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 `: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:`) - `--token `: Gateway token (if required) - `--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