TUI

기준일: 2026-07-26
공식 기준: TUI

TUI 문서는 OpenClaw 공식 문서(web/tui)를 한국어로 정리한 가이드입니다. Terminal UI (TUI): connect to the Gateway or run locally in embedded mode 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Terminal UI (TUI): connect to the Gateway or run locally in embedded mode

한국어 가이드 범위: web/tui 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 빠른 시작
• Gateway mode
• Local mode
• or
• What you see
• Mental model: agents + sessions
• Sending + delivery
• Pickers + overlays
• Keyboard shortcuts
• Slash commands
• Local shell commands
• Tool output
• Terminal colors
• History + streaming
• Connection details
• 옵션
• 트러블슈팅
• Connection troubleshooting
• 관련 문서

상세 내용

빠른 시작

이 섹션의 세부 항목은 공식 문서 빠른 시작를 참고하세요.

Gateway mode

Use --password if your Gateway uses password auth.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw gateway

openclaw tui

openclaw tui --url ws://<host>:<port> --token <gateway-token>

Local mode

Run the TUI without a Gateway:

openclaw chat

### or

주요 항목:

- `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.
- Bare `openclaw` (no subcommand) picks a target automatically: an unconfigured install runs inference onboarding; invalid config opens classic doctor guidance; a reachable configured Gateway opens this TUI shell in gateway mode; otherwise a configured local model opens it in local mode.

### What you see

주요 항목:

- Header: connection URL, current agent, current session.
- Chat log: user messages, assistant replies, system notices, tool cards.
- Status line: connection/run state (connecting, running, streaming, idle, error).
- Footer: agent + session + model + goal state + think/fast/verbose/trace/reasoning + token counts + deliver.
- Input: text editor with autocomplete.

### Mental model: agents + sessions

`Pursuing goal`, `Goal paused (/goal resume)`, `Goal blocked (/goal resume)`, or `Goal achieved`.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- Agents are unique slugs (e.g. `main`, `research`). The Gateway exposes the list.
- Sessions belong to the current agent.
- Session keys are stored as `agent:<agentId>:<sessionKey>`.
- If you type `/session main`, the TUI expands it to `agent:<currentAgent>:main`.
- If you type `/session agent:other:main`, you switch to that agent session explicitly.
- Session scope:
- `per-sender` (default): each agent has many sessions.
- `global`: the TUI always uses the `global` session (the picker may be empty).
- The current agent + session are always visible in the footer.
- If the session has a goal, the footer shows its compact state:
- When started without `--session`, gateway-mode TUI resumes the last selected session for the same gateway, agent, and session scope if that session still exists. Passing `--session`, `/session`, `/new`, or `/reset` remains explicit.

### Sending + delivery

주요 항목:

- Messages always go to the Gateway (or embedded runtime in local mode); delivering the assistant's reply back out to a chat provider is a separate, off-by-default step.
- The TUI is an internal source surface like WebChat, not a generic outbound channel. Harnesses that require `tools.message` for visible replies can satisfy the active TUI turn with a targetless `message.send`; explicit provider delivery still uses normal configured channels and never falls back to `lastChannel`.
- Delivery is fixed for the whole TUI session at launch: start with `openclaw tui --deliver` to turn it on. There is no `/deliver` slash command or Settings toggle to flip it mid-session; restart the TUI to change it.

### Pickers + overlays

주요 항목:

- Model picker: list available models and set the session override.
- Agent picker: choose a different agent.
- Session picker: shows up to 50 sessions for the current agent updated in the last 7 days. Use `/session <key>` to jump to an older known session.
- Settings (`/settings`): toggle tool output expansion and thinking visibility. This panel does not control delivery.

### Keyboard shortcuts

주요 항목:

- Enter: send message
- Esc: abort active run
- Ctrl+C: clear input (press twice to exit)
- Ctrl+D: exit
- Ctrl+L: model picker
- Ctrl+G: agent picker
- Ctrl+P: session picker
- Ctrl+O: toggle tool output expansion
- Ctrl+T: toggle thinking visibility (reloads history)

### Slash commands

Local mode implements the same queue modes inside the embedded runtime. A mid-run prompt follows the session's `/queue` policy: `steer` injects when the runtime can accept it, `followup` waits for a separate turn, `collect` combines pending prompts, and `interrupt` stops the current run before starting the new one. Explicit `/steer ` is Gateway-only; use `/queue steer` plus a normal message in local mode.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- `/help`
- `/status` (Gateway-forwarded; shows session/model summary)
- `/gateway-status` (alias `/gwstatus`; shows Gateway connection status directly)
- `/agent <id>` (or `/agents`)
- `/session <key>` (or `/sessions`)
- `/model <provider/model>` (or `/models`)
- `/think <off|minimal|low|medium|high>` (higher tiers may add levels like `xhigh`/`max` depending on the model)
- `/fast <status|auto|on|off>`
- `/verbose <on|full|off>`
- `/trace <on|off>`
- `/reasoning <on|off|stream>`
- `/usage <off|tokens|full|reset>` (`reset`/`inherit`/`clear`/`default` clears the session override)
- `/goal [status] | /goal start <objective> | /goal edit <objective> | /goal pause|resume|complete|block|clear`
- `/elevated <on|off|ask|full>` (alias: `/elev`)
- `/activation <mention|always>`
- `/queue <steer|followup|collect|interrupt> [debounce:<duration>] [cap:<n>] [drop:<summarize|old|new>]`
- `/queue default` (or `/queue reset`) clears the session override
- `/new` (spawn a fresh, isolated session under a new key; does not affect other TUI clients on the old session)
- `/reset` (reset the current session key in place)
- `/abort` (abort the active run)
- `/settings`
- `/exit` (or `/quit`)
- `/auth [provider]` opens the provider auth/login flow inside the TUI.
- `/openclaw [request]` returns from the normal agent TUI to the OpenClaw setup/repair chat, optionally forwarding one request.

### Local shell commands

주요 항목:

- Prefix a line with `!` to run a local shell command on the TUI host.
- The TUI prompts once per session to allow local execution; declining keeps `!` disabled for the session.
- Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent `cd`/env).
- 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.

### OpenClaw setup and repair helper

OpenClaw is the ring-zero setup/repair assistant, exposed as `openclaw setup` after the configured default model passes a live inference check. If inference is unavailable, an interactive invocation returns to inference onboarding and automation fails with repair guidance. It runs inside the same local TUI shell as `openclaw tui --local`, backed by an AI agent restricted to OpenClaw's typed, approval-gated operations:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- Persistent config writes need approval: either confirm interactively or pass `--yes`.
- `--json` prints the startup overview as JSON instead of starting the chat.
- From inside OpenClaw, an `open-tui` request (예를 들어, asking to talk to a normal agent) exits OpenClaw and opens the regular agent TUI; use `/openclaw` there to come back.
- 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.

```bash
openclaw setup                       # start interactively
openclaw setup -m "status"           # run one request and exit
openclaw setup -m "set default model openai/gpt-5.2" --yes   # apply a config write

openclaw chat

Compare my gateway auth config with the docs and suggest the smallest fix.

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

Tool output

주요 항목:

• Tool calls show as cards with args + results.
• Ctrl+O toggles between collapsed/expanded views.
• While tools run, partial updates stream into the same card.

Terminal colors

주요 항목:

• The TUI keeps assistant body text in your terminal's default foreground so dark and light terminals both stay readable.
• If your terminal uses a light background and auto-detection is wrong, set OPENCLAW_THEME=light before launching openclaw tui.
• To force the original dark palette instead, set OPENCLAW_THEME=dark.

History + streaming

주요 항목:

• On connect, the TUI loads the latest history (default 200 messages).
• Streaming responses update in place until finalized.
• The TUI also listens to agent tool events for richer tool cards.

Connection details

주요 항목:

• The TUI connects with client id openclaw-tui under the coarse ui client mode (the same mode Control UI and WebChat use for Gateway policy).
• Reconnects show a system message; event gaps are surfaced in the log.

옵션

When you set --url, the TUI does not fall back to config or environment credentials. Pass --token or --password explicitly, plus --tls-fingerprint when the target uses a pinned certificate. Missing explicit credentials is an error. In local mode, do not pass --url, --token, --password, or --tls-fingerprint.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• --local: Run against the local embedded agent runtime
• --url <url>: Gateway WebSocket URL (defaults to gateway.remote.url from config, or ws://127.0.0.1:<port> on loopback)
• --token <token>: Gateway token (if required)
• --password <password>: Gateway password (if required)
• --tls-fingerprint <sha256>: Expected TLS certificate fingerprint for a pinned wss:// Gateway
• --session <key>: Session key (default: main, or global when scope is global)
• --deliver: Deliver assistant replies to the provider (default off)
• --thinking <level>: Override thinking level for sends
• --message <text>: Send an initial message after connecting
• --timeout-ms <ms>: Agent timeout in ms (defaults to agents.defaults.timeoutSeconds)
• --history-limit <n>: History entries to load (default 200)

트러블슈팅

주요 항목:

• Run /status in the TUI to confirm the Gateway is connected and idle/busy.
• Check the Gateway logs: openclaw logs --follow.
• Confirm the agent can run: openclaw status and openclaw models status.
• If you expect messages in a chat channel, confirm the TUI was started with --deliver (this cannot be turned on later without restarting).

Connection troubleshooting

주요 항목:

• disconnected: ensure the Gateway is running and your --url/--token/--password are correct.
• No agents in picker: check openclaw agents list and your routing config.
• Empty session picker: you might be in global scope or have no sessions yet.

관련 문서

주요 항목:

• Control UI — web-based control interface
• Config — inspect, validate, and edit openclaw.json
• Doctor — guided repair and migration checks
• CLI Reference — full CLI command reference

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/web/tui
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw gateway

openclaw tui

openclaw tui --url ws://<host>:<port> --token <gateway-token>

openclaw chat
# or
openclaw tui --local

openclaw setup                       # start interactively
openclaw setup -m "status"           # run one request and exit
openclaw setup -m "set default model openai/gpt-5.2" --yes   # apply a config write

openclaw chat

관련 링크

• 공식 원문: web/tui
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.