OpenClaw WebChat 浏览器聊天配置教程

2026-01-14 · 6 分钟频道对接

WebChat 概述

WebChat 是 OpenClaw 内置的浏览器聊天界面，基于 WebSocket 协议与 Gateway 直接通信。无需依赖任何外部服务，开箱即用。

它的主要特性包括：

流式响应，实时显示 AI 输出
工具调用过程可视化
图片上传支持
多会话管理

访问 WebChat

WebChat 集成在 Gateway 的控制界面中，启动网关后即可使用：

# 启动网关
openclaw gateway start --port 8080

# WebChat 地址
# http://localhost:8080

打开浏览器访问 http://localhost:8080，进入控制面板后即可看到 WebChat 入口。

基本配置

{
  gateway: {
    port: 8080,
    authToken: "oc_gw_xxxxxxxxxxxxx",

    webchat: {
      // 是否启用 WebChat（默认启用）
      enabled: true,

      // 页面标题
      title: "OpenClaw 助手",

      // 欢迎消息
      welcomeMessage: "你好！我是 OpenClaw AI 助手，有什么可以帮你的？",

      // 使用的 Agent
      agent: "default"
    }
  }
}

流式响应

WebChat 默认启用流式响应，AI 的输出会实时逐字显示。WebSocket 连接确保了低延迟的双向通信：

浏览器 ←WebSocket→ Gateway ←→ AI 模型

流式响应的配置选项：

{
  gateway: {
    webchat: {
      streaming: {
        // 启用流式输出（默认 true）
        enabled: true,

        // 打字效果延迟（毫秒），0 为即时显示
        typeDelay: 0
      }
    }
  }
}

工具调用可视化

当 AI 调用工具时，WebChat 界面会实时展示调用过程：

┌─────────────────────────────────┐
│ 🔧 正在调用工具: fs_read        │
│ 参数: { path: "/etc/hosts" }   │
│ 状态: 执行中...                 │
└─────────────────────────────────┘

可以控制工具调用的显示级别：

{
  gateway: {
    webchat: {
      toolDisplay: {
        // 显示级别: minimal / normal / verbose
        level: "normal",

        // 是否展示工具返回结果
        showResults: true
      }
    }
  }
}

图片上传

WebChat 支持直接上传图片，配合多模态模型使用：

{
  gateway: {
    webchat: {
      upload: {
        // 允许图片上传
        images: true,

        // 最大文件大小（MB）
        maxSize: 10,

        // 支持的格式
        formats: ["jpg", "png", "gif", "webp"]
      }
    }
  }
}

确保配置的模型支持视觉输入（如 Claude Opus、GPT-4o）。

本地网络访问

在同一局域网内的其他设备可以通过局域网 IP 访问 WebChat：

# 查看本机 IP
hostname -I
# 例如: 192.168.1.100

# 其他设备访问
# http://192.168.1.100:8080

确保网关监听所有接口：

{
  gateway: {
    // 监听所有网络接口（默认仅 localhost）
    host: "0.0.0.0",
    port: 8080
  }
}

Tailnet 远程访问

通过 Tailscale 虚拟网络安全地远程访问 WebChat：

# 确保 Tailscale 已连接
tailscale status

# 通过 Tailnet 域名访问
# http://your-machine.tailnet-name.ts.net:8080

这种方式无需暴露公网端口，流量经过 WireGuard 加密。

设备配对

对于远程访问场景，OpenClaw 提供了设备配对机制，确保只有授权设备可以连接：

# 生成配对码
openclaw gateway pair --generate
# 输出: 配对码 ABCD-1234-EFGH

# 在远程设备的浏览器中输入配对码完成认证

配对配置：

{
  gateway: {
    pairing: {
      // 启用设备配对
      enabled: true,

      // 配对码有效期（分钟）
      codeExpiry: 5,

      // 最大配对设备数
      maxDevices: 10,

      // 已配对设备的 Token 有效期（天）
      tokenExpiry: 30
    }
  }
}

管理已配对的设备：

# 查看已配对设备
openclaw gateway pair --list

# 移除某个设备
openclaw gateway pair --revoke device-id

# 移除所有设备
openclaw gateway pair --revoke-all

多会话管理

WebChat 支持同时维护多个对话会话：

{
  gateway: {
    webchat: {
      sessions: {
        // 最大同时会话数
        maxSessions: 10,

        // 会话超时（分钟）
        timeout: 60,

        // 是否持久化会话历史
        persist: true
      }
    }
  }
}

常见问题排查

无法访问 WebChat：确认网关正在运行，检查端口和 host 配置
WebSocket 连接失败：检查浏览器控制台错误，确认没有代理拦截 WebSocket
图片上传失败：检查文件大小和格式限制，确认模型支持视觉输入
远程设备无法连接：确认 host 设为 0.0.0.0，检查防火墙规则
配对码无效：配对码有时效限制，重新生成后尽快使用