一、前置准备

1. 启动 & 检查网关

仪表板、WebChat 均依赖 Gateway 运行，先执行状态校验：

bash

运行

# 查看网关运行状态
openclaw gateway status

# 未运行则启动
openclaw gateway run

正常输出示例：

plaintext

Gateway is running on http://127.0.0.1:18789

默认端口：18789。

2. 基础访问地址

本地统一入口：

plaintext

http://127.0.0.1:18789/

---

二、Control UI 管理仪表板

1. 核心功能总览

仪表板以可视化页面为主，偏向查看、监控、管理，配置修改仍需编辑 ~/.openclaw/openclaw.json。

（1）渠道状态页

首页默认展示所有已接入聊天渠道：

• 状态标识：✅已连接 / ⚠️配置中 / ❌已断开
• 展示信息：渠道类型、在线状态、最后活跃时间、消息统计
• 用途：快速排查渠道掉线、异常问题

（2）会话管理页

集中管理全量会话：

• 查看活跃会话列表、关联渠道 / 联系人
• 翻阅历史聊天记录
• 手动执行 /reset 重置会话、/stop 结束会话

（3）配置查看页

可视化读取当前运行配置：

• 已启用工具、技能、插件列表
• 模型、智能体、渠道全局配置

仅查看，不支持在线编辑。

（4）实时日志页

实时滚动输出运行日志：

• 消息收发、模型调用、工具执行日志
• 报错、警告、钩子运行记录
• 核心用途：调试、排障、审计。

---

三、WebChat 内置聊天界面

WebChat 集成在仪表板内，基于 WebSocket 直连网关，无需对接第三方渠道，主打本地测试。

1. 进入方式

1. 打开 http://127.0.0.1:18789/
2. 点击页面聊天图标 / WebChat 入口，直接开始对话

2. 核心优势

1. 零配置：网关启动即可用，无需 Token、账号等配置
2. 低延迟：本地 WebSocket 通信，响应最快
3. 功能完整：支持代码高亮、文件上传、流式回复
4. 调试友好：浏览器 F12 可查看前端、WebSocket 原始数据

3. 适用场景

• 新技能 / 插件上线前本地测试
• 修改模型、Hooks、记忆配置后验证效果
• 本地演示、快速问答
• 排除第三方渠道带来的干扰问题

4. WebChat VS 外部渠道

表格

对比项	WebChat	Telegram / 微信等外部渠道
配置	无需配置	需密钥、Token、网络
网络	仅本地	需外网 / 代理
功能限制	无限制	受平台接口规则约束
主要用途	开发、调试、测试	日常对外使用

---

四、TUI 终端交互界面

纯终端聊天方案，适合 SSH 远程服务器、无图形桌面 场景。

1. 启动 TUI

bash

运行

openclaw tui

2. 常用快捷键

表格

快捷键	功能
Enter	发送消息
Shift + Enter	换行（多行输入代码 / 文本）
↑ / ↓	翻阅历史消息
Ctrl + C	退出 TUI 界面

3. 单条消息快速调用（不进入交互界面）

仅发一条消息并获取结果，适合脚本、批量调用：

bash

运行

# 直接传文本
openclaw agent --message "帮我写一段 Python 排序代码"

# 读取文本文件内容作为提问
openclaw agent --message "$(cat question.txt)"

4. TUI VS WebChat

表格

对比项	TUI 终端界面	WebChat 浏览器界面
运行环境	终端 / SSH	浏览器
文件上传	不支持	支持
代码高亮	基础样式	完整高亮
推荐场景	服务器远程运维	本地开发、演示

---

五、远程访问配置

默认仅本地 127.0.0.1 访问，多设备 / 外网访问提供三种方案，优先推荐前两种安全方案。

方案一：Tailscale（首选，安全无端口暴露）

基于加密虚拟内网，不用修改防火墙、不用公网 IP。

1. 服务器安装 Tailscale

bash

运行

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

1. 获取虚拟内网 IP

bash

运行

tailscale ip -4

1. 个人设备安装同账号 Tailscale，直接访问：

plaintext

http://TailscaleIP:18789/

方案二：SSH 隧道（适合已有 SSH 权限）

本地执行端口转发，流量走 SSH 加密隧道：

bash

运行

# 本地终端执行，替换为你的服务器账号和IP
ssh -L 18789:127.0.0.1:18789 用户名@服务器IP

转发成功后，本地浏览器打开：

plaintext

http://127.0.0.1:18789/

方案三：修改监听地址（公网慎用，必须搭配认证）

将网关监听所有网卡，允许全网访问，公网环境务必开启认证。

编辑 ~/.openclaw/openclaw.json：

json

{
  "gateway": {
    "host": "0.0.0.0",
    "port": 18789
  }
}

修改后重启网关：

bash

运行

openclaw gateway restart

---

六、仪表板访问认证（公网必开）

网关暴露到外网后，必须配置身份认证，防止未授权访问。

1. Token 密钥认证（简单高效）

配置文件：

json

{
  "gateway": {
    "auth": {
      "type": "token",
      "token": "你的随机密钥"
    }
  }
}

访问格式：

plaintext

http://服务器IP:18789/?token=你的随机密钥

生成安全随机密钥

bash

运行

# 方式1：openssl
openssl rand -hex 32

# 方式2：Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. 账号密码认证

json

{
  "gateway": {
    "auth": {
      "type": "password",
      "username": "admin",
      "password": "高强度密码"
    }
  }
}

访问时会弹出登录框，输入账号密码进入。

3. 可信代理认证（搭配 Nginx 反向代理）

认证交由前端 Nginx 处理：

json

{
  "gateway": {
    "auth": {
      "type": "trusted-proxy",
      "trustedProxies": ["127.0.0.1"]
    }
  }
}

---

七、反向代理 Nginx 配置（WebSocket 兼容）

使用 Nginx 做反向代理时，必须额外配置 WebSocket 升级，否则 WebChat 连接失败：

nginx

server {
    listen 80;
    server_name 你的域名;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

配置重载：

bash

运行

nginx -t && nginx -s reload

---

八、常见问题排查

1. 仪表板无法打开

1. 检查网关状态：openclaw gateway status，未运行则启动
2. 检查端口占用：lsof -i :18789
3. 检查防火墙：sudo ufw status，放行 18789 端口
4. 重启网关：openclaw gateway restart

2. WebChat 提示连接失败

1. 确认网关正常运行
2. 反向代理场景：检查 Nginx WebSocket 配置是否完整
3. 浏览器 F12 查看 Console / Network，排查 WebSocket 报错

3. 远程访问延迟高

1. 优先切换 Tailscale，网络稳定性最优
2. SSH 隧道延迟取决于 SSH 链路质量
3. 公网直连检查服务器带宽、地区线路

---

九、使用场景总结

1. 本地开发 / 调试 → 首选 WebChat，零干扰、功能最全
2. 服务器远程运维、纯命令行环境 → 首选 TUI 终端界面
3. 状态监控、会话管理、日志排查 → 首选 Control UI 仪表板
4. 多设备远程访问 → Tailscale / SSH 隧道（安全优先）
5. 公网部署 → 开启认证 + Nginx 反向代理，禁止裸端口暴露