TUI

快速开始

Gateway(网关) 模式

1. 启动 Gateway(网关) 网关。

openclaw gateway

2. 打开 TUI。

openclaw tui

3. 输入消息并按 Enter 键。

远程 Gateway(网关) 网关：

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

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

本地模式

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

openclaw chat
# or
openclaw tui --local

注意事项：

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

您所看到的

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

心智模型：agents + 会话

• 代理是唯一的标识符（例如 main、research）。Gateway(网关) 会公开该列表。
• 会话属于当前的 agent。
• 会话密钥存储为 agent:<agentId>:<sessionKey>。
  • 如果您输入 /session main，TUI 会将其展开为 agent:<currentAgent>:main。
  • 如果您输入 /session agent:other:main，您将显式切换到该代理会话。
• 会话范围：
  • per-sender（默认）：每个代理有多个会话。
  • global：TUI 始终使用 global 会话（选择器可能为空）。
• 当前的 Agent + 会话始终在页脚中可见。
• If the 会话 has a goal, the footer shows its compact state such as Pursuing goal, Goal paused (/goal resume), or Goal achieved.
• When started without --sessionTUI, gateway-mode TUI resumes the last selected 会话 for the same gateway, agent, and 会话 scope if that 会话 still exists. Passing --session, /session, /new, or /reset remains explicit.

Sending + delivery

• Messages are sent to the Gateway; delivery to providers is off by default.
• The TUI is an internal source surface like WebChat, not a generic outbound 渠道. Harnesses that require TUIWebChattools.messageTUI for visible replies can satisfy the active TUI turn with a targetless message.send; explicit 提供商 delivery still uses normal configured channels and never falls back to lastChannel.
• Turn delivery on:
  • /deliver on
  • or the Settings panel
  • or start with openclaw tui --deliver

Pickers + overlays

• Model picker: list available models and set the 会话 override.
• Agent picker: choose a different agent.
• Session picker: shows up to 50 sessions for the current agent updated in the last 7 days. Use /session <key> to jump to an older known 会话.
• Settings: toggle deliver, 工具 output expansion, and thinking visibility.

Keyboard shortcuts

• Enter: send message
• Esc: abort active run
• Ctrl+C: clear input (press twice to exit)
• Ctrl+D: exit
• Ctrl+L: 模型 picker
• Ctrl+G: agent picker
• Ctrl+P: 会话 picker
• Ctrl+O: toggle 工具 output expansion
• Ctrl+T: toggle thinking visibility (reloads history)

Slash commands

Core:

• /help
• /status
• /agent <id> (or /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>
• /goal [status] | /goal start <objective> | /goal pause|resume|complete|block|clear
• /elevated <on|off|ask|full> （别名： /elev）
• /activation <mention|always>
• /deliver <on|off>

会话生命周期：

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

仅限本地模式：

• /auth [provider] 在 TUI 内部打开提供商授权/登录流程。

其他 Gateway(网关) 斜杠命令（例如 /context）会被转发到 Gateway(网关) 并作为系统输出显示。参见 斜杠命令。

本地 Shell 命令

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

从本地 TUI 修复配置

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

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

典型循环：

1. 启动本地模式：

openclaw chat

2. 向 agent 询问您想要检查的内容，例如：

Compare my gateway auth config with the docs and suggest the smallest fix.

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 config set 或 openclaw configure 而不是手动编辑 openclaw.json。
• 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 向 Gateway 注册为 TUIGateway(网关)mode: "tui"。
• 重新连接会显示一条系统消息；事件间隔会显示在日志中。

选项

• --local：针对本地嵌入式 agent 运行时运行
• --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）

Warning

当您设置

--url

TUI 时，TUI 不会回退到配置或环境凭据。请显式传递

--token

或

--password

。缺少显式凭据是一个错误。在本地模式下，不要传递

--url

、

--token

或

--password

。

故障排除

发送消息后无输出：

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

连接故障排除

• disconnectedGateway(网关)：确保 Gateway(网关) 正在运行且您的 --url/--token/--password 是正确的。
• 选择器中没有代理：检查 openclaw agents list 和您的路由配置。
• 会话选择器为空：您可能处于全局作用域或尚未有任何会话。

相关内容

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