可以直接通过 OpenClaw TUI 与智能体交互：用 openclaw tui 连接运行中的 Gateway，或用 openclaw chat 启动本地模式不依赖 Gateway。第一次使用先运行 openclaw gateway 启动网关，再开 TUI；连接远程 Gateway 需要传递 --url 和 --token 或 --password。消息发送后默认不投递到聊天频道，需要手动开启 /deliver on 或启动时加 --deliver。如果发送消息无输出，先运行 /status 确认连接状态，再检查 Gateway 日志 openclaw logs --follow。

OpenClaw 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，直接在本地运行：

openclaw chat
# 或
openclaw tui --local

注意：

• openclaw chat 和 openclaw terminal 都是 openclaw tui --local 的别名。
• --local 不能与 --url、--token 或 --password 同时使用。
• 本地模式使用内置的智能体运行时。大多数本地工具可用，但 Gateway 专属功能不可用。
• openclaw 和 openclaw crestodian 也使用这个 TUI shell，Crestodian 作为本地设置和修复聊天后端。

界面元素

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

心智模型：智能体 + 会话

• 智能体是唯一的 slug（例如 main、research）。Gateway 会暴露列表。
• 会话属于当前智能体。
• 会话键存储为 agent:<agentId>:<sessionKey>。
  • 输入 /session main，TUI 将其展开为 agent:<currentAgent>:main。
  • 输入 /session agent:other:main，显式切换到该智能体的会话。
• 会话范围：
  • per-sender（默认）：每个智能体可以有多个会话。
  • global：TUI 始终使用 global 会话（选择器可能为空）。
• 当前智能体 + 会话始终显示在底部栏。
• 启动时若未加 --session，Gateway 模式下的 TUI 会恢复上次为该 Gateway、智能体、会话范围选择的会话（如果仍存在）。显式传递 --session、使用 /session、/new 或 /reset 则始终明确执行。

发送 + 投递

• 消息发送到 Gateway；默认不向提供商投递。
• TUI 是内部源界面（类似 WebChat），不是通用外发渠道。依赖 tools.message 获取可见回复的 Harness，可以通过无目标的 message.send 满足当前 TUI 回合；明确提供商投递仍使用正常配置的渠道，不会回退到 lastChannel。
• 开启投递：
  • /deliver on
  • 或 Settings 面板切换
  • 或启动时加 openclaw tui --deliver

选择器 + 浮层

• 模型选择器：列出可用模型并设置会话覆盖。
• 智能体选择器：选择不同智能体。
• 会话选择器：显示当前智能体最近 7 天更新过的最多 50 个会话。使用 /session <key> 跳转到更早的已知会话。
• 设置：切换投递、工具输出展开和思考可见性。

键盘快捷键

快捷键	作用
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>
• /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 中打开提供商认证/登录流程。

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

本地 Shell 命令

• 以 ! 开头的行会在 TUI 主机上运行本地 shell 命令。
• TUI 每个会话会提示一次是否允许本地执行；拒绝后当前会话 ! 保持禁用。
• 命令在全新的非交互 shell 中运行，工作目录为 TUI 工作目录（持久 cd/env 不生效）。
• 本地 shell 命令会收到环境变量 OPENCLAW_SHELL=tui-local。
• 单独的 ! 作为普通消息发送；前导空格不会触发本地执行。

从本地 TUI 修复配置

如果当前配置已通过验证，但你想让嵌入式智能体在同一台机器上检查配置并与文档比对，可以使用本地模式帮助修复漂移，不需要依赖运行中的 Gateway。

如果 openclaw config validate 已经报错，先运行 openclaw configure 或 openclaw doctor --fix。openclaw chat 不会绕过无效配置保护。

典型步骤：

1. 启动本地模式：

openclaw chat

2. 向智能体提问你想检查的内容，例如：

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>" 在同一台机器上搜索实时文档索引。
• openclaw config validate --json 用于获取结构化 schema 和 SecretRef/可解析性错误。

工具输出

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

终端颜色

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

历史 + 流式传输

• 连接时，TUI 加载最新历史（默认 200 条消息）。
• 流式响应就地在卡片中更新，直到完成。
• TUI 还会监听智能体工具事件以显示更丰富的工具卡片。

连接详情

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

选项

选项	说明
--local	针对本地嵌入式智能体运行时运行
--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>	覆盖发送时的思考级别
--message <text>	连接后发送初始消息
--timeout-ms <ms>	智能体超时（毫秒，默认 agents.defaults.timeoutSeconds）
--history-limit <n>	加载的历史条目数（默认 200）

WARNING

使用 --url 时，TUI 不会回退到配置或环境凭据，必须显式传递 --token 或 --password。缺少显式凭据会报错。本地模式下不要传递 --url、--token 或 --password。

故障排查

发送消息后无输出

• 在 TUI 中运行 /status 确认 Gateway 已连接且状态为 idle 或 busy。
• 检查 Gateway 日志：openclaw logs --follow。
• 确认智能体可以运行：openclaw status 和 openclaw models status。
• 如果希望消息出现在聊天频道中，开启投递（/deliver on 或启动时加 --deliver）。

连接后显示 disconnected

• 确保 Gateway 正在运行。
• 确认 --url、--token、--password 正确。
• 检查 openclaw agents list 和路由配置。
• 如果会话选择器为空，你可能处于 global 范围，或者尚无会话。

相关文档

• Control UI Web 控制界面
• 配置管理 — 查看、验证和编辑 openclaw.json
• Doctor 修复工具 — 引导式修复和迁移检查
• CLI 参考 — 完整 CLI 命令参考

常见问题

OpenClaw TUI 连接不上怎么办

先确保 Gateway 已启动：openclaw gateway。然后检查 TUI 的 --url 和 --token 是否正确。使用 /status 查看连接状态，如果显示 disconnected，重新核对地址和认证方式。本地模式下不要传递 --url。

OpenClaw TUI 如何开启消息投递到聊天频道

在 TUI 中输入 /deliver on，或者在 Settings 面板中切换投递开关，也可以在启动时加 --deliver。开启前发送的消息不会自动投递。

OpenClaw TUI 如何使用本地 shell 命令

在输入框中以 ! 为前缀即可运行本地 shell 命令，例如 !openclaw config validate。第一次使用会提示确认是否允许本地执行。注意：单独的 ! 作为普通消息发送，前导空格不会触发本地执行。