# 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` 事件。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.1_control_ui_webchat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.