跳转到内容
OpenClaw Docs

TUI

快速开始

Section titled “快速开始”

Gateway(网关) 模式

Section titled “Gateway(网关) 模式”
  1. 启动 Gateway(网关) 网关。
Terminal window
openclaw gateway
  1. 打开 TUI。
Terminal window
openclaw tui
  1. 输入消息并按 Enter 键。

远程 Gateway(网关) 网关：

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

如果您的 Gateway(网关) 使用密码认证，请使用 --password。

本地模式

Section titled “本地模式”

在没有 Gateway(网关) 的情况下运行 TUI：

Terminal window
openclaw chat
# or
openclaw tui --local

注意事项：

  • openclaw chat 和 openclaw terminal 是 openclaw tui --local 的别名。
  • --local 不能与 --url、--token 或 --password 结合使用。
  • 本地模式直接使用嵌入式代理运行时。大多数本地工具都可以工作，但仅限 Gateway(网关) 的功能不可用。
  • openclaw 和 openclaw crestodian 也使用此 TUI shell，其中 Crestodian 作为本地设置和修复聊天后端。

您所看到的

Section titled “您所看到的”
  • 页眉：连接 URL、当前代理、当前会话。
  • 聊天记录：用户消息、助手回复、系统通知、工具卡片。
  • 状态栏：连接/运行状态（连接中、运行中、流式传输中、空闲、错误）。
  • 页脚：连接状态 + agent + 会话 + 模型 + think/fast/verbose/trace/reasoning + token 计数 + deliver。
  • 输入：带有自动补全功能的文本编辑器。

心智模型：agents + 会话

Section titled “心智模型：agents + 会话”
  • 代理是唯一的标识符（例如 main、research）。Gateway(网关) 会公开该列表。
  • 会话属于当前的 agent。
  • 会话密钥存储为 agent:<agentId>:<sessionKey>。
    • 如果您输入 /session main，TUI 会将其展开为 agent:<currentAgent>:main。
    • 如果您输入 /session agent:other:main，您将显式切换到该代理会话。
  • 会话范围：
    • per-sender（默认）：每个代理有多个会话。
    • global：TUI 始终使用 global 会话（选择器可能为空）。
  • 当前的 Agent + 会话始终在页脚中可见。
  • 当在不带 --session 的情况下启动时，如果该会话仍然存在，网关模式的 TUI 将恢复同一网关、代理和会话范围内上次选择的会话。传递 --session、/session、/new 或 /reset 仍然保持显式状态。

发送与投递

Section titled “发送与投递”
  • 消息将发送到 Gateway(网关)；默认情况下不投递给提供商。
  • TUI 是一个像 WebChat 这样的内部源表面，而不是通用的出站渠道。需要 tools.message 才能显示可见回复的连接器，可以使用无目标的 message.send 来满足活动的 TUI 回合；显式的提供商交付仍使用正常配置的渠道，绝不会回退到 lastChannel。
  • 开启投递：
    • /deliver on
    • 或设置面板
    • 或以 openclaw tui --deliver 启动

选择器 + 覆盖层

Section titled “选择器 + 覆盖层”
  • 模型选择器：列出可用模型并设置会话覆盖。
  • 代理选择器：选择不同的代理。
  • 会话选择器：显示当前代理在过去 7 天内更新的多达 50 个会话。使用 /session <key> 跳转到较早的已知会话。
  • 设置：切换交付、工具输出展开和思考可见性。

键盘快捷键

Section titled “键盘快捷键”
  • Enter：发送消息
  • Esc：中止正在运行的会话
  • Ctrl+C：清除输入（按两次退出）
  • Ctrl+D：退出
  • Ctrl+L：模型选择器
  • Ctrl+G：代理选择器
  • Ctrl+P：会话选择器
  • Ctrl+O：切换工具输出展开
  • Ctrl+T：切换思考可见性（重新加载历史记录）

斜杠命令

Section titled “斜杠命令”

核心：

  • /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>
  • /trace <on|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

仅限本地模式：

  • /auth [provider]TUI 会在 TUI 内部打开提供商身份验证/登录流程。

其他 Gateway(网关) 斜杠命令（例如 Gateway(网关)/contextGateway(网关)）会被转发到 Gateway(网关) 并显示为系统输出。请参阅 Slash commands。

Local shell commands

Section titled “Local shell commands”
  • 在 TUI 主机上运行本地 shell 命令，请在行首加上 !。
  • 为了允许本地执行，TUI 会在每次会话时提示一次；如果拒绝，该会话期间 ! 将保持禁用状态。
  • 命令在 TUI 工作目录中的一个新的非交互式 shell 中运行（没有持久的 cd/env）。
  • 本地 Shell 命令在其环境中接收 OPENCLAW_SHELL=tui-local。
  • 单独的 ! 将作为普通消息发送；前导空格不会触发本地执行。

从本地 TUI 修复配置

Section titled “从本地 TUI 修复配置”

当当前配置已经通过验证，并且您希望嵌入式代理在同一台机器上检查它、将其与文档进行比较，并在不依赖运行中的 Gateway(网关) 的情况下帮助修复配置漂移时，请使用本地模式。

如果 openclaw config validate 已经失败，请先从 openclaw configure 或 openclaw doctor --fix 开始。openclaw chat 不会绕过无效配置保护。

典型流程：

  1. 启动本地模式：
Terminal window
openclaw chat
  1. 让 agent 检查你需要的内容，例如：
Compare my gateway auth config with the docs and suggest the smallest fix.
  1. 使用本地 shell 命令获取确切的证据和验证：
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
  1. 使用 openclaw config set 或 openclaw configure 应用局部更改，然后重新运行 !openclaw config validate。
  2. 如果 Doctor 建议自动迁移或修复，请查看并运行 !openclaw doctor --fix。

提示：

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

工具输出

Section titled “工具输出”
  • 工具调用显示为包含参数 + 结果的卡片。
  • Ctrl+O 用于在折叠/展开视图之间切换。
  • 在工具运行时，部分更新会流式传输到同一张卡片中。

终端颜色

Section titled “终端颜色”
  • TUI 会将助手正文文本保留在终端的默认前景色中，因此深色和浅色终端都能保持可读性。
  • 如果您的终端使用浅色背景且自动检测错误，请在启动 openclaw tui 之前设置 OPENCLAW_THEME=light。
  • 若要强制使用原始深色调色板，请设置 OPENCLAW_THEME=dark。

历史记录 + 流式传输

Section titled “历史记录 + 流式传输”
  • 连接时，TUI 会加载最新的历史记录（默认 200 条消息）。
  • 流式响应会原地更新，直到完成。
  • TUI 还会监听代理工具事件，以显示更丰富的工具卡片。

连接详情

Section titled “连接详情”
  • TUI 向 Gateway(网关) 注册为 TUIGateway(网关)mode: "tui"。
  • 重连会显示系统消息；事件间隙会在日志中显示。

选项

Section titled “选项”
  • --local：针对本地嵌入式代理运行时运行
  • --url <url>Gateway(网关)：Gateway(网关) WebSocket URL（默认为配置或 ws://127.0.0.1:<port>）
  • --token <token>Gateway(网关)：Gateway(网关)令牌（如果需要）
  • --password <password>Gateway(网关)：Gateway(网关)密码（如果需要）
  • --session <key>：会话密钥（默认值：main，或当作用域为全局时为 global）
  • --deliver：将助手回复投递给提供商（默认关闭）
  • --thinking <level>：覆盖发送的思维级别
  • --message <text>：连接后发送初始消息
  • --timeout-ms <ms>：代理超时时间，以毫秒为单位（默认为 agents.defaults.timeoutSeconds）
  • --history-limit <n>：要加载的历史记录条目（默认 200）

故障排除

Section titled “故障排除”

发送消息后无输出：

  • 在 TUI 中运行 /status 以确认 Gateway(网关) 已连接并处于空闲/忙碌状态。
  • 检查 Gateway(网关) 日志：openclaw logs --follow。
  • 确认代理能否运行：openclaw status 和 openclaw models status。
  • 如果您期望在聊天渠道中收到消息，请启用投递（/deliver on 或 --deliver）。

连接故障排除

Section titled “连接故障排除”
  • disconnected：确保 Gateway(网关) 正在运行且您的 --url/--token/--password 正确。
  • 选择器中没有 Agent：检查 openclaw agents list 和您的路由配置。
  • 空会话选择器：您可能处于全局作用域或尚未有任何会话。

相关

Section titled “相关”