> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.1_control_ui_webchat.md).

# 3.1 控制台与 Chat 快速上手

本节以官方 Web 端为准建立最小闭环：先用 CLI 确认网关健康，再用 Dashboard 打开 Control UI 的 Chat 页做一次最小交互验证，并把“新设备访问需要批准”这类常见拦截纳入排障路径。目标是让渠道接入之前就具备一条稳定、可复验的本地基准线，以验证核心功能正常运行。

## 3.1.1 为什么先从 Dashboard 与 Chat 开始

外部渠道接入会引入大量外部变量：平台限流、回调重试、网络抖动、群聊噪声等。先用本地 Dashboard 的 Control UI Chat 验证主链路，有两个直接收益。

* 把问题分层：如果本地 Control UI Chat 能正常运行，外部渠道失败更可能是渠道配置或平台侧问题。
* 建立证据链：本地交互更容易复现，日志与 trace 更完整。

官方建议的桌面端入口是 Dashboard，通常运行在 `http://127.0.0.1:18789/` 等本地地址。

## 3.1.2 打开 Dashboard：端口、入口与常见拦截

Dashboard（Control UI）是 OpenClaw 的 Web 管理中心。根据当前源码与官方文档，左侧栏稳定的一级分组仍是 **`Chat`、`Control`、`Agent`、`Settings`**，另外底部有独立的 `Docs` 外链入口。下面先给出当前常见页面，再聚焦本章最常用的几个页面。

> \[!TIP] **第一次跑通时，只需要记住 3 个页面：** `Chat` 用来做最小交互，`Overview` 用来确认网关健康，`Logs` 用来对照排障。其余页面先知道它们存在即可，不必在首轮验收前逐个理解。

### 左侧导航结构

**Chat**——对话交互入口。

* **Chat**（`/chat`）：Control UI 的浏览器对话窗口。支持会话选择、新建会话、agent filter、模型与 thinking session override，以及流式输出。右上角的显示开关可展示 assistant thinking / working 输出，但不应理解成直接暴露模型内部推理链。Focus Mode 用于隐藏导航栏专注对话。本章把浏览器入口称为 Control UI Chat；官方 WebChat 文档还会同时覆盖原生 macOS/iOS 聊天 UI 以及共享的会话投影语义。

**Control**——运行状态与运维监控。

* **Overview**（`/overview`）：网关总览页。上方为 Gateway Access 连接信息（WebSocket URL、Token、Session Key、语言设置），下方为 Snapshot 快照卡片（Status、Uptime、Tick Interval 等）。排障时从此页面确认网关健康状态。
* **Instances**：当前界面中的实例视图，用于查看当前连接到控制面的实例状态。
* **Sessions** 页面（路由 `/sessions`）：活跃会话键与每会话默认值管理页。可查看最近活跃的 `session key`、Token 用量与 `thinking` / `verbose` / `reasoning` 等覆盖项。详见[第六章 6.1 会话模型](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/06_context_memory/6.1_sessions.md)。
* **Usage**：当前界面中的用量视图，用于查看系统的资源或调用用量汇总。
* **Cron Jobs**（`/cron`）：定时任务管理。支持查看、新增、启用/禁用和手动触发定时任务。详见[第八章 8.2 定时任务](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/08_automation_ops/8.2_cron_jobs.md)。

**Agent**——智能体配置与能力管理。

* **Agents**（`/agents`）：智能体配置中心。左侧为智能体列表，右侧为详情面板。进入某个智能体后，内部提供子面板切换：Overview（身份与模型选择、回退模型配置）、Files（展示当前 `agents.files.list` 返回的工作区指令文件）、Tools（工具目录与 allow/deny 策略控制）、Skills（已安装技能开关与工作区技能管理）、Channels（渠道绑定）、Cron（智能体级定时任务）。详见[第四章](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models.md)和[第五章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills.md)。
* **Skills**（`/skills`）：全局技能管理。安装、启用/禁用技能包，更新 API 密钥。详见[第五章 5.3 技能与插件](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.3_skills_plugins.md)。
* **Nodes**（`/nodes`）：设备与节点管理。查看已配对设备、批准待配对设备、管理执行审批。详见[第九章 9.5 渠道配对](/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/09_gateway_protocol/9.5_pairing_trust.md)。
* **Dreaming**（`/dreaming`）：记忆整理与 dreaming 相关状态页。入口是稳定的 Agent 标签页，页面内容和状态取决于 dreaming 配置与运行时状态。

**Settings**——系统配置、通信、外观、自动化、基础设施、智能体设置与调试入口。

* **Config**（`/config`）：配置编辑器。以当前 UI 支持的表单或源码视图查看和编辑 `openclaw.json`，并在保存时进行配置校验。详见[第四章 4.1 配置体系](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.1_config_system.md)。
* **Channels**（`/channels`）：渠道状态与配置的设置详情页，不是 Control 分组的根级页面。当前可见卡片会随内置渠道、外部插件和启用状态变化。详见[第七章](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/07_multi_agent.md)。
* **Communications / Appearance / Automation / Infrastructure / AI & Agents**：分别收纳通信、界面、自动化、基础设施与智能体相关设置；其中 AI & Agents 对应 `/ai-agents`，具体命名和是否显示以当前 UI 文案为准。
* **Debug**（`/debug`）：调试工具。当前更贴近“status/health/models/heartbeat 快照 + Event Log + 手动 RPC 调用”的综合调试页，而不是通用的事件重放中心。
* **Logs**（`/logs`）：实时日志查看器。读取网关日志文件，支持过滤、关键词搜索与自动跟随。排障时对比日志与交互输出。
* **Docs**：文档入口。当前源码里它作为侧边栏底部的外链入口出现，不属于 `Settings` 组内的 tab。

> **版本说明**：Dashboard 当前采用分组导航；可见分组为 `Chat`、`Control`、`Agent`、`Settings`，另外侧边栏底部还有独立的 `Docs` 外链入口。具体子页面名称和是否显示会继续演进，请以当前 UI 文案为准。

本章主要用到 **Chat**（交互验证）、**Overview**（健康检查）和 **Logs**（排障对比）三个页面。按当前分组，它们分别位于 `Chat`、`Control` 和 `Settings`。

如果你是第一次打开 Dashboard，先认清 Overview 页面最省时间。下面这张图展示了左侧导航、Gateway Access 连接信息和 Snapshot 快照卡片的典型布局。

![Dashboard Overview 总览页](/files/uM7CrX9cVjFFViLBh2n6)

图 3-1：Dashboard Overview 总览页示意

操作步骤建议如下。

1. 先确认服务健康。

```bash
openclaw health --json
```

2. 打开 Dashboard。

```bash
openclaw dashboard

# 或直接在网关机器上打开：
# http://127.0.0.1:18789/
```

默认情况下，Dashboard 运行在 `http://127.0.0.1:18789/`。

常见拦截：**不是所有首次访问都需要人工批准。** 若你是在网关机器上通过 `127.0.0.1` / `localhost` 直连浏览器，本地 loopback 访问通常会自动批准；Tailnet 或局域网中的新浏览器/新设备则更可能进入待批准状态。若 Dashboard 提示设备待批准，可按官方流程列出并批准设备（命令与字段以实际版本为准，参考 onboarding 指南）。

```bash
openclaw devices list
openclaw devices approve <requestId>
```

批准前建议重新运行 `openclaw devices list`，因为待批准请求的 `requestId` 会随重试或重新打开页面变化。

## 3.1.3 Control UI Chat 的交互与流式：看得见的过程更容易排障

Control UI Chat 的关键价值在于把过程暴露出来：模型请求是否发出、工具是否被提议与执行、输出是否在流式返回。对排障而言，最重要的是把每次交互与日志里的 trace 对齐。

操作建议：开启结构化日志并在 Dashboard 的 Chat 界面对比流式输出。

先看 Chat 页面，确认自己找对了最小交互入口。

![Control UI Chat 对话界面](/files/0bstpCA6KvYjRG2OQeyt)

图 3-2：Control UI Chat 对话界面示意

Chat 页面提供了完整的交互视图：对话输入区、流式输出区（包含用户输入、assistant thinking / working 输出、工具调用请求与返回结果），以及右上角的会话选择器和模型切换器。部署 OpenClaw 后，点击左侧 Chat 分区即可进入；不要把 UI 中的 thinking 展示等同于模型内部不可见推理链。

```bash
openclaw logs --follow --json
```

如果你更习惯先看证据，再回到对话窗口定位问题，也可以直接打开 Dashboard 的 Logs 页面。

![Logs 实时监控界面](/files/upgNkybZN9hMyM8cnTqS)

图 3-3：Logs 实时监控界面示意

## 3.1.4 最小闭环测试用例

建议用可复验的测试用例验证最小闭环，而不是随意发问。

**测试用例 1：健康链路确认**

* 动作：先执行 `health`，再打开 Dashboard。
* 预期正常输出：看到一份可解析的健康快照或探针结果，且整体状态正常。
* 注意：`health` 的 JSON 字段会随版本变化，不建议把它写死为某个固定 schema。
* Dashboard 访问成功，无设备待批准提示。

**测试用例 2：最小交互**

* 动作：在 Control UI Chat 输入 `请只输出一个 JSON：{"pong": true}`。
* 预期正常输出：

  ```
  {"pong": true}
  ```
* 注意：以下日志示例仅为示意性参考。当前文件日志更稳定的字段是 `time`、`message`、`session_id`、`channel`、`agent_id`、`traceId` 与 `spanId` 等，CLI 的 `openclaw logs --json` 会输出 `type=="log"` 记录，并保留 `raw` 便于回看原始 JSONL。真正排障时应以本机结构化日志的实际字段为准。
* 对应日志片段（结构化日志，JSONL 每行一条 JSON）：

  ```jsonl
  {"time":"2026-03-06T10:30:45.123Z","session_id":"sess_abc123","traceId":"t-abc123","message":"chat request received"}
  {"time":"2026-03-06T10:30:47.456Z","session_id":"sess_abc123","traceId":"t-abc123","spanId":"s-reply","message":"assistant response sent"}
  ```

**测试用例 3：流式输出可验证**

* 动作：输入 `请分 5 步输出一个排障计划，每步不超过 20 字`。
* 预期正常输出（流式返回）：

  ```
  1. 确认服务健康 ✓
  2. 检查渠道连接状态 ✓
  3. 查询最近日志错误 ✓
  4. 验证模型权限与配额 ✓
  5. 隔离问题根源 ✓
  ```
* 预期日志表现：
  * 实际事件名以 `openclaw logs --json` 和 agent stream 输出为准，重点观察 `assistant`、`tool`、`lifecycle`、`error`、`command_output` 等流。
  * 若延迟 >5s，先查看是否有工具调用、模型等待或供应商限流相关日志，不要假定存在固定的分块发送事件。
  * 若完全卡住，查看是否有 `error` 或 `timeout` 事件。