OpenClaw WebChat 使用指南：我的实战配置与心得

今天我想和你分享一下我在使用 OpenClaw WebChat 界面时积累的一些经验和配置技巧。这个原生聊天界面用起来非常顺手，希望这份指南能帮你快速上手。

1. WebChat 简介

1.1 什么是 WebChat

在我使用 OpenClaw 的过程中，WebChat 是我最常用的界面之一。它作为 OpenClaw Gateway 的原生聊天 UI，有几个让我特别喜欢的点：

✅ 原生界面：作为一个 macOS/iOS 的 SwiftUI 应用，它的响应速度和流畅度远超嵌入式浏览器方案，用起来感觉非常“跟手”。
✅ 无需本地服务器：直接通过 WebSocket 连接 Gateway，省去了很多中间环节，配置起来简单直接。
✅ 统一会话管理：这一点很关键，它和其他通道（比如 CLI）共享相同的会话和路由规则，保证了体验的一致性。
✅ 确定性路由：消息的回复一定会返回到 WebChat，不会“迷路”，这在多任务处理时特别安心。

1.2 技术架构

理解它的架构，能帮你更好地排查问题。下面是我梳理的连接示意图：

┌─────────────────────────────────────────────────────────────┐
│                     WebChat 架构                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐      WebSocket      ┌──────────────┐     │
│  │  WebChat UI  │ ◀─────────────────▶ │   Gateway    │     │
│  │  (macOS/     │                     │   (Local/    │     │
│  │   iOS)       │                     │   Remote)    │     │
│  └──────────────┘                     └──────────────┘     │
│         │                                      │            │
│         │                                      ▼            │
│         │                             ┌──────────────┐     │
│         └────────────────────────────▶│    Agent     │     │
│                                       └──────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

简单来说，WebChat 应用就是一个“瘦客户端”，所有复杂的逻辑和状态都托管在后端的 Gateway 里。

2. 快速开始

2.1 启动步骤

刚开始用的时候可能会觉得步骤有点多，但熟悉后其实非常快。我的标准流程是这样的：

步骤 1：启动 Gateway
这是所有服务的基础。我通常直接在终端里操作：

# 启动 Gateway（默认端口）
openclaw gateway

# 如果需要指定端口（比如避免冲突），我会用这个命令
openclaw gateway --port 18789

步骤 2：打开 WebChat UI
启动 Gateway 后，就可以打开聊天界面了：
- macOS/iOS 用户：直接打开 WebChat 应用即可。
- 所有用户：也可以通过浏览器访问 Control UI 的 Chat 标签页，这是一个不错的备选方案。

步骤 3：配置认证
这一步新手容易忽略。即使是在本机（loopback）使用，Gateway 默认也是需要认证的，这是为了安全。配置一次就好：

# 添加 Gateway 认证信息
openclaw auth add

按照提示输入信息就行，系统会帮你保存好。

2.2 访问 Control UI

Control UI 是一个功能更全面的 Web 管理界面。启动 Gateway 后，在浏览器输入以下地址就能访问：

http://127.0.0.1:18791/

我经常用它来查看工具状态和做一些高级配置。

3. 工作原理

了解一些内部机制，能让你在使用时更得心应手，尤其是在遇到一些“奇怪”现象的时候。

3.1 WebSocket 连接

WebChat UI 和 Gateway 之间通过 WebSocket 进行通信，主要靠几个核心命令：

命令	说明
`chat.history`	获取聊天历史。每次打开应用或切换会话时都会调用。
`chat.send`	发送你输入的消息。
`chat.inject`	这是一个特殊命令，用于直接向对话中注入助手（Assistant）的注释。

3.2 聊天历史管理

历史记录的管理方式值得注意：
- 历史获取限制：为了性能，Gateway 会对返回的数据做处理。比如，它会截断特别长的文本字段，省略大量元数据。如果某条消息实在太大，你会在 UI 里看到 [chat.history omitted: message too large] 这样的提示，而不是卡死。
- chat.inject 行为：这个命令会直接把助手注释添加到转录中，并广播到 UI，但不会触发 agent 运行。我通常用它来手动添加一些系统提示或上下文。

3.3 中断处理

有时候我们不得不中断一个长时间运行的任务。这时，Gateway 的处理很人性化：
- 被中断的运行可以在 UI 中保留部分已经输出的助手文本。
- Gateway 会把这些被中断的文本持久化到历史记录中，并标记上 abort 元数据。这样下次查看历史时，你能知道任务是在哪里被中断的。

3.4 历史持久化

记住一个关键点：历史记录始终是从 Gateway 获取的。WebChat 应用本身不监控任何本地文件。这意味着如果 Gateway 服务不可达，WebChat 会进入只读模式，无法发送新消息。

4. Control UI 工具面板

Control UI 里的工具面板是我管理插件和功能的核心区域，它的数据来源很有意思。

4.1 工具目录

面板通过调用 tools.catalog 来获取运行时的工具目录，动态生成列表。界面大概长这样：

┌─────────────────────────────────────────┐
│  Agents Tools Panel                     │
├─────────────────────────────────────────┤
│  Tools:                                 │
│  ├── [core] file_read                   │
│  ├── [core] file_write                  │
│  ├── [plugin:bash] run_command          │
│  └── [plugin:git] git_status            │
├─────────────────────────────────────────┤
│  Profile: default                       │
│  Override: none                         │
└─────────────────────────────────────────┘

4.2 工具类型

工具分为几种类型，了解它们有助于权限管理：

类型	说明	示例
`core`	核心工具，一般是基础功能。	`file_read`, `file_write`
`plugin:<id>`	来自特定插件的工具。	`plugin:bash/run_command`
`optional`	可选插件提供的工具，需要手动启用。	一些实验性功能

4.3 回退行为

如果 tools.catalog 调用失败（比如插件服务挂了），面板不会崩溃，而是会优雅地回退到一个内置的静态工具列表，保证基本功能可用。

4.4 配置编辑

你可以在面板里直接编辑 profile（配置文件）和 override（覆盖配置），这很方便。但要注意，工具的实际运行时访问权限，最终是由一套优先级策略决定的：
1. 全局的 allow / deny 列表。
2. 每个 agent 单独的覆盖配置。
3. provider 或 channel 级别的覆盖。

5. 远程使用

这是我非常喜欢的一个功能，它让我能在任何地方连接到我实验室的机器。

5.1 远程模式

远程模式的本质是通过 SSH 或 Tailscale 这样的隧道，将 Gateway 的 WebSocket 连接安全地传输过来。

┌──────────────┐     SSH/Tailscale     ┌──────────────┐
│   WebChat    │ ◀───────────────────▶ │   Gateway    │
│   (Client)   │                       │   (Remote)   │
└──────────────┘                       └──────────────┘

5.2 配置远程连接

配置起来并不复杂，主要是在配置文件中指定远程 Gateway 的地址和认证信息：

# 配置远程 Gateway
gateway:
  remote_url: "wss://remote-host:18789"
  remote_token: "your-token"
  remote_password: "your-password"

5.3 优势

无需额外服务器：不需要在远程机器上单独为 WebChat 启一个服务，复用 Gateway 就行。
安全：连接通过加密隧道，安全性有保障。
体验一致：操作体验和本地使用几乎一模一样，没有割裂感。

6. 配置参考

这里我整理了一份自己常用的配置清单，你可以根据需要进行调整。

6.1 通道选项

首先明确一点：WebChat 没有自己独立的 webchat.* 配置块。它的所有配置都继承自 Gateway endpoint 和相关的认证设置。

6.2 全局选项

Gateway 基础配置

这是最基础的网络设置。

gateway:
  port: 18789           # WebSocket 监听的端口
  bind: "0.0.0.0"       # 绑定到所有网络接口。如果只想本地访问，可以改成 "127.0.0.1"

Gateway 认证配置

安全无小事，认证一定要配好。

gateway:
  auth:
    mode: "token"              # 认证模式，我常用 token，方便自动化
    token: "your-token"        # 你的认证 token
    password: "your-password"  # 或者使用密码认证

可信代理认证

如果你前面有 Nginx 之类的反向代理，并且由代理处理认证，可以用这个模式。

gateway:
  auth:
    mode: "trusted-proxy"  # 信任反向代理的认证（常用于浏览器客户端场景）

远程 Gateway 配置

连接他人或远程服务器 Gateway 时使用。

gateway:
  remote_url: "wss://remote-host:18789"
  remote_token: "your-remote-token"
  remote_password: "your-remote-password"

会话配置

管理聊天会话的存储方式和默认值。

session:
  # 会话存储方式，`memory` 重启丢失，`file` 会持久化
  storage: "memory"  # 或 "file"
  main_key: "default" # 默认的主会话标识

6.3 完整配置示例

下面是一个我放在 ~/.openclaw/openclaw.yaml 的配置示例，包含了常用部分：

# ~/.openclaw/openclaw.yaml

# Gateway 配置
gateway:
  port: 18789
  bind: "127.0.0.1"
  auth:
    mode: "token"
    token: "your-gateway-token"

# 会话配置
session:
  storage: "memory"
  main_key: "default"

# Agent 配置
agents:
  default:
    models:
      - id: qwen-portal/coder-model

7. 常见问题

这里列出的都是我在使用过程中真实遇到过的问题和解决方法。

Q1: WebChat 无法连接到 Gateway

可能原因：
- Gateway 服务根本没启动。
- WebChat 里配置的端口和 Gateway 启动的端口对不上。
- 认证信息（token/password）填错了。

我的解决方法：

# 首先，检查 Gateway 是否在指定端口上正常运行
openclaw gateway --port 18789

# 然后，验证一下认证配置是否正确
openclaw models status

Q2: 如何查看聊天历史？

聊天历史是通过 chat.history 命令从 Gateway 实时获取的。你不需要手动操作，在 WebChat UI 中切换会话或重新打开应用时，历史记录会自动加载并显示。

Q3: 消息过大怎么办？

别担心，系统有保护机制。Gateway 会自动截断超大的消息，并在 UI 中显示 [chat.history omitted: message too large] 的提示，而不会导致服务崩溃或客户端卡死。

Q4: 如何配置远程访问？

有两种主流方法，我根据网络环境选择：

# 方法一：使用 SSH 端口转发（最通用）
ssh -L 18789:localhost:18789 user@remote-host

# 方法二：如果双方都安装了 Tailscale（最方便）
tailscale up

之后在 WebChat 配置中，将 gateway.remote_url 指向 remote-host 即可。

Q5: 工具面板不显示工具？

可能原因：
- tools.catalog 服务暂时不可用。
- 提供工具的插件没有被启用。

我的排查步骤：

# 先看看有哪些插件，以及它们的状态
openclaw plugins list

# 如果发现需要的插件是 disabled 状态，启用它
openclaw plugins enable <plugin-id>

Q6: 如何禁用 Gateway 认证？

强烈不建议在生产环境或可被外部访问的环境下这么做！ 如果只是在绝对安全的本地测试环境想图个方便，可以配置：

gateway:
  auth:
    mode: "none"  # 警告：仅限封闭的测试环境！

Q7: WebChat 与 Control UI 有什么区别？

刚开始我也分不清，用久了就明白了。它们定位不同：

特性	WebChat	Control UI
界面类型	原生 SwiftUI 应用	基于 Web 的界面
主要平台	macOS/iOS（体验最佳）	全平台（有浏览器就行）
核心功能	专注于聊天	聊天 + 工具面板 + 系统配置

简单说，WebChat 是“专业聊天客户端”，Control UI 是“全能管理后台”。

附录：快捷键速查

记住这几个快捷键能极大提升效率，尤其是 Cmd/Ctrl + Enter 发送消息，用惯了离不开。

快捷键	功能
`Cmd/Ctrl + N`	新建一个会话
`Cmd/Ctrl + Enter`	发送当前输入的消息
`Esc`	取消操作或关闭弹出的面板

你可能感兴趣的文章

来源：每日教程， 每日一例，深入学习实用技术教程，关注公众号TeachCourse
转载请注明出处： https://teachcourse.cn/3893.html ，谢谢支持！

资源分享

分类：DevOps 标签：Control UI, Gateway, iOS, macOS, OpenClaw, SwiftUI, WebChat, WebSocket, 会话管理, 远程访问