TUI（终端界面）

快速上手

1. 启动 Gateway。

openclaw gateway

2. 打开 TUI。

openclaw tui

3. 输入消息，按 Enter 发送。

连接远程 Gateway：

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

如果 Gateway 使用密码认证，用 --password。

界面组成

• 头部：连接 URL、当前 agent、当前会话。
• 聊天日志：用户消息、助手回复、系统通知、工具卡片。
• 状态行：连接/运行状态（connecting、running、streaming、idle、error）。
• 底部：连接状态 + agent + 会话 + 模型 + think/fast/verbose/reasoning + token 计数 + deliver。
• 输入：文本编辑器，带自动补全。

核心概念：agent + 会话

• Agent 是唯一的 slug（如 main、research）。Gateway 暴露列表。
• 会话属于当前 agent。
• 会话键存储为 agent:<agentId>:<sessionKey>。
  • 输入 /session main 时，TUI 展开为 agent:<currentAgent>:main。
  • 输入 /session agent:other:main 时，显式切换到那个 agent 会话。
• 会话范围：
  • per-sender（默认）：每个 agent 有多个会话。
  • global：TUI 始终使用 global 会话（选择器可能为空）。
• 当前 agent + 会话始终在底部显示。

发送与投递

• 消息发送到 Gateway；默认不投递给 provider。
• 开启投递：
  • /deliver on
  • 或设置面板
  • 或启动时加 openclaw tui --deliver

选择器与浮层

• 模型选择器：列出可用模型并设置会话覆盖。
• Agent 选择器：切换不同 agent。
• 会话选择器：仅显示当前 agent 的会话。
• 设置：切换 deliver、工具输出展开和 thinking 可见性。

快捷键

• Enter：发送消息
• Esc：中止活跃运行
• Ctrl+C：清空输入（连按两次退出）
• Ctrl+D：退出
• Ctrl+L：模型选择器
• Ctrl+G：agent 选择器
• Ctrl+P：会话选择器
• Ctrl+O：切换工具输出展开
• Ctrl+T：切换 thinking 可见性（重新加载历史）

斜杠命令

核心：

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

会话控制：

• /think <off|minimal|low|medium|high>
• /fast <status|on|off>
• /verbose <on|full|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /elevated <on|off|ask|full>（别名：/elev）
• /activation <mention|always>
• /deliver <on|off>

会话生命周期：

• /new 或 /reset（重置会话）
• /abort（中止活跃运行）
• /settings
• /exit

其他 Gateway 斜杠命令（如 /context）会被转发到 Gateway 并显示为系统输出。详见 斜杠命令。

本地 Shell 命令

• 在行首加 ! 可运行本地 shell 命令（在 TUI 主机上）。
• TUI 每次会话首次运行时会提示是否允许本地执行；拒绝后该会话中 ! 保持禁用。
• 命令在 TUI 工作目录下的全新、非交互式 shell 中运行（没有持久的 cd/env）。
• 本地 shell 命令环境中包含 OPENCLAW_SHELL=tui-local。
• 单独一个 ! 会作为普通消息发送；行首空格不会触发本地执行。

工具输出

• 工具调用显示为带参数 + 结果的卡片。
• Ctrl+O 在折叠/展开视图间切换。
• 工具运行时，部分更新流式写入同一卡片。

终端颜色

• TUI 将助手正文保持在终端的默认前景色，暗色和亮色终端都能正常阅读。
• 如果你的终端是浅色背景且自动检测不正确，启动 openclaw tui 前设置 OPENCLAW_THEME=light。
• 要强制使用原始暗色调色板，设置 OPENCLAW_THEME=dark。

历史与流式

• 连接时，TUI 加载最近的历史（默认 200 条消息）。
• 流式响应原地更新直到最终确定。
• TUI 也监听 agent 工具事件以提供更丰富的工具卡片。

连接细节

• TUI 以 mode: "tui" 注册到 Gateway。
• 重连时显示系统消息；事件间隙在日志中标出。

启动选项

• --url <url>：Gateway WebSocket URL（默认使用配置或 ws://127.0.0.1:<port>）
• --token <token>：Gateway token（如果需要）
• --password <password>：Gateway 密码（如果需要）
• --session <key>：会话键（默认 main，全局范围时为 global）
• --deliver：将助手回复投递给 provider（默认关闭）
• --thinking <level>：发送时覆盖 thinking 级别
• --timeout-ms <ms>：Agent 超时（毫秒），默认为 agents.defaults.timeoutSeconds

注意：设置 --url 后，TUI 不回退到配置或环境凭据。请显式传递 --token 或 --password。缺少显式凭据会报错。

故障排查

发送消息后没有输出：

• 在 TUI 中运行 /status 确认 Gateway 已连接且处于 idle/busy 状态。
• 检查 Gateway 日志：openclaw logs --follow。
• 确认 agent 可运行：openclaw status 和 openclaw models status。
• 如果期望消息出现在聊天频道中，启用投递（/deliver on 或 --deliver）。
• --history-limit <n>：加载的历史条目数（默认 200）

连接故障排查

• disconnected：确保 Gateway 正在运行，--url/--token/--password 正确。
• 选择器中没有 agent：检查 openclaw agents list 和路由配置。
• 会话选择器为空：可能处于全局范围或还没有会话。