基于Tailscale Funnel与WebSocket构建一体化AI助手与远程桌面Web门户

1. 项目概述：一个浏览器内的AI助手与远程桌面中心

如果你和我一样，日常重度依赖像OpenClaw这样的本地AI助手，同时又经常需要在不同设备间查看Mac的屏幕，那你肯定也烦透了在聊天应用、远程桌面软件和浏览器标签页之间反复横跳。这种割裂的体验不仅效率低下，还容易打断工作流。我一直在寻找一个能把这两件事合二为一的解决方案：在一个统一的Web界面里，既能和我的AI助手流畅对话，又能随时瞥一眼家里或办公室Mac的桌面状态，比如看看一个长时间运行的编译任务进度，或者临时从手机端操作电脑发个文件。

这就是我动手构建ClawConnect的初衷。它本质上是一个高级的Web前端，核心目标是把与OpenClaw的对话和远程查看/控制Mac屏幕这两大功能，无缝集成到一个浏览器页面中。你不再需要单独打开OpenClaw的客户端，也不需要启动TeamViewer、VNC Viewer之类的远程桌面工具。一切操作，从提问AI到远程点击，都在一个标签页内完成。这对于需要频繁在移动设备和电脑间切换，或者希望将AI助手能力“门户化”提供给内网其他设备的场景来说，尤其方便。

整个项目的技术栈非常“现代Web”且注重实效：前端使用Angular 21构建，享受响应式信号和独立组件的开发体验；远程桌面部分则基于久经考验的noVNC库，通过一个轻量级的Node.js WebSocket代理桥接Mac原生的VNC服务；而让这一切能从公网安全访问的关键，则交给了Tailscale的Funnel功能。下面，我就带你从设计思路到实操细节，完整拆解这个项目。

2. 核心架构与设计思路拆解

2.1 为什么选择这样的架构？

ClawConnect的架构可以用一句话概括：“静态前端 + 动态WebSocket + 安全隧道”。这个选择背后是几个非常实际的考量：

首先，为什么是纯静态前端？项目的前端（Angular应用）在构建后是一堆HTML、CSS、JS文件。这意味着你可以把它部署到任何静态托管服务上，比如GitHub Pages、Vercel、Netlify，甚至是公司内网的一台Nginx服务器。部署成本极低，无需关心后端运行环境。我选择将其托管在claw.publichome.page，就是为了提供一个开箱即用的入口，但你也完全可以下载代码，构建后放到自己的域名下，实现完全的自托管。

其次，通信层为什么全部基于WebSocket？这主要是为了满足实时性的需求。与OpenClaw的对话（Chat）需要双向、低延迟的通信来支持流式响应；远程桌面（Screen Share）的VNC协议本身也是基于帧的实时数据传输，通过WebSocket代理后能在浏览器中完美运行。因此，前端通过两个独立的WebSocket连接分别对接AI网关和VNC代理服务。

最关键的，网络暴露问题如何解决？这是此类自托管工具最大的痛点。传统的方案可能需要你拥有公网IP、配置复杂的路由器端口转发、申请SSL证书等。ClawConnect巧妙地利用了Tailscale Funnel。Tailscale本身能为你建立一个加密的虚拟局域网（Tailnet），而Funnel功能允许你将Tailnet内的特定服务安全地暴露到公共互联网，并自动提供HTTPS支持。这意味着，你不需要动家里的路由器，也不需要自己搞域名和证书，就能获得一个可以通过公网访问的、加密的端点。安全性由Tailscale保障，便捷性达到了极致。

2.2 核心数据流与组件职责

理解数据流有助于后续的调试和问题排查。整个系统的数据流向如下：

1. 用户打开浏览器，访问ClawConnect前端页面。
2. 前端初始化：页面加载后，会根据用户设置（或默认值）尝试建立两个WebSocket连接。
3. AI聊天通道：
   • 前端WebSocket客户端 -> (通过公网) ->Tailscale Funnel (端口8443)-> (通过Tailnet) ->本地Mac上的OpenClaw Gateway (端口18789)。
   • 用户的提问消息通过这个链路发送给OpenClaw，OpenClaw的流式回复再通过原路返回，实时显示在聊天界面。
4. 远程桌面通道：
   • 前端noVNC客户端 -> (通过公网) ->Tailscale Funnel (端口443)-> (通过Tailnet) ->本地Mac上的Node.js WebSocket代理 (端口6080)->Mac系统原生VNC服务 (端口5900)。
   • 前端的鼠标键盘事件通过这个链路发送给VNC服务，而Mac的屏幕帧则反向传输，在浏览器中渲染出来。

各核心组件的职责：

• Angular前端：提供用户界面，管理聊天会话和远程桌面画布，处理与后端服务的WebSocket通信。
• OpenClaw Gateway：这是OpenClaw自带的HTTP/WebSocket网关服务，负责处理与AI模型的对话协议。ClawConnect直接与之通信。
• Node.js WebSocket代理 (ws-proxy.js)：这是一个轻量级桥接服务。因为浏览器中的noVNC库使用WebSocket协议，而Mac的VNC服务使用原始的TCP协议。这个代理的作用就是在WebSocket和TCP之间进行转换。
• Tailscale Funnel：作为安全的反向代理和入口网关，它处理了TLS终止、身份验证（基于Tailscale设备认证）和流量转发，是内网服务能够安全公网访问的基石。

注意：这里存在一个常见的理解误区。tailscale funnel命令暴露的是你本地Mac上的服务端口（如18789, 6080），而不是Tailscale节点本身。Funnel扮演了一个“智能网关”的角色，外部流量先到达Tailscale的基础设施，经过认证和加密后，再通过已建立的Tailnet隧道转发到你指定的本地端口。

3. 环境准备与“魔法安装”解析

为了让体验尽可能平滑，我提供了“魔法安装”脚本。但知其然更要知其所以然，了解脚本做了什么，才能在出问题时自己动手排查。

3.1 macOS 环境深度配置

运行install.sh脚本，它会自动化完成以下关键步骤，我们逐一拆解其原理：

1. 基础环境检查与安装：脚本首先会检查是否安装了Homebrew（macOS包管理器），如果没有则进行安装。随后，通过Homebrew安装Node.js和Tailscale。Node.js是运行WebSocket代理和前端构建工具链的必需品；Tailscale则是建立安全隧道的核心。

2. 安装与配置OpenClaw：脚本会通过pip安装或升级OpenClaw。安装后，它会检查OpenClaw的配置文件（通常位于~/.openclaw/openclaw.json），并确保其中的gateway配置部分启用了WebSocket服务，且监听在正确的地址（0.0.0.0:18789）上。这一步至关重要，它保证了OpenClaw Gateway能够接受来自本机其他服务（乃至通过Tailscale隧道而来的）的连接。

3. 启动并配置Tailscale：如果Tailscale未登录，脚本会引导你打开浏览器进行登录认证，确保你的设备加入到你的Tailnet中。接着，它会启用Tailscale的Funnel功能。Funnel并非默认开启，需要显式启用。脚本会执行tailscale funnel 8443和tailscale funnel 443，这实际上是告诉Tailscale：“请将发往本设备Tailnet域名上8443和443端口的公共流量，分别转发到我本地的18789和6080端口。”

4. 配置系统级VNC访问：为了让noVNC能连接，需要开启macOS系统自带的屏幕共享，并启用VNC协议。脚本中对应的kickstart命令是一系列Apple Remote Desktop配置工具的封装，它激活了ARDagent，并授予VNC客户端所有控制权限（-privs -all），同时设置了使用系统密码进行验证。执行后，你可以在“系统设置”->“通用”->“共享”中看到“屏幕共享”已被勾选。

5. 启动后台服务：最后，脚本以后台服务的形式启动两个核心进程：

   • openclaw gateway：启动OpenClaw网关。
   • node onboard.js --proxy：启动一个集成管理进程，它内部会运行WebSocket代理(ws-proxy.js)，并处理一些健康检查逻辑。

实操心得：在macOS 26 (Sequoia) 及以后版本中，VNC服务（端口5900）采用了socket-activation机制。这意味着你在没有客户端连接时，用lsof -i:5900或netstat -an | grep 5900可能看不到监听进程。这很正常，系统会在连接到来时才动态启动服务。验证VNC是否就绪的正确方法是使用nc命令尝试连接，如echo "" | nc -w 2 localhost 5900 | head -c 12，如果返回RFB 003.889（RFB是VNC协议名），即表示服务正常。

3.2 Windows 环境适配要点

Windows版的install.ps1PowerShell脚本逻辑与macOS类似，但实现细节有差异：

1. 包管理：Windows上使用winget或choco来安装Node.js和Tailscale客户端。
2. OpenClaw安装：通过pip安装OpenClaw，但Windows上OpenClaw Gateway的配置文件和启动方式可能与macOS略有不同，脚本需要做相应适配。
3. 服务管理：Windows上通常将后台进程注册为系统服务，以获得更好的开机自启和进程管理体验。脚本可能会使用nssm（Non-Sucking Service Manager）或PowerShell脚本来创建服务。
4. VNC服务：Windows本身没有原生的系统级VNC服务器。因此，ClawConnect在Windows上的“屏幕共享”功能，需要依赖一个第三方VNC服务器软件，例如TightVNC或UltraVNC。脚本可能需要引导用户安装并配置其中一款，并将其服务端口（默认为5900）代理出来。这是与macOS方案最大的不同点。

重要提示：由于Windows生态的多样性，Windows版的“魔法安装”可能无法覆盖所有情况，特别是不同VNC服务器的配置。如果脚本运行后屏幕共享失败，你可能需要手动检查并配置你所选的VNC服务器，确保其允许本地回环地址（127.0.0.1）连接，并且认证方式正确。

4. 手动安装与配置全流程

如果你不想运行一键脚本，或者想更精细地控制每个环节，以下是完整的手动配置步骤。这能帮你更深入地理解系统是如何串联起来的。

4.1 前置条件检查清单

在开始之前，请确保你的Mac上已准备好以下条件：

4.2 逐步配置指南

第一步：获取项目代码并安装依赖

# 克隆仓库 git clone https://github.com/publichomepage/claw-connect.git cd claw-connect # 安装项目依赖（主要是Angular开发依赖和构建工具） npm install

第二步：运行自动配置脚本这是手动流程中唯一“自动化”的步骤，它帮你生成必要的配置。

npm run setup

这个命令会做三件事：

1. 生成OpenClaw Gateway访问令牌：它会与本地运行的OpenClaw Gateway交互，创建一个用于WebSocket连接的身份验证令牌。
2. 配置CORS：它会修改OpenClaw的网关配置，允许来自ClawConnect前端域名（如claw.publichome.page或你自定义的部署域名）的跨域请求。这是浏览器安全策略所必需的。
3. 输出关键信息：执行完成后，控制台会打印出生成的Auth Token。请务必保存好这个令牌，它是前端连接聊天网关的密码。

第三步：启动OpenClaw Gateway确保OpenClaw的聊天网关服务正在运行。

# 启动网关服务（如果尚未运行） openclaw gateway start # 验证服务状态 openclaw gateway status

你应该看到服务状态为“running”，并且监听在0.0.0.0:18789地址上。

第四步：配置并启动Tailscale Funnel这是实现公网访问的关键。你需要为两个服务分别创建Funnel。

# 1. 为OpenClaw Gateway (聊天服务) 创建Funnel，将公网8443端口映射到本地18789端口 tailscale funnel --bg --https=8443 http://localhost:18789 # 2. 为屏幕共享代理创建Funnel。注意，这里映射的是稍后启动的代理端口（默认6080）。 # 我们使用443端口，因为这是标准HTTPS端口，兼容性最好。 tailscale funnel --bg --https=443 http://localhost:6080

--bg参数让命令在后台运行。--https=8443指定了公网访问的HTTPS端口。执行后，Tailscale会为你生成一个唯一的子域名，格式通常为your-machine-name.your-tailnet-name.ts.net。

使用以下命令检查Funnel状态：

tailscale funnel status

你会看到类似下面的输出，确认两个端点都已激活：

# Funnel on: # https://your-mac.tailnet.ts.net:8443 -> http://127.0.0.1:18789 # https://your-mac.tailnet.ts.net:443 -> http://127.0.0.1:6080

第五步：启动屏幕共享WebSocket代理ClawConnect项目包含一个ws-proxy.js脚本，用于桥接WebSocket和VNC的TCP连接。在项目根目录下启动它：

# 直接启动代理，将WebSocket的6080端口转发到VNC的5900端口 node ws-proxy.js 6080 localhost:5900

为了让它能在后台持续运行，你可以使用&符号，或者更好的方式是使用pm2、forever等进程管理工具。

# 使用nohup和&在后台运行 nohup node ws-proxy.js 6080 localhost:5900 > proxy.log 2>&1 &

第六步：启用macOS屏幕共享与VNC如果之前没有运行过魔法脚本，你需要手动开启系统级的VNC访问。

1. 打开“系统设置” -> “通用” -> “共享”。
2. 勾选“屏幕共享”复选框。
3. 点击右侧的“信息”(i)按钮，确保“使用Apple ID或本地用户密码登录”选项已勾选。
4. 在终端执行以下命令，启用完整的VNC控制权限（只需执行一次）：

   sudo /System/Library/CoreServices/RemoteManagement/ARDAgent.app/Contents/Resources/kickstart \ -activate -configure -access -on -privs -all -restart -agent -menu

   输入你的系统管理员密码。这个命令会重启远程管理服务，使VNC配置生效。

5. 前端配置与连接实战

环境和服务都就绪后，现在可以启动前端并建立连接了。

5.1 开发环境运行与构建

项目使用Angular框架，提供了标准的开发脚本。

# 在本地启动开发服务器，通常访问 http://localhost:4200 npm start # 构建用于生产环境的静态文件，输出到 `dist/ClawConnect/browser/` 目录 npm run build

在开发模式下，你可以修改代码并实时看到变化。但需要注意的是，开发服务器运行在localhost，如果你要从同一网络下的其他设备（如手机或平板）访问，需要将npm start命令改为监听所有网络接口：npm start -- --host 0.0.0.0。不过，更常见的做法是直接构建生产版本，然后部署到静态服务器。

5.2 连接参数详解与界面配置

无论你是使用我提供的在线版本(claw.publichome.page)，还是部署了自己的版本，首次打开页面都需要进行配置。

1. 聊天连接配置：在设置面板中，找到“Chat Connection”部分，需要填写三个关键信息：

• Gateway Host：你的Tailscale Funnel域名。即tailscale funnel status命令输出中your-mac.tailnet.ts.net部分。注意：这里不要带https://前缀。
• Gateway Port：填写8443。这是你在创建Funnel时指定的公网端口。
• Auth Token：填写运行npm run setup时控制台打印出的那一长串令牌字符串。

2. 屏幕共享连接配置：在“Screen Share”部分，同样需要填写信息：

• Tailscale Domain：与上面相同，填写your-mac.tailnet.ts.net（不带协议和端口）。
• WebSocket Port：填写443。这是VNC代理服务对应的公网HTTPS端口。
• System Username/Password：这里需要填写你登录Mac系统时使用的用户名和密码。这是VNC协议级别的认证，用于连接macOS原生的屏幕共享服务。请注意，这不是Tailscale的账号密码。

填写完毕后，点击“Save & Connect”。如果一切配置正确，你应该能看到左侧的聊天面板状态变为“Connected”，并且可以开始向OpenClaw提问；右侧的屏幕共享面板在经过短暂连接后，会显示出你Mac的实时桌面。

界面操作提示：在屏幕共享视图内，你可以像操作本地机器一样使用鼠标和键盘。noVNC工具栏提供了缩放、全屏、发送特定快捷键（如Command、Control）等功能。如果遇到键盘映射问题，可以尝试在工具栏的“Settings”中切换不同的键盘类型。

6. 故障排查与常见问题实录

在实际部署和使用过程中，你可能会遇到一些问题。下面是我在开发和测试中遇到的一些典型情况及其解决方法。

6.1 聊天功能连接失败

6.2 屏幕共享功能异常

6.3 Tailscale Funnel 相关问题

7. 项目结构与定制化开发

如果你对代码感兴趣，或者想进行二次开发，了解项目结构会很有帮助。

7.1 核心目录与文件解析

claw-connect/ ├── src/ # Angular应用源代码 │ ├── app/ │ │ ├── components/ # 可复用的UI组件 │ │ │ ├── chat/ # 主聊天面板布局组件 │ │ │ ├── message/ # 单条消息的渲染组件 │ │ │ ├── screen-share/ # 集成noVNC的远程桌面组件 │ │ │ └── settings/ # 连接设置面板组件 │ │ └── services/ # 数据层服务 │ │ ├── openclaw.service.ts # 封装与OpenClaw Gateway的WebSocket通信 │ │ └── screen-share.service.ts # 管理noVNC实例的生命周期和状态 │ └── styles.css # 全局样式 ├── public/novnc/ # noVNC库的ESM版本源码 (v1.5.0) ├── ws-proxy.js # WebSocket转TCP代理服务器（核心桥梁） ├── onboard.js # 简化启动脚本，用于一键启动代理和管理 ├── setup.js # 自动配置脚本（生成Token、配置CORS） ├── install.sh / install.ps1 # 全平台一键安装脚本 └── angular.json, package.json等 # 项目构建和依赖管理配置

• src/app/services/openclaw.service.ts：这是与AI聊天的核心。它使用RxJS库管理WebSocket连接，处理消息的发送、接收（包括流式响应）、重连逻辑和错误处理。如果你想修改聊天协议或增加功能（如对话历史管理），这里是重点。
• src/app/services/screen-share.service.ts：负责加载noVNC库、初始化RFB（远程帧缓冲）客户端、处理VNC连接事件（如密码请求、桌面大小改变）和销毁清理。如果你想调整noVNC的UI或交互，可以在这里修改传递给noVNC的选项。
• ws-proxy.js：一个非常简洁但关键的Node.js脚本。它使用ws库创建WebSocket服务器，并与本地的TCP端口（5900）建立连接，在两种协议间转发数据。如果你需要增加日志、流量监控或加密层，可以修改此文件。
• public/novnc/：包含了noVNC的客户端库。noVNC是一个纯HTML5的VNC客户端，我们直接使用其编译后的ES模块版本，通过screen-share.service.ts动态加载。

7.2 如何进行定制化修改

1. 修改前端样式与布局：所有UI组件位于src/app/components/。Angular 21使用独立组件和信号(Signals)。你可以直接修改对应组件的HTML模板和CSS样式来改变界面外观和布局。例如，觉得聊天窗口太窄，可以去chat.component.html里调整布局容器的宽度比例。

2. 更换远程桌面核心库：目前使用noVNC。如果你想替换成其他Web VNC库（如@novnc/novnc的最新npm包版本），需要：

• 在package.json中添加新依赖。
• 修改screen-share.service.ts，调整初始化逻辑以适应新库的API。
• 可能还需要调整Angular的构建配置。

3. 适配其他AI助手后端：ClawConnect目前与OpenClaw的Gateway Protocol v3深度耦合。如果你想对接其他兼容OpenAI API格式的本地模型服务（如Ollama、LM Studio），需要：

• 修改openclaw.service.ts中的WebSocket连接URL和消息格式。
• 很可能需要调整消息发送和接收的解析逻辑，因为不同服务返回的流式数据格式可能有细微差别。

4. 增强安全性：当前方案依赖Tailscale Funnel提供传输层安全。如果你在内网使用，或者想增加应用层认证：

• 可以在ws-proxy.js前端增加简单的Token验证。
• 可以修改前端，在连接WebSocket时携带额外的认证头或查询参数。
• 注意：这需要同时修改代理服务器和前端代码。

8. 部署指南与生产环境考量

开发测试完成后，你可能希望将ClawConnect部署到一个更稳定、可公开访问的环境。

8.1 静态资源构建与部署

部署前端部分非常简单，因为它只是静态文件。

# 在项目根目录执行生产构建 npm run build # 构建完成后，产物位于 `dist/ClawConnect/browser/` 目录下 # 你可以将这个目录下的所有文件上传到任何静态托管服务

例如：

• GitHub Pages: 将dist/ClawConnect/browser/目录的内容推送到gh-pages分支，或配置Actions自动部署。
• Vercel/Netlify: 将这些文件拖入其部署界面，或连接Git仓库自动部署。
• 自有服务器: 使用Nginx或Apache配置一个虚拟主机，将根目录指向这个browser文件夹。

部署后重要步骤：部署到新域名后，必须重新运行npm run setup，并将你的新域名添加到OpenClaw Gateway的CORS允许列表中。因为浏览器会阻止来自不同域的前端访问本地网关。你可以手动执行：openclaw gateway cors add https://你的新域名.com。

8.2 后台服务的持久化运行

对于Mac本地的OpenClaw Gateway和WebSocket代理服务，你需要确保它们能长期稳定运行，并在系统重启后自动启动。

方案一：使用launchd(macOS 原生)这是最系统的方式。为openclaw gateway和node ws-proxy.js分别创建.plist文件，放在~/Library/LaunchAgents/目录下。

<!-- 例如：com.user.openclaw-gateway.plist --> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.user.openclaw-gateway</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/openclaw</string> <string>gateway</string> <string>start</string> </array> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>StandardOutPath</key> <string>/tmp/openclaw-gateway.log</string> <key>StandardErrorPath</key> <string>/tmp/openclaw-gateway.err</string> </dict> </plist>

加载服务：launchctl load ~/Library/LaunchAgents/com.user.openclaw-gateway.plist

方案二：使用pm2(进程管理工具)对于Node.js进程管理更友好。

# 全局安装pm2 npm install -g pm2 # 启动并管理OpenClaw Gateway (假设它提供了CLI) pm2 start "openclaw gateway start" --name openclaw-gateway # 启动WebSocket代理 pm2 start ws-proxy.js --name vnc-proxy -- 6080 localhost:5900 # 设置开机自启 pm2 save pm2 startup

8.3 安全强化建议

对于生产环境，除了依赖Tailscale，还可以考虑以下措施：

1. 限制Funnel访问：Tailscale Funnel可以设置访问控制列表，限制只有特定Tailscale用户或群组可以访问暴露的服务。在Tailscale管理后台进行配置。
2. 使用自定义域名与HTTPS：虽然Funnel提供了ts.net子域名和HTTPS，但你也可以将自己的域名通过CNAME记录指向Funnel地址，并在前端使用自定义域名。
3. 前端增加访问密码：可以在前端页面入口增加一个简单的静态密码验证（通过JavaScript），虽然不能防止技术用户绕过，但可以增加一道简单的屏障。
4. 定期轮换Token：定期重新运行npm run setup生成新的OpenClaw Gateway Token，并更新前端配置。
5. 监控与日志：确保launchd或pm2的日志输出路径正确，定期检查日志，监控服务的运行状态和错误信息。

通过以上步骤，你应该能够成功部署并运行一个属于你自己的、功能完整的ClawConnect实例。它将作为一个统一的Web门户，让你随时随地与你的AI助手交流，并掌控你的远程桌面。