跳到主要内容
AI教程

如何自行托管 Whirl：全栈 AI 聊天应用

了解如何在本地安装并运行 Whirl、连接所需服务、开始首次 AI 对话，并掌握其可选功能。本教程还将介绍仓库结构、隐私功能、配置策略，以及为自托管部署做准备的实用技巧。

AI我搜编辑部阅读约 8 分钟
如何自行托管 Whirl：全栈 AI 聊天应用

什么是 Whirl？

Whirl 是一款使用 Next.js 和 Convex 构建的开源全栈 AI 聊天应用。它是 whirl.chat 背后的代码，并采用 MIT 许可证发布，因此你可以检查代码、运行自己的实例或贡献改进。

该项目将多种 AI 模型、持久记忆、可编辑工件、网络研究、自定义工具和注重隐私的对话整合到一个界面中。模型通过 OpenRouter 路由，Convex 则提供数据库、后端函数、流式传输和计划任务。

主要功能

  • 多种领先模型：在同一对话中使用顶尖 AI 模型，并调整其思考级别。
  • 动态工件：创建文档、图表和交互式页面，这些内容会在侧边面板中保持可编辑状态，也可以通过链接分享。
  • 工具与技能：通过 MCP 连接外部工具，包括基于 OAuth 的集成；还可以安装扩展 Whirl 行为的技能。
  • 长期记忆：在不同对话之间保留偏好和项目上下文。
  • 最新网络信息：搜索网络并阅读网页，基于近期来源生成答案。
  • 私密对话：锁定的聊天会在用户设备上使用服务器永远无法获取的密码加密，并且仅使用零数据保留模型。
  • 生产力功能：Whirl 支持隐身模式、消息排队、语音输入、图像生成、文件附件、文件夹和分享。
  • 可自定义界面：选择浅色或深色模式、设置强调色，并将 Whirl 安装为移动端 Web 应用。

技术栈

生产环境 Web 应用使用 Next.js 16、React 19、Tailwind CSS v4 和 Motion。Convex 提供后端，Clerk 负责身份验证，OpenRouter 则通过 AI SDK 提供模型访问。代码仓库采用 Bun 工作区组织，并使用 TypeScript 编写。

核心配置只需要 Convex、Clerk 和 OpenRouter。其他服务均为可选：

  • Autumn，用于计费
  • Exa，用于网络搜索
  • Supermemory，用于记忆
  • PostHog 和 Axiom，用于分析
  • Braintrust，用于追踪
  • Resend，用于电子邮件
  • Median，用于支持代理

如果未配置某项可选服务，Whirl 会隐藏由该服务提供支持的功能，而不是要求该服务才能运行应用。

前置条件

安装 Whirl 前，请准备以下内容：

  • 已安装在计算机上的 Bun
  • 一个免费的 Convex 账户
  • 一个 Clerk 应用
  • 一个 OpenRouter API 密钥
  • 用于克隆代码仓库的 Git

步骤 1：克隆并安装 Whirl

克隆代码仓库，进入其目录，并使用 Bun 安装所有工作区依赖：

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

步骤 2：创建 Convex 后端

进入后端包并启动 Convex 开发进程：

cd packages/backend
bunx convex dev

首次运行时，Convex 会引导你创建项目和开发部署。请保持该进程运行，以便在开发期间同步后端变更。

步骤 3：配置后端密钥

在 packages/backend 中打开另一个终端。将 Clerk JWT 发行者域名和 OpenRouter API 密钥添加到 Convex 环境中：

bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

将示例值替换为你自己的 Clerk 和 OpenRouter 账户凭据。详细的自托管文档说明了 Convex 所需的 Clerk JWT 模板。

请勿将 API 密钥或身份验证密钥提交到代码仓库。使用 Convex 环境命令存储后端密钥，并将本地 Web 设置存储在适当的环境文件中。

步骤 4：配置 Web 应用

进入生产 Web 应用目录，并根据提供的示例创建本地环境文件：

cd ../../apps/v2
cp .env.example .env.local

打开 .env.local，填写 Convex 和 Clerk 所需的四个值。请以示例文件中的变量名为准，不要创建新的名称。

步骤 5：启动开发环境

返回代码仓库根目录并启动开发命令：

cd ../..
bun run dev

服务运行后，打开 localhost:3000。通过已配置的 Clerk 应用登录，然后开始对话。

基本用法

开始对话

在聊天输入框中输入请求，并将其发送给已配置的模型。下面这个简单的初始提示可以验证 Web 应用、身份验证、Convex 后端和 OpenRouter 连接是否协同正常：

用五个简洁的要点解释此应用的主要组件。

使用模型

Whirl 旨在通过 OpenRouter 在一次对话中提供对多种领先模型的访问。对于应用和所选模型支持的情况，你还可以使用可调节的思考级别。

创建和完善产物

让 Whirl 生成文档、图表或交互式页面。这些动态产物会保留在侧边面板中，仍可继续编辑，也可以通过链接分享，因此适合需要持续完善的输出，而不只是一次性的聊天回复。

使用文件、语音和组织功能

除了输入文字消息外，Whirl 还支持文件附件和语音输入。你可以将对话整理到文件夹中，并通过分享功能让他人访问选定的内容。

了解代码仓库

该 monorepo 包含多个应用和一个共享后端：

  • apps/v2：Whirl 使用的生产环境 Next.js Web 应用。
  • apps/console：用于管理模型、集成和技能的 Vite 管理控制台。
  • apps/mobile：使用 Expo 构建的原生应用。
  • apps/waitlist：独立的候补名单页面。
  • apps/remotion：宣传视频合成项目。
  • apps/legacy：之前的 Web 应用，仅保留用于参考，已不再维护。
  • packages/backend：Convex 架构、函数和 AI 流程。
  • docs：自托管、配置和架构指南。
  • brand：Logo、颜色、横幅和应用图标。

对于当前的 Web 开发，请重点关注 apps/v2 和 packages/backend。不要在 apps/legacy 上构建新功能，因为它已不再维护。

高级技巧

逐步添加可选服务

先配置必需的 Convex、Clerk 和 OpenRouter。核心聊天流程正常运行后，再逐个添加可选提供商。缺少必需密钥时，Whirl 会自动隐藏相应功能，因此可以方便地运行规模更小的安装。

有关计费、搜索、记忆、分析、追踪、电子邮件和支持功能对应的环境变量，请参阅代码仓库中的配置指南。

选择合适的隐私模式

如果不希望使用普通的持久化对话流程，请使用隐身模式。需要更强保护时，可以使用锁定聊天：聊天内容会在设备上使用服务器永远无法看到的密码进行加密，并且只由零保留模型回答。请注意，如果丢失由客户端持有的密码，可能会影响你访问加密内容的能力。

检查消息流程

调试流式传输、工具调用或模型行为时，请阅读项目的架构指南。其中说明了消息如何从编辑器传递到模型，再返回应用。相关实现主要分布在生产环境 Web 应用和 Convex 后端中。

谨慎准备生产环境

快速入门会创建开发环境。在公开部署之前，请遵循完整的自托管指南，包括其中关于 Clerk JWT 模板和生产部署的说明。

安全地参与贡献

提交拉取请求前，请阅读项目的贡献指南，了解约定和检查要求。请遵守行为准则，并按照SECURITY.md中的流程报告安全问题，不要创建公开 issue。

结语

Whirl 为自托管 AI 聊天工作区提供了功能丰富的起点，将 Next.js 界面与 Convex 后端、Clerk 身份验证和 OpenRouter 模型访问结合在一起。先配置三个必需服务，在 localhost:3000 验证本地聊天，然后根据部署需求启用可选的搜索、记忆、分析、计费及其他集成。