1. 项目概述你的私有AI工作空间如果你和我一样对市面上的AI助手又爱又恨——爱它们的强大能力恨它们要么是云端黑盒要么功能单一要么配置复杂——那么ClaraVerse的出现绝对值得你花上十分钟了解一下。这不仅仅是一个聊天界面它是一个完整的、可私有化部署的AI工作空间。想象一下把ChatGPT的对话能力、Trello的任务看板、Zapier的自动化流程以及一个能直接调用你本地Ollama模型的智能体全部整合进一个界面并且数据完全掌握在你自己的服务器或浏览器里。这就是ClaraVerse正在做的事情。简单来说ClaraVerse是一个开源的、自托管的AI智能体平台。它的核心目标是为个人和小团队提供一个功能聚合、隐私优先的AI操作中心。你不再需要在十几个标签页和不同应用间来回切换在这里你可以和名为“Clara”的AI助手聊天、给她分配需要长时间运行的研究或编码任务、用拖拽的方式构建复杂的自动化工作流甚至通过Telegram在手机上与她互动。最吸引我的一点是它对“本地优先”的极致支持如果你已经在电脑上运行了Ollama或LM StudioClaraVerse能自动发现并导入你所有的本地模型几乎无需任何配置就能让强大的开源大模型为你工作。2. 核心架构与设计哲学2.1 为什么是“工作空间”而非“聊天机器人”市面上的AI应用大多聚焦于单点功能要么是纯聊天要么是自动化要么是AI绘画。ClaraVerse的设计哲学从一开始就不同它要成为一个上下文连贯的协作环境。这意味着你在聊天中提到的任务可以直接拖进Nexus看板进行长期追踪在工作流中生成的数据可以无缝成为下一次对话的上下文通过Telegram频道设置的定时任务其结果会同步回主应用。这种设计消除了工具间的数据孤岛让AI真正成为一个连贯的“数字同事”。其技术栈的选择也紧紧围绕这一目标。后端采用Go语言编写看重其高并发性能和轻量级特性非常适合处理AI任务流和实时WebSocket通信。前端基于现代的React 19 TypeScript Vite构建确保了复杂交互界面的流畅体验。数据层则务实地区分了关系型、文档型和缓存型数据分别用MySQL、MongoDB和Redis来处理这种混合架构在应对AI应用多变的数据形态结构化任务、非结构化对话历史、实时状态时显得游刃有余。2.2 隐私优先的零知识架构隐私是ClaraVerse的另一个基石也是我决定深度使用它的关键原因。它的“浏览器本地存储”机制并非噱头。所有对话历史、临时上下文等敏感数据默认直接存储在浏览器的IndexedDB中永远不会未经加密就发送到服务器。服务器端只处理任务编排、模型调用和集成逻辑。这种“零知识”架构意味着即使你使用托管的ClaraVerse云服务从理论上讲服务提供商也无法窥探你的对话内容。对于自托管用户你则拥有数据的完全主权。这种设计也带来了一个有趣的副作用你的聊天体验会非常“快”。因为大量的上下文切换和渲染都在本地完成减少了网络往返延迟。当然这也对前端状态管理提出了更高要求项目选用Zustand这类轻量级状态库正是为了在复杂状态和性能之间取得平衡。2.3 无缝的本地AI集成自动发现的魔法对于本地AI爱好者来说ClaraVerse的“自动发现”功能堪称神来之笔。通常将Ollama这样的本地模型服务接入一个Web应用需要手动配置IP、端口、API密钥等一系列参数过程繁琐且容易出错。ClaraVerse彻底简化了这一步。当你启动ClaraVerse无论是Docker版还是桌面版它会自动在你的本地网络中进行扫描寻找已知的AI服务端点。对于Ollama它会尝试连接http://host.docker.internal:11434对于LM Studio则是http://host.docker.internal:1234。一旦发现它会立即拉取该服务中所有可用的模型列表并在后台自动为你创建一个对应的“模型提供商”同时设置好基本的可见性权限。整个过程静默完成你在UI的模型选择下拉菜单里立刻就能看到自己本地的llama3.2、qwen2.5等模型开箱即用。实操心得关于Ollama的“0.0.0.0”陷阱这里有一个几乎所有新手都会踩的坑Docker容器默认无法访问宿主机上监听127.0.0.1的服务。如果你发现ClaraVerse无法自动发现Ollama九成是因为Ollama默认绑定在127.0.0.1。解决方法很简单修改Ollama的配置让其监听所有网络接口# Linux/macOS 使用 systemd 的情况 sudo systemctl edit ollama在打开的编辑器中添加以下内容[Service] EnvironmentOLLAMA_HOST0.0.0.0保存退出后重启Ollama服务sudo systemctl restart ollama。之后ClaraVerse就能顺利发现了。3. 核心功能深度解析与实操3.1 Nexus你的AI任务指挥中心Nexus是ClaraVerse区别于普通聊天机器人的核心功能。它本质上是一个为AI智能体设计的Kanban看板任务管理系统。你不再需要把复杂的任务用一段冗长的提示词塞给AI然后祈祷它不会中途“失忆”。如何使用Nexus创建任务在聊天窗口或Nexus面板中你可以像给同事分配工作一样给Clara创建一个任务。例如“研究一下2024年Rust在Web后端开发中的最佳实践并整理成一份带有代码示例的Markdown报告。”任务分解与追踪Clara会接受任务并将其分解为“待处理”、“进行中”、“等待反馈”、“已完成”等状态显示在看板上。你可以清晰看到每个任务的当前状态、所属分类以及负责人当然是Clara。介入与协作在任务执行过程中如果Clara需要更多信息比如让你确认某个研究方向或者遇到无法自动处理的障碍任务卡会进入“等待反馈”列。你可以点击任务查看其详细日志并提供必要的输入。这种“Human-in-the-loop”人在回路的设计确保了复杂任务的可靠完成。成果交付任务完成后所有的输出物——文本报告、生成的代码、收集的参考资料链接等都会附在任务卡上方便你集中查阅和归档。个人使用场景我常用它来管理我的技术调研和内容创作。我会创建一个“撰写技术博文”的任务Clara会主动进行资料搜集、大纲拟定甚至在得到我确认后起草初稿。整个过程透明可控我随时可以介入调整方向而不是面对一个一次性生成的、可能离题万里的结果。3.2 上下文感知技能让AI学会“用工具”传统的AI工具调用如OpenAI的Function Calling需要开发者预先定义好工具清单并在每次对话时传给模型。ClaraVerse的“技能”系统更进了一步它是上下文感知和动态激活的。技能如何工作无需显式触发你不需要说“请使用网络搜索技能”。当你在对话中问“今天纽约的天气怎么样”时Clara会根据对话上下文自动判断需要调用“网络搜索”或“天气查询”技能如果已配置并在后台执行将结果融入回复中。丰富的内置技能库项目集成了超过150种工具和集成涵盖Slack、GitHub、Jira、Google Sheets、Notion等主流生产力工具。这些技能在聊天、工作流、Nexus和定时任务中是共享的。你只需要在设置中配置一次GitHub的API密钥那么无论是在聊天中让Clara总结你最近的commit还是在工作流中自动创建issue都可以直接调用。技能组合更强大的是Clara可以链式调用多个技能来完成复杂指令。例如你发出指令“从我们团队的Notion数据库里找出上周所有标记为‘高优先级’的任务总结一下然后发到Slack的#周报频道。” Clara会依次调用Notion读取、文本总结、Slack发送这三个技能一气呵成。3.3 可视化工作流拖拽构建复杂自动化对于不熟悉编程的用户用自然语言描述复杂逻辑并让AI正确执行依然有挑战。ClaraVerse的可视化工作流编辑器解决了这个问题。工作流构建体验自然语言描述你可以在工作流编辑器中直接输入“每天上午9点检查我的GitHub仓库有没有新的issue如果有就提取标题和内容总结后发送到我的Telegram。”AI辅助生成Clara的LLM会理解你的描述并自动生成一个包含“定时触发器”、“GitHub查询节点”、“文本处理节点”、“Telegram发送节点”的可视化工作流图。拖拽编辑与调试当然你也可以完全手动从左侧的节点库包含触发器、逻辑判断、API调用、数据转换等200多种节点中拖拽组件用连线的方式构建流程。每个节点都可以点击配置参数工作流支持并行执行、条件分支和错误处理。调度与API化构建好的工作流可以设置为定时运行如每日、每周也可以暴露为一个HTTP API端点供你自己的其他系统调用。这意味着你可以把ClaraVerse作为整个数字生态的AI自动化中枢。一个真实案例我设置了一个工作流每周一早上自动从我的博客分析工具通过API拉取上周的访问数据让Clara用本地模型分析趋势并生成一段简评然后连同关键图表一起发布到我的团队知识库Notion中。整个过程完全自动化无需我每周手动操作。3.4 频道与定时任务移动端无缝衔接通过“频道”功能你可以将ClaraVerse连接到Telegram。这带来了两个核心价值移动端聊天在Telegram中与Clara对话就像使用ChatGPT官方App一样方便但背后是你自己部署的、功能更强大的私有AI。定时任务与推送你可以创建“Routines”定时任务序列。例如一个每天早上8点运行的Routine让Clara抓取新闻头条、总结你日程表上的首要事项并直接推送到Telegram。这样你醒来就能在手机上收到一份个性化的晨报。配置步骤简述在ClaraVerse后台的“Channels”页面选择连接Telegram。根据指引与BotFather交互创建一个新的Telegram Bot并获取API Token。将Token填入ClaraVerse并设置一个Webhook URL通常ClaraVerse会提供或自动配置。完成后你就可以在Telegram中与你创建的Bot对话ClaraVerse会处理这些消息。4. 部署与配置实战指南4.1 部署方案选型Docker Compose 是最佳路径ClaraVerse提供了多种部署方式对于绝大多数想要自托管的用户我强烈推荐使用Docker Compose方案。它一键封装了所有依赖前端、后端、MySQL、MongoDB、Redis以及私有的SearXNG搜索引擎。这避免了手动安装和配置多个数据库的繁琐也保证了环境的一致性。详细部署步骤环境准备确保你的服务器或本地开发机满足最低要求4GB RAM推荐8GB以上并已安装Docker和Docker Compose V2。获取代码与启动# 克隆仓库 git clone https://github.com/claraverse-space/ClaraVerse.git cd ClaraVerse # 使用生产环境配置启动所有服务 docker compose -f docker-compose.production.yml up -d执行这个命令后Docker会拉取所有必要的镜像并启动容器。-d参数表示在后台运行。初始访问等待一两分钟让服务完全启动。然后在浏览器中打开http://你的服务器IP:3000。首次访问会进入注册页面第一个注册的用户会自动成为管理员拥有系统的全部配置权限。验证服务运行docker compose -f docker-compose.production.yml ps可以查看所有容器的运行状态。确保claraverse、mysql、mongodb、redis、searxng这几个服务的状态都是Up。4.2 关键配置详解环境变量与模型连接默认配置通常就能良好运行但了解关键配置项能让你更好地定制环境。核心环境变量.env文件在ClaraVerse目录下创建一个名为.env的文件可以覆盖docker-compose.production.yml中的默认设置。# 应用访问端口 CLARAVERSE_PORT8080 # 如果你希望使用8080端口而非3000 # 本地AI服务地址关键 # 如果你的Ollama/LM Studio运行在宿主机Docker容器需要通过特殊主机名访问 OLLAMA_BASE_URLhttp://host.docker.internal:11434 LMSTUDIO_BASE_URLhttp://host.docker.internal:1234 # 如果你想使用云端模型在这里添加API密钥 # OPENAI_API_KEYsk-xxx # ANTHROPIC_API_KEYsk-ant-xxx # GOOGLE_API_KEYxxx注意host.docker.internal这个主机名在Linux、macOS和Windows的Docker Desktop中通常都能正确解析到宿主机。但在纯Linux服务器环境下无Desktop可能需要改为宿主机在Docker网桥中的实际IP如172.17.0.1或使用--networkhost模式运行容器。模型提供者配置登录管理员账户后进入Settings - AI Providers。本地模型如果自动发现成功你会看到“Ollama (Local)”之类的提供者。点击即可查看和管理导入的模型可以在这里禁用不需要的模型或调整其优先级。云端模型点击“Add Provider”选择OpenAI、Anthropic、Google等填入对应的API密钥和Base URL如需。配置完成后这些模型会出现在所有模型选择列表中。模型优先级ClaraVerse允许你为不同用途聊天、工作流、Nexus设置默认模型。你可以在Settings - Default Models中为“Chat”、“Workflow Agent”、“Nexus Agent”等分别指定首选模型实现资源优化。例如让聊天使用快速的本地小模型而让执行复杂分析任务的Nexus使用更强大的云端模型。4.3 Clara Companion连接本地MCP服务器的桥梁这是面向高级用户和开发者的一个强大功能。MCPModel Context Protocol是一个新兴协议旨在标准化AI模型与工具如文件系统、数据库、API之间的连接。ClaraVerse原生支持MCP。Clara Companion的作用它是一个轻量级的命令行工具运行在你的本地电脑或任何其他机器上。它的职责是作为一座“桥梁”将这台机器上运行的MCP服务器例如一个可以访问你本地文件系统的MCP服务器安全地连接到你的ClaraVerse实例。使用场景假设你的ClaraVerse部署在云服务器上但你希望AI能读取你家里电脑上的文档。你可以在家里电脑上运行Clara Companion并配置一个文件系统MCP服务器。Companion会通过WebSocket与云端ClaraVerse建立安全连接。这样云端ClaraVerse中的AI助手就能通过这座“桥”安全地访问你家里电脑的文件在你的授权和控制下而无需将文件上传到云端。安装与运行Companion# 如果你已经通过安装脚本安装了claraverse CLI claraverse companion # 或者从GitHub Releases页面手动下载对应系统的二进制文件 # 登录到你的ClaraVerse实例通常是 http://localhost:3000 clara_companion login # 启动桥接服务 clara_companion运行后在ClaraVerse的“Devices”页面你应该能看到这台新连接的设备及其暴露的MCP工具。5. 常见问题与故障排查实录在实际部署和使用中你可能会遇到以下问题。这里记录了我踩过的坑和解决方案。5.1 部署与连接问题问题1Docker Compose启动后访问localhost:3000报错或无法连接。可能原因A端口冲突。检查3000端口是否已被其他程序占用lsof -i:3000(macOS/Linux) 或netstat -ano | findstr :3000(Windows)。解决方案修改.env文件中的CLARAVERSE_PORT变量换一个空闲端口如8080然后重启服务docker compose -f docker-compose.production.yml down docker compose -f docker-compose.production.yml up -d。可能原因B容器启动失败。使用docker compose -f docker-compose.production.yml logs claraverse查看前端容器的日志通常错误信息会明确指出问题如数据库连接失败、依赖缺失等。解决方案根据日志修复。常见情况是MySQL或MongoDB容器初始化较慢前端启动时数据库还未就绪。可以等待一两分钟再刷新或者查看数据库容器的日志docker compose -f docker-compose.production.yml logs mysql。问题2无法自动发现本地Ollama模型。排查步骤确认Ollama服务正在运行ollama serve或systemctl status ollama。确认Ollama监听地址curl -s http://localhost:11434/api/tags。如果这条命令在宿主机上能返回模型列表说明Ollama服务正常。在ClaraVerse容器内测试连接docker exec -it claraverse-container-name curl http://host.docker.internal:11434/api/tags。如果失败说明容器网络无法访问宿主机。解决方案确保Ollama监听0.0.0.0如前文所述修改Ollama配置并重启。检查防火墙宿主机防火墙可能阻止了Docker网桥的访问。可以临时关闭防火墙测试或为Docker网段添加规则。使用宿主机IP在.env文件中将OLLAMA_BASE_URL设置为宿主机在局域网的实际IP如http://192.168.1.100:11434。但这在IP可能变化的移动环境中不友好。5.2 功能使用问题问题3技能调用失败提示“API错误”或“无权限”。排查步骤进入Settings - Integrations找到对应的技能如GitHub。检查配置是否正确特别是API密钥或OAuth令牌是否有效、是否过期。查看该技能的“Scope”权限范围是否足够。例如GitHub技能如果需要访问私有仓库令牌必须包含repo权限。解决方案重新配置技能确保使用具有足够权限的有效凭证。对于OAuth类集成可以尝试“重新授权”按钮。问题4工作流运行到某个节点卡住或失败。排查步骤在工作流编辑器中点击失败的工作流运行实例查看其“执行日志”。日志会详细显示每个节点的输入、输出和错误信息。重点关注失败节点之前的节点输出看数据格式是否符合预期。常见原因与解决API限速或配额不足如果节点调用了外部API如Google Sheets可能触发了限流。可以在该节点前添加一个“Delay”延迟节点。数据格式不匹配例如上一个节点输出的是JSON对象但下一个节点期望的是文本字符串。可以在中间插入一个“JSON to Text”或“Extract”节点来处理数据。条件判断逻辑错误检查“If”节点的条件表达式是否正确。可以使用“Debug”节点将中间数据打印到日志辅助调试。问题5Telegram Bot不回复消息。排查步骤在ClaraVerse的“Channels - Telegram”设置中确认Bot状态为“Connected”。在Telegram中给Bot发送/start命令。ClaraVerse后台的频道日志应该能收到这条消息。如果收不到检查ClaraVerse服务器的网络是否能访问Telegram的APIapi.telegram.org以及Webhook URL是否正确设置通常ClaraVerse会自动设置但如果你用了反向代理或特殊端口可能需要手动配置。解决方案在Telegram Bot设置中检查并设置正确的Webhook URL格式为https://你的ClaraVerse域名/api/v1/channels/telegram/webhook/你的BotToken。确保该URL是公网可访问的HTTPS地址本地测试可使用ngrok等工具暴露临时地址。5.3 性能与优化问题6使用本地大模型时响应速度很慢。分析这通常是模型本身推理速度或硬件GPU/CPU性能的瓶颈而非ClaraVerse的问题。优化建议模型量化在Ollama中使用量化版本模型如qwen2.5:7b-instruct-q4_K_M在几乎不损失精度的情况下大幅提升推理速度并降低显存占用。硬件加速确保Ollama正确利用了GPU如果可用。运行ollama run llama3.2时观察终端输出确认是否显示“Using GPU”。调整上下文长度在ClaraVerse的模型提供商设置中可以调整该模型的“最大上下文长度”。过长的上下文会导致每次推理都需要处理大量文本拖慢速度。根据实际需要调低此值。使用更合适的模型对于简单的聊天任务使用7B甚至3B参数的小模型仅在Nexus处理复杂分析时调用70B级别的大模型。问题7长时间使用后浏览器变卡。原因由于对话历史默认存储在浏览器IndexedDB中长时间积累大量数据尤其是包含长上下文、图片附件时可能影响前端性能。解决方案定期在ClaraVerse的聊天界面或设置中清理不重要的旧对话。对于非常重要的对话记录可以使用“导出”功能备份为文件然后从本地删除。检查浏览器扩展某些广告拦截或脚本拦截扩展可能与复杂的WebSocket应用产生冲突尝试在无痕模式下使用ClaraVerse以排除扩展影响。6. 进阶技巧与生态展望经过一段时间的深度使用我总结出一些能极大提升效率的技巧也对项目的未来生态有一些观察。技巧1巧用“记忆”系统ClaraVerse内置了一个记忆系统Clara会主动记住对话中的关键信息如你的偏好、项目细节。你可以在Settings - Memory中管理这些记忆。更高级的用法是在给Clara分配Nexus任务或构建工作流时在指令中明确引用某条记忆。例如“请参考之前关于‘用户画像’的记忆为我们的新功能起草一份推广文案。” 这能让AI的产出更具一致性和个性化。技巧2创建自定义技能模板虽然内置了150集成但你可能需要连接内部系统。ClaraVerse允许开发者通过“自定义技能”功能封装一个HTTP API或编写一段JavaScript代码作为新技能。一旦创建这个技能就能像内置技能一样在聊天、工作流等任何地方被调用。这是将企业内网服务AI化的强大入口。技巧3工作流的“子流程”与模块化对于复杂自动化不要试图在一个巨型工作流中完成所有事情。可以将可复用的逻辑如“数据清洗”、“发送通知”封装成独立的子工作流。然后在主工作流中通过“Execute Workflow”节点来调用。这提高了工作流的可维护性和复用性。生态展望MCP的潜力ClaraVerse对MCP协议的原生支持是一个极具前瞻性的设计。MCP正在成为连接AI与工具的事实标准。随着更多MCP服务器的出现用于连接数据库、云服务、设计工具等ClaraVerse只需通过Clara Companion就能轻松集成这些新能力而无需等待官方更新。这使它具备了成为一个“万能AI胶水”的潜力能够灵活适配快速变化的AI工具生态。最后的选择云、自托管还是桌面版云版 (claraverse.space)最适合想零成本、零运维快速体验全部功能的用户。隐私依靠项目的“零知识”架构保障。自托管Docker版适合注重数据完全主权、需要深度定制、或在内网环境使用的团队和个人。拥有最高的控制权和灵活性。桌面版 (Electron App)适合主要在本机使用、希望获得接近原生应用体验、且不想处理Docker的用户。它本质上打包了所有服务安装即用。从我个人的实践来看对于开发者或技术团队自托管Docker版是首选它能与本地开发环境深度集成。对于普通用户桌面版提供了最省心的体验。无论哪种方式ClaraVerse都提供了一个将强大AI能力私有化、流程化、场景化的优秀平台它让AI不再是玩具而是真正能融入日常工作流的生产力伙伴。