TUI（终端界面）

快速开始

1. 启动 Gateway。

openclaw gateway

2. 打开 TUI。

openclaw tui

3. 输入消息并按 Enter。

连接远程 Gateway：

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

若 Gateway 使用密码认证，使用 --password。

界面说明

• 标题栏：连接 URL、当前代理、当前会话。
• 聊天日志：用户消息、助手回复、系统通知、工具卡片。
• 状态行：连接/运行状态（连接中、运行中、流式传输、空闲、错误）。
• 底部栏：连接状态 + 代理 + 会话 + 模型 + 思考/快速/详细/推理 + token 计数 + 投递。
• 输入框：带自动补全的文本编辑器。

心智模型：代理 + 会话

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

发送 + 投递

• 消息发送到 Gateway；默认不向提供商投递。
• 开启投递：
  • /deliver on
  • 或在设置面板中切换
  • 或启动时使用 openclaw tui --deliver

选择器 + 浮层

• 模型选择器：列出可用模型并设置会话覆盖。
• 代理选择器：选择不同的代理。
• 会话选择器：仅显示当前代理的会话。
• 设置：切换投递、工具输出展开和思考可见性。

键盘快捷键

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

Slash 命令

核心：

• /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 slash 命令（如 /context）会被转发到 Gateway 并显示为系统输出。见 Slash 命令。

本地 Shell 命令

• 以 ! 为前缀的行在 TUI 主机上运行本地 shell 命令。
• TUI 每个会话提示一次允许本地执行；拒绝则该会话 ! 保持禁用。
• 命令在 TUI 工作目录的全新非交互式 shell 中运行（无持久 cd/env）。
• 本地 shell 命令在其环境中接收 OPENCLAW_SHELL=tui-local。
• 单独的 ! 作为普通消息发送；前导空格不触发本地执行。

工具输出

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

终端颜色

• TUI 将助手正文保持在终端默认前景色，使深色和浅色终端均可读。
• 若终端使用浅色背景且自动检测出错，在启动 openclaw tui 前设置 OPENCLAW_THEME=light。
• 要强制使用原始深色调色板，设置 OPENCLAW_THEME=dark。

历史 + 流式传输

• 连接时，TUI 加载最新历史（默认 200 条消息）。
• 流式响应就地更新直到完成。
• TUI 还监听代理工具事件以获取更丰富的工具卡片。

连接详情

• 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 时为 global）
• --deliver：将助手回复投递到提供商（默认关闭）
• --thinking <level>：覆盖发送的思考级别
• --timeout-ms <ms>：代理超时，单位毫秒（默认为 agents.defaults.timeoutSeconds）

注意：设置 --url 时，TUI 不会回退到配置或环境凭据，需显式传递 --token 或 --password。

故障排查

发送消息后无输出：

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

连接故障排查

• disconnected：确保 Gateway 正在运行，且 --url/--token/--password 正确。
• 选择器中无代理：检查 openclaw agents list 和路由配置。
• 会话选择器为空：你可能处于 global 范围或尚无会话。