TUI (Terminal UI)

Bắt đầu nhanh

  1. Khởi động Gateway.
openclaw gateway
  1. Mở TUI.
openclaw tui
  1. Gõ tin nhắn và ấn Enter.

Kết nối Gateway từ xa:

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

Dùng --password nếu Gateway của các bạn dùng xác thực bằng mật khẩu.

Giao diện hiển thị

  • Header: URL kết nối, agent hiện tại, session hiện tại.
  • Chat log: tin nhắn người dùng, phản hồi assistant, thông báo hệ thống, tool cards.
  • Status line: trạng thái kết nối/chạy (connecting, running, streaming, idle, error).
  • Footer: trạng thái kết nối + agent + session + model + think/verbose/reasoning + số lượng token + deliver.
  • Input: trình soạn thảo văn bản với autocomplete.

Mô hình hoạt động: agents + sessions

  • Agents là các slug duy nhất (ví dụ main, research). Gateway cung cấp danh sách này.
  • Sessions thuộc về agent hiện tại.
  • Session keys được lưu dưới dạng agent:<agentId>:<sessionKey>.
    • Nếu các bạn gõ /session main, TUI sẽ mở rộng thành agent:<currentAgent>:main.
    • Nếu các bạn gõ /session agent:other:main, các bạn sẽ chuyển sang agent session đó một cách rõ ràng.
  • Session scope:
    • per-sender (mặc định): mỗi agent có nhiều sessions.
    • global: TUI luôn dùng session global (picker có thể trống).
  • Agent + session hiện tại luôn hiển thị ở footer.

Gửi tin nhắn + delivery

  • Tin nhắn được gửi tới Gateway; delivery tới providers mặc định là tắt.
  • Bật delivery:
    • /deliver on
    • hoặc qua panel Settings
    • hoặc khởi động với openclaw tui --deliver

Pickers + overlays

  • Model picker: liệt kê các model có sẵn và đặt session override.
  • Agent picker: chọn agent khác.
  • Session picker: chỉ hiển thị sessions của agent hiện tại.
  • Settings: bật/tắt deliver, mở rộng tool output, và hiển thị thinking.

Phím tắt

  • Enter: gửi tin nhắn
  • Esc: hủy run đang chạy
  • Ctrl+C: xóa input (ấn 2 lần để thoát)
  • Ctrl+D: thoát
  • Ctrl+L: model picker
  • Ctrl+G: agent picker
  • Ctrl+P: session picker
  • Ctrl+O: bật/tắt mở rộng tool output
  • Ctrl+T: bật/tắt hiển thị thinking (tải lại lịch sử)

Slash commands

Core:

  • /help
  • /status
  • /agent <id> (hoặc /agents)
  • /session <key> (hoặc /sessions)
  • /model <provider/model> (hoặc /models)

Session controls:

  • /think <off|minimal|low|medium|high>
  • /verbose <on|full|off>
  • /reasoning <on|off|stream>
  • /usage <off|tokens|full>
  • /elevated <on|off|ask|full> (alias: /elev)
  • /activation <mention|always>
  • /deliver <on|off>

Session lifecycle:

  • /new hoặc /reset (reset session)
  • /abort (hủy run đang chạy)
  • /settings
  • /exit

Các Gateway slash commands khác (ví dụ /context) được chuyển tiếp tới Gateway và hiển thị dưới dạng system output. Xem Slash commands.

Lệnh shell local

  • Thêm ! ở đầu dòng để chạy lệnh shell local trên máy chủ TUI.
  • TUI sẽ hỏi một lần mỗi session để cho phép thực thi local; từ chối sẽ giữ ! bị vô hiệu hóa cho session đó.
  • Lệnh chạy trong shell mới, không tương tác trong thư mục làm việc của TUI (không có cd/env persistent).
  • Một ! đơn lẻ sẽ được gửi như tin nhắn bình thường; khoảng trắng ở đầu không kích hoạt local exec.

Tool output

  • Tool calls hiển thị dưới dạng cards với args + kết quả.
  • Ctrl+O chuyển đổi giữa chế độ thu gọn/mở rộng.
  • Trong khi tools chạy, các cập nhật từng phần sẽ stream vào cùng một card.

Lịch sử + streaming

  • Khi kết nối, TUI tải lịch sử mới nhất (mặc định 200 tin nhắn).
  • Streaming responses cập nhật tại chỗ cho đến khi hoàn tất.
  • TUI cũng lắng nghe agent tool events để có tool cards phong phú hơn.

Chi tiết kết nối

  • TUI đăng ký với Gateway dưới dạng mode: "tui".
  • Reconnects hiển thị system message; event gaps được hiển thị trong log.

Tùy chọn

  • --url <url>: Gateway WebSocket URL (mặc định từ config hoặc ws://127.0.0.1:<port>)
  • --token <token>: Gateway token (nếu cần)
  • --password <password>: Gateway password (nếu cần)
  • --session <key>: Session key (mặc định: main, hoặc global khi scope là global)
  • --deliver: Deliver assistant replies tới provider (mặc định tắt)
  • --thinking <level>: Override thinking level khi gửi
  • --timeout-ms <ms>: Agent timeout tính bằng ms (mặc định từ agents.defaults.timeoutSeconds)
  • --history-limit <n>: Số lượng lịch sử entries cần tải (mặc định 200)

Troubleshooting

Không có output sau khi gửi tin nhắn:

  • Chạy /status trong TUI để xác nhận Gateway đã kết nối và đang idle/busy.
  • Kiểm tra Gateway logs: openclaw logs --follow.
  • Xác nhận agent có thể chạy: openclaw status và openclaw models status.
  • Nếu các bạn mong đợi tin nhắn trong chat channel, hãy bật delivery (/deliver on hoặc --deliver).

Các vấn đề khác:

  • disconnected: đảm bảo Gateway đang chạy và --url/--token/--password của các bạn đúng.
  • Không có agents trong picker: kiểm tra openclaw agents list và routing config của các bạn.
  • Session picker trống: các bạn có thể đang ở global scope hoặc chưa có sessions nào.