OpenClaw WebChat 渠道
即时通讯
简单
WebChat 是 OpenClaw Gateway 内置的聊天界面。它通过 WebSocket 直接连接——无需外部服务、API 密钥或第三方账号。只需启动 Gateway、配置认证，然后打开 WebChat 界面即可开始与 AI 助手对话。所有消息采用确定性路由，意味着回复始终返回到发起对话的 WebChat 会话。
快速信息
难度简单
分类即时通讯
支持功能数1 / 6
WebChat 支持的功能
文本消息
支持
媒体与文件
不支持
消息反应
不支持
消息线程
不支持
语音消息
不支持
群聊
不支持
WebChat 前置条件
- 已安装并运行 OpenClaw Gateway
- 已配置 Gateway 认证（token 或密码模式）
- 现代浏览器（Control UI）或原生 macOS/iOS 客户端
- 可访问 Gateway WebSocket 端口的网络（默认：3000）
WebChat 快速设置
1
启动 Gateway
启动 OpenClaw Gateway。WebChat 是内置功能——无需单独安装或插件。运行 'openclaw start' 启动 Gateway 服务。
2
配置认证
在 openclaw.json 中通过 gateway.auth.mode 设置 'token' 或 'password' 认证方式。所有连接（包括 localhost）都必须配置认证。
3
打开 WebChat
通过浏览器中的 Control UI 聊天标签页访问 WebChat 界面，或启动原生 macOS/iOS 客户端。连接到 ws://localhost:3000（或你配置的主机和端口）上的 Gateway。
4
开始对话
发送一条测试消息以验证连接。AI 助手将通过同一个 WebChat 会话进行回复。对话历史由 Gateway 管理，在重新连接后仍然保留。
WebChat 配置示例
config.json
{
"gateway": {
"port": 3000,
"bind": "127.0.0.1",
"auth": {
"mode": "token",
"token": "YOUR_SECRET_TOKEN"
}
}
}WebChat 深入了解
架构概述
WebChat 通过 WebSocket 连接与 OpenClaw Gateway 通信，主要使用三种操作：
• chat.history — 从 Gateway 获取对话历史
• chat.send — 向 AI 助手发送用户消息
• chat.inject — 直接向对话记录中追加助手备注并广播到界面，不触发 Agent 运行
与依赖外部服务和 Webhook 的其他渠道不同，WebChat 是 Gateway 的原生功能。消息不会离开你的基础设施——WebSocket 连接在界面客户端和 Gateway 进程之间直接建立。路由是确定性的：AI 的回复始终返回到发起对话的 WebChat 会话。
WebChat 是最容易配置的渠道，因为它不需要外部账号或 API 密钥——只需 Gateway 本身即可。
chat.inject 操作适用于向对话中添加系统备注或上下文，而不会触发 AI 回复。
Gateway 认证
所有 WebChat 连接都需要认证，即使是环回地址（localhost）连接也不例外。这可以防止未经授权访问你的 AI 助手。
OpenClaw 支持两种认证模式：
• token — 在 WebSocket 握手中传递共享密钥 token。适合程序化访问和单用户场景。
• password — 基于密码的认证。适合每个用户拥有独立凭据的多用户环境。
WebChat 接受连接前，必须至少配置 token 或 password 其中之一。在 openclaw.json 的 gateway.auth 设置中进行配置。
openclaw.json
{
"gateway": {
"auth": {
"mode": "token",
"token": "a-strong-random-token-here"
}
}
}即使是 localhost 连接也必须配置认证。切勿在未配置认证的情况下运行 Gateway——否则机器上的任何进程都可能访问你的 AI 助手。
远程访问
WebChat 支持远程连接，无需运行单独的 Web 服务器。推荐以下两种方式：
• SSH 隧道 — 通过 SSH 转发 Gateway 端口：ssh -L 3000:localhost:3000 user@remote-host。这样你可以在本地访问 WebChat，同时 Gateway 运行在远程机器上。
• Tailscale — 通过 Tailscale 的 Mesh VPN 连接你的设备。Gateway 可通过其 Tailscale IP 地址访问，无需端口转发或防火墙配置。
对于远程连接，在 gateway.remote 设置中配置目标 WebSocket URL 和认证凭据。原生客户端会在网络状况变化时自动重连。
openclaw.json
{
"gateway": {
"remote": {
"url": "wss://your-remote-host:3000",
"token": "YOUR_REMOTE_TOKEN"
}
}
}SSH 隧道是获取远程访问最快捷的方式，无需额外软件——只需确保拥有 Gateway 主机的 SSH 访问权限。
Tailscale 提供零配置 VPN，无需端口转发即可让所有设备访问 Gateway。
会话管理
WebChat 使用 Gateway 管理的会话来维护对话上下文。每个 WebChat 连接关联一个会话，用于存储对话历史和 AI 上下文。
会话在重连后保持持久化——如果 WebSocket 断开后重新连接，对话会从断开处继续。chat.history 操作会在重连时从 Gateway 获取完整的对话记录。
会话配置通过 openclaw.json 中的 session.* 设置进行管理，包括存储后端和默认会话键。
对话历史来源于 Gateway，不在本地存储。这意味着你可以切换设备后继续同一段对话。
使用 session.defaultKey 为 WebChat 对话分配一致的会话标识符。
只读模式
当 Gateway 变得不可达时，WebChat 会自动进入只读模式。在此状态下：
• 之前的对话历史仍然可见
• 无法发送新消息
• 界面会显示断开连接状态
• 后台自动尝试重新连接
当 Gateway 恢复在线后，WebChat 会自动重连并恢复完整功能。对话历史不会丢失，因为所有历史记录都来源于 Gateway。
只读模式是一种优雅降级——在 Gateway 暂时不可用期间，用户仍然可以查看过往对话。
原生客户端功能
WebChat 在 Apple 平台上以原生 SwiftUI 应用实现：
• macOS — 完整的桌面体验，支持键盘快捷键、系统通知和菜单栏集成
• iOS — 移动端优化界面，支持推送通知和后台刷新
原生实现提供了响应迅速的平台原生体验，没有内嵌浏览器或 Electron 封装的额外开销。文本渲染、滚动和输入处理均使用原生平台组件。
其他平台（Windows、Linux、Android）可通过任何现代浏览器中的 Control UI 聊天标签页访问 WebChat。
原生 macOS/iOS 客户端提供最佳体验，具备系统通知和键盘快捷键等平台特定功能。
基于浏览器的 Control UI 聊天标签页适用于所有平台，提供相同的核心功能。
消息投递
WebChat 通过 WebSocket 连接处理消息投递，支持对长 AI 回复进行可配置的分块处理：
• textChunkLimit — 每个消息分块的最大字符数（默认：2000）。长回复会自动拆分。
• blockStreaming — 启用后，回复在生成过程中以块为单位实时发送，提供即时反馈。
消息通过 WebSocket 即时投递——没有轮询或 Webhook 延迟。双向 WebSocket 连接意味着发送和接收都是实时进行的。
openclaw.json
{
"channels": {
"webchat": {
"textChunkLimit": 2000,
"blockStreaming": true
}
}
}安全最佳实践
WebChat 的安全性建立在 Gateway 认证层之上。请遵循以下最佳实践确保部署安全：
• 始终配置认证 — 不允许匿名访问
• 使用 TLS 加密 — 所有远程连接通过 wss://（WebSocket Secure）进行
• 限制绑定地址 — 使用 gateway.bind: "127.0.0.1" 仅允许本地访问；除非使用反向代理，否则避免绑定到 0.0.0.0
• 使用强凭据 — 生成随机 token 或强密码
• 反向代理 — 生产环境部署时，将 Gateway 置于反向代理（nginx、Caddy）之后并启用 TLS 终止
如果在同一台机器上使用反向代理，请配置 gateway.trustedProxies 以确保正确检测客户端 IP。
切勿在没有 TLS 加密和强认证的情况下将 Gateway WebSocket 端口直接暴露到互联网。生产部署请使用带有 TLS 终止的反向代理。
WebChat 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| gateway.port | number | 3000 | Gateway 的 WebSocket 端口号 |
| gateway.bind | string | "127.0.0.1" | Gateway 绑定的 WebSocket 连接主机地址 |
| gateway.auth.mode | string | "token" | 认证模式：'token' 为共享密钥模式，'password' 为凭据认证模式 |
| gateway.auth.token | string | "" | 用于 WebSocket 认证的共享密钥 token |
| gateway.auth.password | string | "" | 用于 WebSocket 认证的密码 |
| gateway.remote.url | string | "" | 远程 Gateway WebSocket URL（如 wss://remote-host:3000） |
| gateway.remote.token | string | "" | 连接远程 Gateway 的认证 token |
| gateway.remote.password | string | "" | 连接远程 Gateway 的认证密码 |
| session.defaultKey | string | "" | WebChat 对话的默认会话键 |
| session.storage | string | "memory" | 会话存储后端（memory、file、redis 等） |
| textChunkLimit | number | 2000 | 每个出站消息分块的最大字符数 |
| blockStreaming | boolean | false | 在生成过程中以块为单位发送回复，提供实时反馈 |
gateway.port
Type: numberDefault: 3000
Gateway 的 WebSocket 端口号
gateway.bind
Type: stringDefault: "127.0.0.1"
Gateway 绑定的 WebSocket 连接主机地址
gateway.auth.mode
Type: stringDefault: "token"
认证模式：'token' 为共享密钥模式，'password' 为凭据认证模式
gateway.auth.token
Type: stringDefault: ""
用于 WebSocket 认证的共享密钥 token
gateway.auth.password
Type: stringDefault: ""
用于 WebSocket 认证的密码
gateway.remote.url
Type: stringDefault: ""
远程 Gateway WebSocket URL（如 wss://remote-host:3000）
gateway.remote.token
Type: stringDefault: ""
连接远程 Gateway 的认证 token
gateway.remote.password
Type: stringDefault: ""
连接远程 Gateway 的认证密码
session.defaultKey
Type: stringDefault: ""
WebChat 对话的默认会话键
session.storage
Type: stringDefault: "memory"
会话存储后端（memory、file、redis 等）
textChunkLimit
Type: numberDefault: 2000
每个出站消息分块的最大字符数
blockStreaming
Type: booleanDefault: false
在生成过程中以块为单位发送回复，提供实时反馈
WebChat 常见问题
WebChat 故障排查
WebChat 显示「已断开连接」且无法重连
Gateway 未在运行，或 WebSocket 端口被防火墙拦截。
使用 'openclaw status' 确认 Gateway 正在运行。检查配置的 gateway.port 是否被防火墙拦截。确保 gateway.bind 允许来自客户端网络地址的连接。
连接时认证失败
token 或密码与 Gateway 配置不匹配。
确认 gateway.auth.token 或 gateway.auth.password 与客户端凭据完全一致。检查是否有多余的空格或编码问题。更改认证设置后请重启 Gateway。
消息已发送但没有 AI 回复
AI Agent 未配置，或 AI 服务商 API 密钥无效。
检查 Gateway 日志中的错误信息。确认 openclaw.json 中的 Agent 配置正确。确保 AI 服务商（如 OpenAI、Anthropic）的 API 密钥有效且有可用额度。
通过 SSH 隧道远程连接失败
SSH 隧道未转发正确的端口，或 Gateway 未在预期地址上监听。
确保 SSH 命令与 Gateway 端口匹配：ssh -L 3000:localhost:3000 user@host。在远程机器上确认 Gateway 正在监听预期端口。检查 gateway.bind 是否设置为 127.0.0.1 以支持 SSH 隧道访问。
重连后对话历史为空
会话在两次连接之间过期或被清除。
检查 openclaw.json 中的会话配置设置。确保 Gateway 有足够的存储空间用于会话持久化。确认两次连接之间使用了相同的会话键。