1. 项目概述为你的AI助手打造一个专属的“家”如果你和我一样对AI Agent智能体的潜力感到兴奋但又对把对话数据完全交给第三方平台心存疑虑那么这个项目可能就是你在找的答案。我最近在折腾一个叫OpenClaw的AI助手它很强大能连接我的WhatsApp、Notion、Apple Notes等一堆应用帮我处理信息。但问题来了它的主要交互界面是WhatsApp或Telegram。用了一段时间我发现了几个痛点消息格式支持太弱不支持Markdown和代码高亮、所有对话都要经过Meta或Telegram的服务器、我根本看不清我的AI助手到底有哪些“技能”可用。这感觉就像买了一台顶配电脑却只能用最原始的DOS命令行来操作憋屈。于是我动手搭建了OpenClaw Web Interface。简单说这是一个完全自托管、运行在你本机或自己服务器上的网页聊天界面。它通过WebSocket直接连接到你本地的OpenClaw网关所有数据流都在你的掌控之中没有任何第三方介入。界面干净漂亮支持完整的Markdown渲染、代码高亮、实时流式响应还能在一个侧边栏里清晰地展示AI助手所有已连接的工具和技能。对于学生党来说这本身就是一个非常棒的毕业设计Final Year Project选题涵盖了现代Web开发Next.js, TypeScript、实时通信WebSocket、AI应用集成和隐私安全等多个热门方向。对于开发者或隐私爱好者它则提供了一个将AI能力私有化、可视化的完美方案。接下来我就带你从零开始把这个“家”给建起来并分享一些我踩过坑才总结出的实操细节。2. 核心架构与工具选型解析2.1 为什么选择这样的技术栈这个项目的技术选型非常“现代”且务实每一项选择背后都有明确的考量不是为了追新而追新。Next.js 15 TypeScript构建坚如磐石的前端基石我选择Next.js 15作为框架核心原因在于它对React应用开发体验的革命性提升尤其是其App Router和服务端组件Server Components。对于这样一个以实时聊天为核心的应用首屏加载速度和初始状态的稳定性至关重要。利用服务端组件我可以在服务器端就渲染出聊天界面的静态骨架和技能侧边栏用户打开页面瞬间就能看到内容而不是一个空白的加载动画。TypeScript的加入则是为了项目的长期可维护性。AI Agent的响应数据结构可能比较复杂TypeScript的强类型检查能在开发阶段就规避大量潜在的类型错误让对接OpenClaw网关API的过程更加顺畅这对学生项目减少调试时间尤其有帮助。Tailwind CSS 4极致高效与一致性的样式方案在UI快速迭代的阶段传统的CSS或CSS-in-JS方案常常让我在样式命名和文件切换中耗费精力。Tailwind CSS的实用类Utility-First理念完美解决了这个问题。我几乎不需要离开HTML/JSX文件就能完成所有样式的编写。最新版本Tailwind CSS 4在性能和开发体验上更进一步其Just-in-Time引擎确保最终打包的CSS文件只包含我实际用到的类体积非常小。对于需要兼顾美观与性能的自托管应用这一点至关重要。深色/浅色主题的切换功能利用Tailwind的dark:变体可以轻松实现无需复杂的主题上下文管理。WebSocket实时双向通信的生命线这是整个应用与OpenClaw网关对话的“大动脉”。为什么不使用更常见的HTTP轮询或Server-Sent Events因为AI思考与响应的过程是连续的、流式的。HTTP轮询会有延迟和冗余请求SSE只能是服务器向客户端的单向流。而WebSocket提供了全双工、低延迟的通信通道。当用户在界面发送消息时前端通过WebSocket将指令实时推送给网关网关处理AI请求时可以逐词token-by-token地将思考流推回前端实现那种“AI正在输入”的实时效果。这种体验是传统请求-响应模式无法比拟的。React Markdown 语法高亮提升信息密度的关键一个合格的AI助手界面必须能漂亮地展示AI的“思考”结果。AI经常返回代码片段、列表、表格等结构化信息。React Markdown库允许我将AI返回的Markdown字符串安全地渲染为React组件。搭配rehype-highlight这类插件可以为代码块自动添加语法高亮区分不同编程语言让技术讨论和代码审查变得一目了然。这不仅仅是美观问题更是提升了信息传递的效率和准确性。2.2 隐私与安全的设计哲学这个项目在安全设计上采取了“极简主义”但非常有效。核心原则不持有任何秘密。整个前端项目代码库中你不应该找到任何API密钥、令牌或数据库密码。去中心化的鉴权你的OpenClaw访问令牌Token是在运行时通过浏览器界面手动输入的。这个令牌只会保存在浏览器的内存或本地存储LocalStorage中用于建立WebSocket连接时的鉴权。它永远不会被发送到本项目的前端服务器开发服务器或生产构建服务器。这意味着即使有人拿到了这个Web界面的全部源代码他们也拿不到你的OpenClaw令牌。本地通信闭环在标准本地部署下数据流是浏览器 - 本机Web界面服务 - 本机OpenClaw网关。所有数据包都在你的物理机器内部循环没有一寸数据需要经过互联网。这是最高级别的隐私保障。VPS部署的SSH隧道策略当你想把OpenClaw网关和Web界面都放在云服务器VPS上然后从外部访问时项目推荐使用SSH隧道。这同样避免了在VPS防火墙上公开暴露OpenClaw网关的WebSocket端口默认18789所有流量都通过加密的SSH连接传输安全性堪比本地网络。3. 从零开始的详细部署指南3.1 本地开发环境搭建一步一坑详解假设你是在一台干净的电脑上开始我们从头走一遍。第一步夯实基础——Node.js与OpenClaw安装首先确保你的Node.js版本在18或以上。我推荐使用nvmNode Version Manager来管理Node版本这样可以轻松切换。安装OpenClaw时官方命令是npm install -g openclaw。这里有个常见坑点在某些系统如某些Linux发行版或配置了严格权限的macOS上全局安装可能需要sudo权限。但使用sudo安装npm包有时会导致后续权限问题。我的建议是优先检查你的npm全局安装路径是否在用户目录下例如~/.npm-global并正确配置了PATH。如果必须用sudo安装后可以检查一下openclaw命令的所属用户和组确保你的普通用户有执行权限。第二步启动OpenClaw网关——不仅仅是运行命令执行openclaw gateway install和openclaw gateway start后别急着下一步。务必运行openclaw status进行验证。 你期望看到的输出应该类似Gateway: reachable WhatsApp: OK (or connecting/disconnected) ...其他通道状态如果Gateway显示unreachable问题通常出在端口冲突默认的18789端口被其他程序占用。你可以通过openclaw gateway config查看或修改端口配置。网关进程未成功启动检查系统日志如journalctl -u openclaw如果配置了服务或尝试重启网关。实操心得在首次启动网关后最好等待一两分钟再检查状态。因为网关可能需要初始化内部模块或建立外部连接如WhatsApp Web扫描二维码初始状态可能不稳定。第三步克隆与启动Web界面——注意依赖一致性克隆项目后进入目录运行npm install。这里可能遇到的典型问题是依赖版本冲突尤其是如果你本地Node版本较高而项目package.json中某些依赖有版本限制。如果安装失败或出现警告可以尝试rm -rf node_modules package-lock.json然后重新npm install。或者使用npm ci命令它会根据package-lock.json精确安装依赖确保环境一致。 启动开发服务器npm run dev后打开浏览器访问http://localhost:3000。如果页面空白或报错打开浏览器开发者工具F12的“控制台(Console)”和“网络(Network)”标签查看具体错误信息。常见问题可能是本地网关未运行或者Next.js开发服务器因端口3000被占用而启动失败。3.2 生产环境部署与VPS远程访问方案当你希望在云服务器上长期运行并可能从不同设备访问时就需要部署到生产环境。构建生产版本在项目根目录下运行npm run build这个命令会启动Next.js的构建过程进行代码优化、压缩并生成一个独立的、高性能的生产版本。构建完成后你可以使用以下命令启动生产服务器npm start生产服务器默认也会监听3000端口但它的性能和处理静态资源的方式与开发服务器npm run dev有本质区别。VPS部署与SSH隧道详解官方文档简单提到了SSH隧道但这里有几个关键细节在VPS上你需要像在本地一样安装Node.js、OpenClaw并启动OpenClaw网关。同时将本Web界面项目代码也上传到VPS构建并运行生产服务器假设运行在VPS的3000端口。建立两条SSH隧道隧道一用于Web界面将VPS上的Web界面服务映射到你本地。ssh -L 3000:localhost:3000 useryour-vps-ip这样你在本地浏览器访问http://localhost:3000流量就会通过SSH加密隧道转发到VPS的3000端口。隧道二用于OpenClaw网关将VPS上的OpenClaw网关WebSocket端口也映射到本地。# 在另一个终端窗口执行 ssh -L 18789:localhost:18789 useryour-vps-ip在Web界面中配置连接此时在浏览器打开的Web界面里网关URL仍然填写ws://127.0.0.1:18789。因为通过第二条隧道本地的18789端口已经指向了VPS上的网关服务。重要提示这种方式下你的浏览器直接连接的是你本机映射的端口数据流路径是浏览器 - 本地端口 - SSH加密隧道 - VPS服务。VPS上的网关和Web服务都不需要对外公开端口极大增强了安全性。缺点是每次访问都需要先建立SSH连接。更进阶的部署方式对于希望24小时可访问且不想手动维护SSH隧道的用户可以考虑使用Docker Compose将OpenClaw网关和这个Web界面打包成容器通过一个docker-compose.yml文件定义网络和依赖一键启动。配置反向代理如Nginx/Caddy在VPS上通过Nginx将域名如chat.yourdomain.com的HTTPS流量代理到本地的3000端口Web界面和18789端口WebSocket网关。这需要非常小心地配置WebSocket代理proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;并且务必为你的域名配置SSL证书如使用Let‘s Encrypt确保通信全程加密。4. 核心功能使用与界面详解4.1 首次连接与配置打开Web界面你会看到一个简洁的连接配置表单。这里有两个关键字段字段值说明与注意事项Gateway URLws://127.0.0.1:18789这是OpenClaw网关默认的WebSocket地址。如果你修改了网关的监听端口或主机需要相应调整。协议必须是ws://非加密或wss://加密。本地环境通常用ws。Token位于~/.openclaw/openclaw.json这是网关的认证令牌。获取方式在终端执行 cat ~/.openclaw/openclaw.json点击连接后留意浏览器开发者工具中的“网络(Network)”选项卡筛选WSWebSocket你应该能看到一个状态码为101 Switching Protocols的连接这表示WebSocket握手成功。如果连接失败控制台会打印错误信息常见的有连接被拒绝网关未运行或无效令牌。4.2 技能侧边栏你的AI能力地图连接成功后界面左侧或可通过按钮展开的技能侧边栏是整个项目的亮点之一。它会动态地从网关获取你的OpenClaw实例已加载的所有“技能”Skills或“工具”Tools。这是什么每个技能对应一个OpenClaw能执行的具体操作例如“搜索网络”、“读取Notion页面”、“发送邮件”、“查询天气”等。侧边栏以清晰的列表或卡片形式展示它们通常包括技能名称和简短描述。为什么重要可发现性你无需记忆复杂的指令或技能名称。一眼扫过去你就知道你的AI助手“会做什么”从而能更有效地向它发出指令。比如你看到有“SummarizeWebpage”这个技能就可以直接说“帮我总结一下这个网页的内容”。调试与验证当你安装或配置了一个新技能后可以立刻在侧边栏看到它是否成功加载这是验证技能集成是否成功的直观方法。提示工程在编写给AI的系统提示System Prompt时你可以明确引用这些可用的技能名引导AI在合适的场景下主动使用它们。4.3 畅快的聊天体验Markdown与流式响应主聊天区域是交互的核心。你输入消息AI会以流式Streaming的方式回复。流式响应体验你发送问题后回复不是等AI完全“想”好了再一整段出现而是像有人在实时打字一样一个字一个字、一个词一个词地显示出来。这不仅减少了等待的焦虑感有时你甚至能通过AI先输出的部分内容提前判断它的思考方向是否正确。这个功能的实现依赖于后端OpenClaw网关以Server-Sent Events或分块chunk的形式通过WebSocket推送数据前端则持续接收并拼接、渲染这些数据块。完整的Markdown渲染AI的回复如果包含代码块会被自动识别语言并进行语法高亮阅读代码非常舒适。表格会渲染成结构清晰的HTML表格。列表、加粗、斜体、链接都会以对应的富文本样式呈现。 这极大地提升了长文回复、技术解答、数据展示的可读性。相比之下在WhatsApp里收到一段包含代码的回复所有格式都会丢失体验天差地别。对话历史管理界面通常会维护一个会话历史。你可以开始一个新对话New Chat清空当前上下文。有些实现还可能支持重命名对话、删除历史记录等功能。所有历史记录默认都保存在浏览器的本地存储IndexedDB或LocalStorage中刷新页面不会丢失但清除浏览器数据会。5. 常见问题排查与进阶技巧5.1 连接类问题问题现象可能原因排查步骤与解决方案无法连接网关1. OpenClaw网关未运行。2. 网关URL或端口错误。3. 防火墙/安全组阻止。1. 在终端运行openclaw status确认网关状态。2. 检查openclaw gateway config确认WebSocket监听地址和端口。3. 本地尝试curl -v http://127.0.0.1:18789(或对应端口)看是否有响应网关可能提供HTTP健康检查端点。连接成功但立即断开/认证失败1. 令牌Token错误或过期。2. 网关配置了IP白名单。1. 重新从~/.openclaw/openclaw.json文件复制令牌注意不要包含多余空格或换行。2. 检查网关配置文件确认是否限制了连接来源IP。本地连接通常无此问题VPS部署时需注意。VPS部署后外部无法访问Web界面1. VPS防火墙未开放3000端口。2. 生产服务器未正确启动或监听在0.0.0.0。1. 在VPS上运行sudo ufw allow 3000(如果使用UFW) 或配置云服务商安全组。2. 确保启动命令是npm start或HOST0.0.0.0 npm start让服务监听所有网络接口。WebSocket连接在Nginx反向代理后失败Nginx未正确配置WebSocket代理。在Nginx的location配置块中必须添加以下指令proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection upgrade;5.2 功能与显示类问题问题现象可能原因排查步骤与解决方案技能侧边栏为空1. 网关未加载任何技能。2. 前端获取技能列表的API路径或方式错误。1. 检查OpenClaw的配置文件或日志确认技能插件已正确安装和启用。2. 打开浏览器开发者工具“网络(Network)”标签查看连接建立后是否有获取技能列表的请求以及其响应内容。Markdown或代码高亮不渲染1. 对应的React组件库未正确安装或引入。2. AI回复的内容格式不是标准Markdown。1. 确认package.json中包含了react-markdown和语法高亮库如rehype-highlight并检查相关渲染组件代码。2. 有时AI的回复可能包含非标准的Markdown或混合格式。可以尝试将AI的原始回复粘贴到专门的Markdown编辑器中测试。流式响应中断或不流畅1. 网络不稳定。2. 后端响应流被意外中断。3. 前端处理流数据的逻辑有缺陷。1. 检查网络连接。对于VPS部署网络延迟可能导致体验不佳。2. 查看OpenClaw网关日志看AI处理过程中是否有报错。3. 在开发者工具中查看WebSocket消息帧看数据流是否完整。对话历史丢失浏览器本地存储被清除。确认项目使用的是localStorage还是IndexedDB。这是前端持久化策略刷新页面应保留但清除浏览器数据或使用隐私模式会丢失。如需跨设备同步需要自行开发后端用户系统。5.3 性能优化与自定义进阶优化构建体积Next.js生产构建会自动优化。你还可以通过分析包大小npm run analyze来查看是否有意外引入的大型依赖并考虑按需引入如图标库。自定义UI主题项目使用Tailwind CSS修改主题非常方便。你可以直接编辑tailwind.config.js文件修改colors、fontFamily等扩展主题打造独一无二的界面风格。这对于毕业设计展示个性化非常有用。添加新功能对话导出可以增加一个按钮将当前对话历史以Markdown或JSON格式导出到文件。预设提示词在输入框附近添加一个“常用指令”下拉菜单快速插入如“用表格总结”、“用Python代码实现”等预设提示。多会话管理强化会话管理功能支持树状结构、会话标签、搜索历史等。与CI/CD集成如果你将代码托管在GitHub可以配置GitHub Actions在每次向主分支推送代码时自动构建Docker镜像并部署到你的VPS。这实现了自动化运维。整个项目搭建和使用下来最深的体会是将强大的AI能力与一个自主、美观、功能完备的界面相结合带来的掌控感和体验提升是巨大的。它不再是一个躲在即时通讯软件里的“黑盒”而是一个你可以清晰观察、直接交互的数字伙伴。无论是用于学习、工作还是作为技术探索的起点这个项目都提供了一个极佳的样板。如果你在部署或修改过程中遇到了上面没提到的问题最好的办法是打开浏览器的开发者工具和查看服务端的日志大部分问题的答案都藏在这些输出里。