TUI

​

快速开始

​

网关模式

1. 启动网关。

openclaw gateway

2. 打开 TUI。

openclaw tui

3. 输入消息并按 Enter。

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

​

本地模式

openclaw chat
# 或
openclaw tui --local

• openclaw chat 和 openclaw terminal 是 openclaw tui --local 的别名。
• --local 不能与 --url、--token 或 --password 组合使用。
• 本地模式直接使用内置的代理运行时。大多数本地工具可用，但网关专属功能不可用。
• 直接运行 openclaw（不带子命令）会自动选择目标：未配置的安装会运行推理引导；无效配置会打开经典的诊断指引；可访问且已配置的网关会以网关模式打开此 TUI shell；否则，已配置的本地模型会以本地模式打开。

​

你将看到什么

• 页眉：连接 URL、当前代理、当前会话。
• 聊天记录：用户消息、助手回复、系统通知、工具卡片。
• 状态行：连接/运行状态（连接中、运行中、流式传输、空闲、错误）。
• 页脚：代理 + 会话 + 模型 + 目标状态 + 思考/快速/详细/追踪/推理 + 令牌计数 + 交付。
• 输入：带自动补全的文本编辑器。

​

心智模型：代理 + 会话

• 代理是唯一的 slug（例如 main、research）。网关会暴露这个列表。
• 会话属于当前代理。
• 会话键会存储为 agent:<agentId>:<sessionKey>。
  • 如果你输入 /session main，TUI 会将其展开为 agent:<currentAgent>:main。
  • 如果你输入 /session agent:other:main，你会显式切换到那个代理会话。
• 会话作用域：
  • per-sender（默认）：每个代理都有多个会话。
  • global：TUI 总是使用 global 会话（选择器可能为空）。
• 当前代理 + 会话会始终显示在页脚中。
• 如果会话有一个目标，页脚会显示其紧凑状态： 正在追求目标、目标已暂停（/goal resume）、目标受阻（/goal resume） 或 目标已达成。
• 在不带 --session 启动时，网关模式 TUI 会恢复同一网关、代理和会话作用域下上一次选中的会话，前提是该会话仍然存在。传入 --session、/session、/new 或 /reset 仍然是显式指定。

​

发送 + 投递

• 消息始终发送到网关（或本地模式下的嵌入式运行时）；将助手的回复发送回聊天服务提供商是一个独立的、默认关闭的步骤。
• TUI 是一种内部源接口，类似于 WebChat，而不是通用的出站渠道。对于需要使用 tools.message 才能显示回复的测试框架，可以通过使用不指定目标的 message.send 来满足当前的 TUI 轮次；显式的提供商投递仍会使用通常配置的渠道，并且绝不会回退到 lastChannel。
• 投递设置在整个 TUI 会话启动时即确定：使用 openclaw tui --deliver 启动以启用投递。没有可以在会话中途切换的 /deliver 斜杠命令或设置开关；如需更改，必须重启 TUI。

​

选择器 + 覆盖层

• 模型选择器：列出可用模型并设置会话覆盖。
• 代理选择器：选择不同的代理。
• 会话选择器：显示当前代理在过去 7 天内更新的最多 50 个会话。使用 /session <key> 跳转到较早的已知会话。
• 设置（/settings）：切换工具输出展开和思考可见性。此面板不控制传递。

​

键盘快捷键

• Enter: 发送消息
• Shift+Enter 或 Ctrl+J: 插入换行而不发送
• Esc: 中止当前运行
• Ctrl+C: 清空输入（按两次退出）
• Ctrl+D: 退出
• Ctrl+L: 模型选择器
• Ctrl+G: 智能体选择器
• Ctrl+P: 会话选择器
• Ctrl+O: 切换工具输出展开
• Ctrl+T: 切换思考可见性（重新加载历史记录）。

​

斜杠命令

• /help
• /status（由 Gateway 转发；显示会话/模型摘要）
• /gateway-status（别名 /gwstatus；直接显示 Gateway 连接状态）
• /agent <id>（或 /agents）
• /session <key>（或 /sessions）
• /model <provider/model>（或 /models）

• /think <off|minimal|low|medium|high>（更高层级可能会根据模型增加类似 xhigh/max 的级别）
• /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 清除会话覆盖设置）
• /goal <objective> | /goal [status] | /goal start <objective> | /goal edit <objective> | /goal pause|resume|complete|block|clear
• /btw <side question>（别名：/side；提问时不会改变未来的会话上下文）
• /elevated <on|off|ask|full>（别名：/elev）
• /activation <mention|always>
• /queue <steer|followup|collect|interrupt> [debounce:<duration>] [cap:<n>] [drop:<summarize|old|new>]
• /queue default（或 /queue reset）清除会话覆盖设置

• /new（在新键下生成一个全新、隔离的会话；不会影响旧会话上的其他 TUI 客户端）
• /reset（就地重置当前会话键）
• /abort（中止当前运行）
• /stop（停止当前运行或排队中的运行）
• /settings
• /exit（或 /quit）

• /auth [provider] 会在 TUI 内打开 provider 的认证/登录流程。

• /openclaw [request] 会从正常的 agent TUI 返回到 OpenClaw 设置/修复聊天，并可选择性地转发一条请求。

​

本地 shell 命令

• 在行首添加 !，即可在 TUI 主机上运行本地 shell 命令。
• TUI 会在每个会话中提示一次是否允许本地执行；如果拒绝，则该会话中 ! 将保持禁用状态。
• 命令会在 TUI 工作目录中的一个全新的、非交互式 shell 中运行（不会保留 cd/环境变量）。
• 本地 shell 命令在其环境中会收到 OPENCLAW_SHELL=tui-local。
• 单独的 ! 会作为普通消息发送；前导空格不会触发本地执行。

​

OpenClaw 设置和修复助手

openclaw setup                       # 交互式启动
openclaw setup -m "status"           # 运行一次请求并退出
openclaw setup -m "set default model openai/gpt-5.2" --yes   # 应用一次配置写入

• 持久化配置写入需要审批：可以交互式确认，或者传入 --yes。
• --json 会以 JSON 格式打印启动概览，而不是启动聊天。
• 在 OpenClaw 内部，open-tui 请求（例如，要求切换到普通 agent）会退出 OpenClaw 并打开常规的 agent TUI；在其中使用 /openclaw 可以返回。

1. 启动本地模式：

openclaw chat

2. 让 agent 检查你想要验证的内容，例如：

将我的 gateway 认证配置与文档进行比较，并建议最小的修复。

3. 使用本地 shell 命令获取准确证据并进行验证：

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

4. 使用 openclaw config set 或 openclaw configure 应用小范围更改，然后重新运行 !openclaw config validate。
5. 如果 Doctor 建议自动迁移或修复，请先审查，再运行 !openclaw doctor --fix。

• 相比手动编辑 openclaw.json，更推荐使用 openclaw config set 或 openclaw configure。
• openclaw docs "<query>" 会从同一台机器上搜索实时文档索引。
• 当你需要结构化的 schema 以及 SecretRef/可解析性错误时，openclaw config validate --json 很有用。

​

工具输出

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

​

终端颜色

• TUI 会将助手正文保持为终端的默认前景色，因此深色和浅色终端都能保持可读。
• 如果你的终端使用浅色背景且自动检测不正确，请在启动 openclaw tui 前设置 OPENCLAW_THEME=light。
• 若要强制使用原始深色调色板，则设置 OPENCLAW_THEME=dark。

​

历史记录 + 流式传输

• 连接时，TUI 会加载最新的历史记录（默认 200 条消息）。
• 流式响应会就地更新，直到完成。
• 从另一个客户端发送到同一会话的消息会自动出现。
• TUI 还会监听 agent 工具事件，以显示更丰富的工具卡片。

​

连接详情

• TUI 使用客户端 ID openclaw-tui 连接，并采用粗粒度的 ui 客户端模式（Control UI 和 WebChat 在 Gateway 策略中也使用相同模式）。
• 重新连接时会显示一条系统消息；事件间隙会在日志中显现。

​

选项

• --local: 连接到本地嵌入式代理运行时
• --url <url>: 网关 WebSocket URL（默认使用配置中的 gateway.remote.url，或者在回环地址上使用 ws://127.0.0.1:<port>）
• --token <token>: 网关令牌（如需要）
• --password <password>: 网关密码（如需要）
• --tls-fingerprint <sha256>: 预期的 TLS 证书指纹，用于固定的 wss:// 网关
• --session <key>: 会话键（默认：main，或在作用域为全局时为 global）
• --deliver: 将助手回复发送给提供方（默认关闭）
• --thinking <level>: 覆盖发送时的思考级别
• --message <text>: 连接后发送一条初始消息
• --timeout-ms <ms>: 代理超时，单位为毫秒（默认值为 agents.defaults.timeoutSeconds）
• --history-limit <n>: 要加载的历史记录条目数（默认 200）

​

故障排查

• 在 TUI 中运行 /status，确认 Gateway 已连接且处于空闲/忙碌状态。
• 检查 Gateway 日志：openclaw logs --follow。
• 确认代理可以运行：openclaw status 和 openclaw models status。
• 如果你期望在聊天频道中收到消息，请确认 TUI 是使用 --deliver 启动的（此选项无法在启动后再开启，需重启后才能生效）。

​

连接故障排查

• disconnected：确保 Gateway 正在运行，并且你的 --url/--token/--password 正确。
• 选择器中没有 agent：检查 openclaw agents list 和你的路由配置。
• 会话选择器为空：你可能处于 global 作用域，或者还没有任何会话。

​

相关内容

• 控制 UI — 基于 Web 的控制界面
• 配置 — 检查、验证并编辑 openclaw.json
• Doctor — 引导式修复和迁移检查
• CLI 参考 — 完整的 CLI 命令参考