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

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

一、它是做什么的？

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

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

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

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

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，执行业务逻辑

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 虚拟形象渲染

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

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

关键配置项

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 版本硬约束

5.2 Neo4j 数据库依赖

5.3 API Key 安全

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

六、行业意义与趋势

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

社区活跃度

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

一、它是做什么的？

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

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

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

3.2 GRAG 知识图谱记忆系统

3.3 Live2D 虚拟形象渲染

3.4 语音交互（Edge TTS + FunASR）

3.5 MCP（Model Context Protocol）工具生态

3.6 Electron + Vue3 桌面客户端

四、如何快速上手？

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

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

关键配置项

五、局限与挑战

5.1 Python 3.11 版本硬约束

5.2 Neo4j 数据库依赖

5.3 API Key 安全

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

六、行业意义与趋势

社区活跃度

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

一、它是做什么的？

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

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

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

3.2 GRAG 知识图谱记忆系统

3.3 Live2D 虚拟形象渲染

3.4 语音交互（Edge TTS + FunASR）

3.5 MCP（Model Context Protocol）工具生态

3.6 Electron + Vue3 桌面客户端

四、如何快速上手？

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

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

关键配置项

五、局限与挑战

5.1 Python 3.11 版本硬约束

5.2 Neo4j 数据库依赖

5.3 API Key 安全

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

六、行业意义与趋势