TUI (Terminal UI,终端界面)

快速开始

  1. 启动 Gateway。
openclaw gateway
  1. 打开 TUI。
openclaw tui
  1. 输入消息并按 Enter。

远程 Gateway:

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

如果你的 Gateway 使用密码认证,使用 --password。

你看到的内容

  • Header (头部): 连接 URL、当前 agent、当前 session。
  • Chat log (聊天日志): 用户消息、助手回复、系统通知、tool 卡片。
  • Status line (状态行): 连接/运行状态(connecting, running, streaming, idle, error)。
  • Footer (页脚): 连接状态 + agent + session + model + think/verbose/reasoning + token 计数 + deliver。
  • Input (输入): 带自动完成的文本编辑器。

心智模型: agents + sessions

  • Agents 是唯一的 slugs (例如 main, research)。Gateway 暴露列表。
  • Sessions 属于当前 agent。
  • Session keys 存储为 agent:<agentId>:<sessionKey>。
    • 如果你输入 /session main,TUI 将其扩展为 agent:<currentAgent>:main。
    • 如果你输入 /session agent:other:main,你明确切换到该 agent session。
  • Session scope (范围):
    • per-sender(默认): 每个 agent 有多个 sessions。
    • global: TUI 始终使用 global session (选择器可能为空)。
  • 当前 agent + session 始终在 footer 中可见。

Sending + delivery (发送 + 交付)

  • 消息发送到 Gateway; 默认情况下 providers 的交付是关闭的。
  • 打开交付:
    • /deliver on
    • 或 Settings 面板
    • 或使用 openclaw tui --deliver 启动

Pickers (选择器) + overlays (覆盖层)

  • Model picker (模型选择器): 列出可用模型并设置 session 覆盖。
  • Agent picker: 选择不同的 agent。
  • Session picker: 仅显示当前 agent 的 sessions。
  • Settings: 切换 deliver、tool 输出展开和 thinking 可见性。

键盘快捷键

  • Enter: 发送消息
  • Esc: 中止活动运行
  • Ctrl+C: 清除输入(按两次退出)
  • Ctrl+D: 退出
  • Ctrl+L: 模型选择器
  • Ctrl+G: agent 选择器
  • Ctrl+P: session 选择器
  • Ctrl+O: 切换 tool 输出展开
  • Ctrl+T: 切换 thinking 可见性(重新加载历史)

Slash 命令

核心:

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

Session 控制:

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

Session 生命周期:

  • /new 或 /reset (重置 session)
  • /abort (中止活动运行)
  • /settings
  • /exit

其他 Gateway slash 命令(例如 /context)被转发到 Gateway 并显示为系统输出。查看 Slash commands。

本地 shell 命令

  • 在行前加 ! 以在 TUI 主机上运行本地 shell 命令。
  • TUI 每个 session 提示一次以允许本地执行;拒绝会使该 session 的 ! 禁用。
  • 命令在 TUI 工作目录的新的非交互式 shell 中运行(没有持久的 cd/env)。
  • 单独的 ! 作为普通消息发送;前导空格不会触发本地 exec。

Tool 输出

  • Tool 调用显示为带有 args + results 的卡片。
  • Ctrl+O 在折叠/展开视图之间切换。
  • 当 tools 运行时,部分更新流入同一张卡片。

History (历史) + streaming (流式传输)

  • 连接时,TUI 加载最新历史(默认 200 条消息)。
  • Streaming 响应在最终确定之前就地更新。
  • TUI 还监听 agent tool 事件以获得更丰富的 tool 卡片。

连接详细信息

  • TUI 向 Gateway 注册为 mode: "tui"。
  • 重新连接显示系统消息;事件间隙在日志中显示。

选项

  • --url <url>: Gateway WebSocket URL (默认为 config 或 ws://127.0.0.1:<port>)
  • --token <token>: Gateway token (如果需要)
  • --password <password>: Gateway password (如果需要)
  • --session <key>: Session key (默认: main,或 scope 为 global 时为 global)
  • --deliver: 将助手回复交付给 provider (默认关闭)
  • --thinking <level>: 覆盖发送的 thinking 级别
  • --timeout-ms <ms>: Agent timeout,单位 ms (默认为 agents.defaults.timeoutSeconds)

故障排除

发送消息后无输出:

  • 在 TUI 中运行 /status 以确认 Gateway 已连接且空闲/忙碌。
  • 检查 Gateway 日志: openclaw logs --follow。
  • 确认 agent 可以运行: openclaw status 和 openclaw models status。
  • 如果你期望聊天渠道中的消息,启用交付(/deliver on 或 --deliver)。
  • --history-limit <n>: 要加载的历史条目(默认 200)

故障排除

  • disconnected (已断开连接): 确保 Gateway 正在运行,且你的 --url/--token/--password 正确。
  • Agents picker 中无 agents: 检查 openclaw agents list 和你的路由配置。
  • Session picker 为空: 你可能处于 global scope,或者还没有 sessions。
← 返回文档首页