NagaAgent——让你的AI助手拥有二次元灵魂

一、它是做什么的？

想象一下，当你打开电脑，一个活灵活现的二次元少女形象出现在桌面上——她叫娜杰日达（娜迦），不仅能听你说、和你聊，还能记住你们的每一次对话，用知识图谱构建你们的"共同记忆"，同时调用各种工具帮你完成任务。这就是 NagaAgent——一个将大语言模型能力封装为可交互、可定制、有灵魂的本地AI助手的开源项目。

它不是简单的聊天机器人，而是一个功能完整的多模态AI助手框架：流式对话输出、Live2D虚拟形象实时渲染、语音合成（TTS）和语音识别（ASR）、Neo4j图数据库驱动的长期记忆系统、OpenClaw驱动的多工具调用（浏览器自动化、天气查询、游戏攻略等），以及完整的 Electron 桌面客户端。截至2026年6月，项目在GitHub上已获得1524 Stars，版本迭代至5.1.0，是中文开源AI助手领域的活跃代表。

二、为什么会出现这个项目？

2024-2025年，随着GPT-4、Claude等大语言模型的崛起，AI助手的概念从"问答机器人"进化为"能执行任务的智能体"（Agent）。但当时的AI助手存在几个痛点：

交互体验单一。 大多数AI助手是网页或命令行界面，缺乏情感化的交互载体。Live2D技术早已在虚拟主播（VTuber）领域广泛应用，但与AI助手结合的产品极少。

记忆能力薄弱。 现有AI助手普遍只有"上下文窗口"级别的短期记忆，无法构建用户的长期兴趣图谱。当对话超过上下文限制后，AI就会"失忆"。

工具调用门槛高。 虽然OpenAI在2023年底推出了Function Calling（函数调用）功能，但普通用户要自行搭建一套支持流式工具调用的Agent系统，门槛依然很高。

NagaAgent的作者「柏斯阔落」是一个B站up主（uid: 266938091），同时维护着另一明星项目 openclaw（37.8万星），后者是一个开源的通用AI Agent框架。NagaAgent可以看作是用 openclaw 作为底层引擎，搭配 Live2D 形象界面、GRAG记忆系统和中文社区生态，专为普通用户打造的个人AI助手产品。项目的双许可证策略（AGPL-3.0开源 + 商业闭源授权）也体现了作者的商业化意图。

三、核心功能：技术细节一览

3.1 流式工具调用引擎（OpenClaw Agent）

NagaAgent的Agent核心运行在 agentserver/ 目录下，核心引擎来自 openclaw 项目。agentic_tool_loop.py 实现了多轮工具调用循环：

# apiserver/agentic_tool_loop.py（推测结构）
async def run_tool_loop(messages, tools, max_iterations=5):
    response = await llm.chat(messages, tools=tools, stream=True)
    async for chunk in response:
        yield chunk  # 流式输出
        # 解析 tool_call，执行业务逻辑

支持 OpenAI API 格式和 Anthropic API 格式两种调用方式，通过配置文件的 api_format 字段切换。五元组提取器（意图/主体/行为/对象/条件）负责从用户输入中解析结构化意图。

3.2 GRAG 知识图谱记忆系统

项目名中的"GRAG"即 Graph Retrieval-Augmented Generation——用图数据库增强的 RAG 系统。记忆层架构采用 Neo4j 图数据库 + ChromaDB 向量数据库 双轨设计：

• Neo4j 存储实体节点（三元组：主体-关系-客体），支持多跳推理查询
• ChromaDB 存储语义向量，支持相似性检索
• 配置示例（config.json.example）：

"grag": {
    "enabled": true,
    "neo4j_uri": "neo4j://127.0.0.1:7687",
    "neo4j_password": "your_password",
    "context_length": 5
}

自动从对话历史中提取实体关系，注入后续对话上下文。2026年4月的更新还实现了"云端记忆优先"策略，优先使用远程Neo4j，回退本地。

3.3 Live2D 虚拟形象渲染

ui/live2d_local/ 目录包含 Live2D Cubism 模型（.model3.json）和渲染引擎。默认模型为"kasane_teto"（重音テト）。通过 live2d.py 驱动口型同步（读取 TTS 音频触发唇形动画）和表情变化。渲染层基于 Web（Electron 内嵌 Chromium），动画持续时间可配置（默认600ms）。

3.4 语音交互（Edge TTS + FunASR）

• TTS：集成 Edge TTS（微软Azure语音），默认使用中文女声 zh-CN-XiaoxiaoNeural，支持语速/格式/语言配置
• ASR：集成 FunASR（阿里达摩院开源语音识别）本地模型 SenseVoiceSmall，配合 Silero VAD 做端点检测，实现在本地完成语音转文字，无需上传音频

3.5 MCP（Model Context Protocol）工具生态

mcpserver/ 目录下实现了多个 MCP 工具插件：

MCP 工具	功能描述
agent_weather_time	天气查询与时间信息
agent_screen_vision	屏幕视觉感知（游戏画面识别）
agent_game_guide	游戏攻略助手（配合 MAA 自动操作）
agent_open_launcher	应用启动器
mcp_registry	MCP 服务注册与发现

MCP Server 监听 8003 端口，通过 WebSocket 与 Agent 引擎通信。

3.6 Electron + Vue3 桌面客户端

前端基于 Electron + Vue 3，使用 electron-builder 打包。PyInstaller 编译 Python 后端，生成跨平台可执行文件：

• Windows: .exe 安装包
• macOS: .dmg 安装包（支持 Apple Silicon 和 Intel）
• Linux: AppImage

运行时自动检测用户是否全局安装了 openclaw，若无则使用内置预装版本。

四、如何快速上手？

推荐系统要求： Python 3.11（必须是3.11，不支持其他版本）、4GB+ RAM、2GB+ 磁盘空间。

方式一：直接运行源码（开发者模式）

git clone https://github.com/RTGS2017/NagaAgent.git
cd NagaAgent

# 安装 uv（推荐）或 pip
pip install uv
uv sync

# 准备 Neo4j 数据库（Docker 方式）
docker run -d -p 7474:7474 -p 7687:7687   -e NEO4J_AUTH=neo4j/your_password neo4j:5

# 复制并编辑配置
cp config.json.example config.json
# 编辑 config.json 填入 API Key 和 Neo4j 密码

# 启动后端 API 服务
python main.py

# 启动 Electron 前端（新终端）
cd frontend && npm install && npm run dev

方式二：使用预编译包（普通用户）

前往 GitHub Releases 下载对应平台的安装包（Windows .exe 或 macOS .dmg），安装后首次启动向导会引导配置 API Key 和 Neo4j 连接信息。打包版本内置了 OpenClaw 运行时，无需额外安装 Node.js。

关键配置项

config.json 中的核心配置：

配置项	说明	推荐值
api.api_key	LLM API Key	必填
api.base_url	API 端点	默认 DeepSeek
api.model	模型名称	deepseek-v3.2
grag.neo4j_password	Neo4j 密码	必填
live2d.enabled	启用 Live2D	true
voice_enabled	启用语音	true

五、局限与挑战

5.1 Python 3.11 版本硬约束

项目 requires-python = ">=3.11,<3.12"，这是一个非常严格的版本限制。Python 3.12 已发布一年多，大量新特性和性能改进无法享受。依赖链中可能有 C 扩展包（如 py2neo）绑定了 CPython 3.11 ABI，这是主要原因。解决方案： 使用 pyenv 或 conda 管理多 Python 版本环境。

5.2 Neo4j 数据库依赖

GRAG 记忆系统的核心依赖 Neo4j 图数据库。对于普通用户而言，搭建和运维 Neo4j 有一定门槛。虽然 ChromaDB 是纯 Python 向量库（pip 安装即可），但项目强制 grag.enabled: true，无法完全绕过 Neo4j。这实际上增加了部署复杂度。

5.3 API Key 安全

配置文件中需要填写 API Key（OpenAI/Anthropic/DeepSeek等）。虽然支持 applied_proxy 配置 API 代理，但如果用户将配置文件意外提交到公开仓库，API Key 存在泄露风险。项目应考虑增加 .gitignore 之外的加密存储机制。

5.4 双许可证的法律模糊地带

AGPL-3.0 + 商业闭源许可证的双轨模式在开源社区存在争议。AGPL-3.0 要求衍生作品也必须开源，如果用户基于 NagaAgent 开发了自己的 Agent 系统，是否需要开源存在法律模糊性。商业授权需联系作者书面申请，透明度有限。

六、行业意义与趋势

NagaAgent 代表了一个新兴的产品方向：情感化 AI 助手。2024-2026年，随着 Live2D 开源工具的成熟和 AI 模型能力的爆发，"二次元 AI 助手"从极客玩具逐渐走向普通用户的桌面。

从技术架构看，NagaAgent 的核心价值在于集成而非原创——它将 openclaw（Agent引擎）、Live2D（虚拟形象）、Neo4j（知识图谱）、Edge TTS（语音合成）、FunASR（语音识别）等多个开源组件有机组合，形成了体验完整的产品。这种"组装式AI产品"思路正在成为趋势，降低了普通用户使用 AI 能力的门槛。

项目面临的挑战也很明显：多依赖带来的部署复杂度、与商业化产品的竞争（豆包、Kimi等）、以及如何保持长期活跃的开发更新。对于有技术背景、追求本地部署和定制化的用户，NagaAgent 是一个值得深入研究的优秀样本。

---

报告生成时间：2026-06-13 | 数据来源：GitHub API + 源码分析 | 项目版本：v5.1.0