1. 项目概述你的私有AI工作空间如果你和我一样对当前主流AI助手的“黑盒”体验感到不满——对话历史被云端记录、任务执行过程不透明、本地模型接入繁琐——那么ClaraVerse的出现绝对值得你花上十分钟了解一下。这不仅仅是一个“又一个AI聊天界面”而是一个真正将控制权交还给用户的私有化AI工作空间。它把聊天、可视化工作流、看板式任务管理、甚至Telegram集成全部打包进一个你可以完全掌控的应用里。简单来说ClaraVerse让你能像指派一位数字同事一样给名为Clara的AI助手分派研究、编码或自动化等长期任务并在一个清晰的看板上追踪所有进展。最吸引我的是它的“零配置”理念只要你本地运行着Ollama或LM Studio它就能自动发现并导入所有模型开箱即用。数据隐私方面它采用了浏览器本地存储IndexedDB的零知识架构你的对话记录只留在你自己的设备上。无论是想用GPT-4、Claude 3、Gemini这些云端巨头的API还是完全依赖本地的Llama、Qwen等开源模型它都能无缝支持。2. 核心架构与设计哲学解析2.1 为什么是“工作空间”而非“聊天机器人”市面上的AI工具大多聚焦于单次对话的交互体验但真实的工作场景往往是多线程、长周期且需要协同的。ClaraVerse的设计哲学正是基于此痛点。它将AI能力模块化并嵌入到一个完整的工作流管理系统中。Nexus任务中心这是其核心创新。你可以创建一个任务比如“分析本季度销售数据并生成报告”Clara会将其拆解为子任务获取数据、清洗、分析、可视化、撰写并在一个类Kanban看板上展示每个步骤的状态。这彻底打破了AI响应的“一次性”黑盒让你能清晰看到AI的“思考”过程和执行进度必要时还能进行人工干预Human-in-the-loop。技能Skills系统不同于需要手动触发插件的传统模式Clara的技能是上下文感知的。在聊天中当你提到“帮我查一下今天的科技新闻”它会自动调用网络搜索技能提到“为这个数据集画个图”数据分析技能便会激活。这种无感切换极大地提升了对话的流畅度和实用性。一体化集成层超过150种工具如GitHub、Notion、Slack、Google Sheets的集成不是为单个功能服务的而是作为一个共享层。你在聊天中授权连接了Notion那么这个连接在创建工作流、设置定时任务Routines或是在Nexus中让Clara写文档时都可以直接调用无需重复配置。2.2 隐私优先的技术实现数据安全是自托管项目的生命线。ClaraVerse在这方面做了多层设计对话本地化所有聊天记录默认存储在浏览器的IndexedDB中。这意味着即使你的服务器被托管在VPS上最核心的对话数据也从未离开过你的客户端。服务器端只处理任务元数据、工作流定义和集成配置等非对话内容。本地AI优先项目对Ollama和LM Studio的自动发现机制做得非常彻底。它通过Docker的host.docker.internal或预设的本地网络地址定期每2分钟扫描可用的本地模型服务。一旦发现自动创建对应的模型提供商并导入所有可用模型。这省去了在Web UI里手动填写API地址和密钥的麻烦。透明的多后端支持其架构清晰地将“推理提供商”如OpenAI、Ollama与“能力模块”聊天、工作流解耦。无论你使用哪个提供商上层的功能体验是一致的。这为用户提供了极大的灵活性可以在预算、性能和隐私之间自由权衡。2.3 技术栈选型的考量ClaraVerse选用的技术栈体现了现代、高效和实用的平衡前端React 19 Vite TypeScript Tailwind CSS采用最新的React并发特性以构建更流畅的交互界面Vite提供极速的开发和构建体验TypeScript保障大型前端项目的代码质量Tailwind CSS则实现了高效、一致性的样式开发。Zustand状态管理库相比Redux更轻量适合这种复杂但并非极度庞大的状态管理需求。后端Go FiberGo语言以其高并发、高性能和简洁的语法著称非常适合构建需要处理大量WebSocket连接用于实时任务更新、聊天流的AI应用后端。Fiber是一个受Express启发的Web框架性能优异且语法友好能快速构建RESTful和WebSocket端点。数据层MySQL MongoDB Redis这是一个经典的混合持久化方案。MySQL用于存储高度结构化、关系型的数据如用户信息、任务元数据、集成配置。MongoDB的文档模型适合存储半结构化或变化频繁的数据如复杂的工作流定义、聊天消息的扩展属性。Redis则作为缓存和消息队列提升会话状态管理和实时消息推送的性能。搜索SearXNG直接集成一个自托管的元搜索引擎确保了“网络搜索”技能同样在隐私可控的范围内进行避免了将用户查询发送给第三方搜索引擎API。3. 从零开始部署详细实操指南3.1 环境准备与部署方案选择在动手之前你需要根据自身情况选择部署方式云托管版访问其官网即可免费使用最快捷适合体验和轻度使用。自托管Docker Compose推荐方案。能获得完整控制权数据完全私有可以使用本地模型。需要一台至少有4GB RAM推荐8GB的Linux/macOS服务器或本地电脑。桌面应用基于Electron的独立客户端适合不想折腾服务端的桌面用户。这里我们重点讲解最核心的自托管Docker Compose方案。基础环境检查确保你的系统已安装 Docker 和 Docker Composev2。可以通过命令检查docker --version docker compose version3.2 使用Docker Compose一键部署这是最标准、最省心的部署方式它会拉起包括ClaraVerse应用本身、MySQL、MongoDB、Redis和SearXNG在内的完整服务栈。操作步骤克隆仓库并进入目录git clone https://github.com/claraverse-space/ClaraVerse.git cd ClaraVerse启动服务直接使用项目提供的生产环境配置启动。docker compose -f docker-compose.production.yml up -d这个-d参数代表后台运行。第一次执行会拉取所有镜像并创建容器和卷可能需要几分钟时间。访问与初始化启动完成后在浏览器打开http://你的服务器IP:3000。你会看到注册页面。第一个注册的用户会自动成为管理员拥有管理模型提供商、查看系统日志等权限。完成注册后即可登录开始使用。注意默认配置下所有数据数据库文件、上传文件都保存在Docker的命名卷claraverse-data,claraverse-uploads等中。即使删除容器数据也不会丢失。执行docker compose -f docker-compose.production.yml down只会停止并移除容器数据卷保留。3.3 关键配置详解连接本地AI模型让ClaraVerse使用你本地运行的Ollama模型是提升隐私和节省成本的关键。这里有几个核心配置点1. 确保Ollama监听正确地址Ollama默认只监听127.0.0.1这意味着只有本机可以访问。但在Docker网络中容器被视为独立主机无法直接访问宿主机的127.0.0.1。因此需要让Ollama监听所有网络接口。Linux (Systemd服务) 修改方法sudo systemctl edit ollama在打开的编辑器中添加以下内容[Service] EnvironmentOLLAMA_HOST0.0.0.0保存退出后重启Ollama服务sudo systemctl restart ollamamacOS/Linux (通过环境变量启动)如果你是通过命令行启动可以这样设置OLLAMA_HOST0.0.0.0 ollama serve或者将其添加到你的shell配置文件如~/.bashrc或~/.zshrc中。2. 理解ClaraVerse的自动发现机制ClaraVerse容器内部会尝试通过http://host.docker.internal:11434这个地址访问宿主机的Ollama服务。host.docker.internal是Docker为宿主机保留的特殊域名。如果你的部署环境是Linux服务器且Docker版本较旧可能不支持此域名。此时需要手动配置。3. 自定义配置高级在ClaraVerse项目根目录下创建或编辑一个名为.env的文件覆盖默认配置# 将ClaraVerse的Web服务端口改为8080可选 CLARAVERSE_PORT8080 # 手动指定Ollama的地址。如果Docker不支持host.docker.internal请替换为宿主机的实际IP如192.168.1.100 OLLAMA_BASE_URLhttp://192.168.1.100:11434 # 同理可以指定LM Studio的地址 # LMSTUDIO_BASE_URLhttp://192.168.1.100:1234保存后重启服务使配置生效docker compose -f docker-compose.production.yml down docker compose -f docker-compose.production.yml up -d4. 在界面中确认登录ClaraVerse后点击左下角你的头像进入“Admin Panel”。在“Providers”标签页下你应该能看到一个状态为“Online”的提供商例如 “Ollama (Local)”。点击它可以看到从你本地Ollama中自动导入的所有模型。在这里你可以启用/禁用特定模型或调整它们的优先级。3.4 使用Clara Companion桥接本地MCP服务器这是ClaraVerse另一个强大的特性。MCPModel Context Protocol是一个新兴协议旨在标准化AI模型与工具如文件系统、数据库、第三方API的连接。Clara Companion就是一个MCP桥接器。它能做什么假设你在本地开发机上运行了一个MCP服务器它可以提供访问你代码库、特定数据库或内部系统的能力。通过Clara Companion你可以将这个本地服务器的能力安全地“桥接”到远程的ClaraVerse实例比如你部署在云服务器上的ClaraVerse让云端的Clara也能使用你本地的工具。操作步骤安装Companion如果你已经通过一键脚本安装了claraverseCLI那么可以直接使用claraverse companion或者从项目的GitHub Releases页面手动下载对应系统的二进制文件。登录并连接# 运行登录命令它会提示你输入ClaraVerse实例的地址默认为 http://localhost:3000 clara_companion login # 启动桥接服务 clara_companion启动后Companion会在后台运行建立WebSocket连接。此时在你的ClaraVerse Admin Panel的“Devices”标签页下应该能看到一台在线设备其上的MCP服务器提供的工具Skills也会被同步到ClaraVerse中在聊天或工作流里即可调用。4. 核心功能深度体验与使用技巧4.1 Nexus将AI任务管理工程化Nexus功能彻底改变了我和AI协作的方式。以前让AI写个脚本或做调研我只能一次性抛出问题然后等待一个可能不完整或需要多次修正的结果。现在我可以这样操作创建任务在Nexus面板点击“New Task”输入一个复杂目标例如“开发一个Python脚本监控指定目录下的新图片并自动调用本地Stable Diffusion API为其生成缩略图”。任务拆解与追踪Clara会主动将这个任务拆解为“分析需求”、“设计脚本结构”、“编写文件监控模块”、“集成SD API调用”、“编写错误处理逻辑”、“撰写使用说明”等多个子任务并将它们分别放入“待处理”、“进行中”、“待审核”、“完成”等看板列中。人工干预与审核我可以随时点击任何一个子任务查看Clara生成的代码或文案并提出修改意见。例如在“集成SD API调用”任务中我可以评论“请使用更具体的错误提示并增加重试逻辑。” Clara会根据反馈更新该任务。上下文继承整个Nexus任务板共享一个持久的上下文。这意味着在“编写文件监控模块”时Clara完全清楚之前“分析需求”中确定的技术选型比如用watchdog库。实操心得对于特别复杂或关键的任务我习惯先在聊天中和Clara进行几轮“头脑风暴”明确边界和技术路径然后再将最终确认的方案作为描述提交到Nexus。这能大幅减少任务执行过程中的返工。4.2 工作流无需代码的视觉化自动化工作流编辑器是给非开发者或想快速原型化的开发者的利器。其核心优势在于“描述即生成”。自然语言创建在编辑器里我直接输入“每周一早上9点从Jira抓取‘本周待办’状态的任务总结后发送到Slack的#周报频道并私信给我”。Clara的LLM会理解这个描述并自动生成一个包含“定时触发器”、“Jira查询节点”、“文本处理节点”、“Slack消息节点”的工作流图。并行执行与错误处理你可以轻松地设置多个分支同时运行。每个节点都有独立的成功/失败输出路径。我可以配置当“调用某API失败”时自动执行“发送告警到Telegram”的备用分支。变量与数据流节点之间通过变量传递数据。你可以引用上游节点的输出例如{{steps.jira_query.output.issues}}。编辑器提供自动补全非常方便。一个实用工作流示例信息聚合与播报触发器每天上午8点。并行分支1调用“网络搜索”技能获取指定关键词的新闻摘要。并行分支2调用“GitHub API”集成获取我关注仓库的昨日更新。聚合节点将两个分支的结果合并让Clara用一段话总结。输出节点将总结内容通过“Telegram Channel”发送到我的手机。这样我每天起床就能在Telegram上收到一份个性化的晨间简报。4.3 技能与交互式提示更智能的对话Clara的技能系统让我感觉像是在和一个真正拥有“工具箱”的助手对话。上下文触发当我问“上海明天天气怎么样”它会自动调用“网络搜索”或“天气查询”技能如果已配置并直接返回结果而不是反问“你需要我搜索吗”。这种无感交互极大地提升了效率。交互式表单当需求模糊时Clara不会瞎猜。例如我让它“帮我生成一张图”它会直接在聊天界面弹出一个表单让我选择或输入图片主题、风格写实/卡通/水墨、尺寸、颜色倾向等。这种“人在回路”的设计确保了输出结果更符合预期。技能市场展望虽然目前内置技能已非常丰富但基于其架构未来社区完全可以开发并分享新的技能插件潜力巨大。4.4 频道与定时任务跨设备无缝衔接Telegram集成Channels解决了移动场景下的使用痛点。绑定Telegram在ClaraVerse的“Channels”设置中通过与BotFather创建的机器人关联获得一个专属的私聊通道。随时随地聊天在外面时我可以在Telegram上直接和Clara对话上下文与Web端同步。定时任务推送在“Routines”中设置的任何定时任务如每日摘要、定期检查其执行结果都可以配置为推送到绑定的Telegram频道。这样重要的AI输出能主动找到我而不是需要我主动去查。5. 运维、问题排查与性能调优5.1 日常运维命令掌握几个简单的Docker Compose命令足以管理日常运维# 查看所有容器状态 docker compose -f docker-compose.production.yml ps # 查看ClaraVerse应用日志-f 表示实时跟随 docker compose -f docker-compose.production.yml logs -f claraverse # 查看数据库日志 docker compose -f docker-compose.production.yml logs -f mysql # 重启单个服务如更新后端代码后 docker compose -f docker-compose.production.yml restart claraverse # 停止所有服务 docker compose -f docker-compose.production.yml down # 停止并彻底清除所有数据卷也会被删除谨慎使用 docker compose -f docker-compose.production.yml down -v5.2 常见问题与排查问题1访问http://localhost:3000无法连接。检查服务状态运行docker compose -f docker-compose.production.yml ps确认所有容器尤其是claraverse状态为 “Up”。检查端口占用确认3000端口未被其他程序占用。可临时修改.env中的CLARAVERSE_PORT为其他端口如8080再重启。查看日志运行docker compose -f docker-compose.production.yml logs claraverse查看错误输出。常见错误包括数据库连接失败、环境变量配置错误等。问题2Ollama模型已运行但ClaraVerse中检测不到或状态为Offline。确认Ollama监听地址在宿主机运行curl http://127.0.0.1:11434/api/tags应能返回模型列表。如果不能说明Ollama服务未正常运行。确认网络连通性在ClaraVerse容器内测试连通性需要进入容器docker exec -it claraverse-space-claraverse-1 /bin/sh # 进入容器后测试连接宿主机IP替换为你的实际IP curl http://192.168.1.100:11434/api/tags检查环境变量确认.env文件中的OLLAMA_BASE_URL设置正确。对于Linux服务器可能需要使用宿主机实际IP而非host.docker.internal。防火墙确保宿主机的11434端口对Docker网络是开放的。问题3任务执行缓慢或卡住。资源监控使用docker stats命令查看容器CPU、内存占用。如果内存不足可能导致Ollama模型加载失败或响应极慢。考虑为Docker分配更多资源或使用更小参数的模型。模型负载如果多个任务同时使用同一个本地模型可能会排队。可以在Admin Panel的Providers设置中为重要模型设置更高的并发数或部署多个Ollama实例分流。检查后端日志任务引擎的错误日志通常会输出到ClaraVerse容器的日志中。问题4浏览器本地存储对话丢失。浏览器行为IndexedDB存储与特定域名和端口绑定。如果你更换了访问地址如从IP改为域名或者用浏览器隐私模式会导致存储隔离。清除数据如果浏览器清理了缓存和站点数据也会导致对话丢失。这是设计如此旨在保障隐私。重要对话请及时使用导出功能或确保工作成果通过Nexus任务、工作流输出等形式保存在服务器端。5.3 数据备份与迁移服务器端的数据用户、任务元数据、工作流、集成配置保存在Docker卷中。备份的关键就是备份这些卷。定位卷使用docker volume ls找到名为claraverse-data、claraverse-mysql-data等相关的卷。备份卷可以使用docker run --rm -v [卷名]:/data -v $(pwd):/backup alpine tar czf /backup/[卷名].tar.gz -C /data .这样的命令将卷内容打包。迁移在新服务器上部署好ClaraVerse后先停止服务然后将备份的tar.gz文件解压到新服务器对应的Docker卷挂载目录再启动服务即可。对于生产环境建议定期执行此类备份并将备份文件存储到安全的位置。5.4 性能调优建议硬件如果主要使用本地大模型如70B参数级别16GB以上内存是必须的。CPU核心数影响推理速度GPU通过Ollama的GPU加速能带来质的飞跃。模型选择在Admin Panel中可以禁用不常用的模型减少Ollama的内存占用。对于日常对话任务7B-13B参数的模型在质量和速度上是不错的平衡。数据库优化对于长期使用、数据量大的情况可以考虑将Docker卷映射到高性能的SSD上并对MySQL、MongoDB的配置进行针对性调优如调整缓存大小。网络如果ClaraVerse服务器和Ollama服务不在同一台机器需要保证它们之间的网络延迟足够低否则会严重影响聊天体验。6. 开发与贡献指南ClaraVerse是一个活跃的开源项目欢迎开发者贡献代码。其模块化架构使得参与门槛相对清晰。本地开发环境搭建启动依赖服务在项目根目录使用开发配置启动数据库等后台服务。docker compose -f docker-compose.dev.yml up -d配置后端cd backend cp .env.example .env # 编辑 .env配置数据库连接等信息通常开发配置已预设好 go run cmd/server/main.go配置前端cd frontend cp .env.example .env npm install npm run dev前端开发服务器运行在http://localhost:5173并代理API请求到后端localhost:3001。主要的贡献方向新的集成工具参考backend/internal/tools目录下的现有实现为新的服务如ClickUp、Airtable添加集成。核心是实现标准的工具接口。新的模型提供商参考backend/internal/providers目录添加对新的AI API如DeepSeek、国内大模型的支持。前端组件与UI优化React组件位于frontend/src/components可以改进现有交互或添加新功能。Bug修复与文档直接查看GitHub Issues列表解决已知问题或完善使用文档、翻译。在提交PR前请确保前端代码通过代码检查和类型检查cd frontend npm run lint npm run type-check经过一段时间的深度使用ClaraVerse给我的感觉更像是一个可编程的、透明的AI数字助理基础设施。它没有试图做一个在单一任务上超越ChatGPT的模型而是专注于解决“如何高效、可控、私有地管理和运用AI能力”这个工程问题。从自动化的日常简报到复杂项目的分步推进再到将AI能力通过Telegram延伸到移动端它切实地融入了我的工作流。对于注重隐私、希望拥有完全控制权且不惧于在自有基础设施上进行一些部署和维护的科技爱好者或中小团队来说ClaraVerse提供了一个当前非常稀缺的、优雅的解决方案。它的开源属性也意味着你可以根据自己的需求对其进行深度定制这或许是未来AI工具演进的一个重要方向。