macOS 系统本地安装 openJiuwen 完整指南

本指南详细介绍在 macOS 系统中通过本地源码方式安装 openJiuwen 的完整流程，包含环境准备、依赖安装、系统部署及常见问题解决，适用于技术开发与测试人员参考。

先看效果

一、环境准备

请确保本地设备满足以下软硬件要求，避免安装过程中出现兼容性问题：

1. 硬件要求

CPU：最低 2 核，推荐 4 核及以上（确保服务运行流畅）
内存（RAM）：最低 4GB，推荐 8GB 及以上（支撑多服务同时启动）

2. 操作系统要求

macOS 14.0（Sonoma）及以上版本

3. 必备软件要求

以下软件需提前安装，具体安装步骤详见下文：

Git 2.40 及以上
Node.js 20.0 及以上（内置 npm，需满足 9.0 及以上）
Python 3.11.4 及以上
uv 0.5.0 及以上
MySQL 8.0 及以上
Milvus 2.6.2 及以上（可选，仅记忆功能依赖）

二、安装依赖软件

正式安装 openJiuwen 前，需先完成上述依赖软件的安装与验证，再执行后续源码获取和部署步骤。

1. 安装 Git

通过 Homebrew 安装 Git（未安装 Homebrew 需先执行安装命令）：

bash 复制代码

# 若未安装 Homebrew，先执行此命令安装（需网络通畅）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Git
brew install git

安装验证：打开终端，输入以下命令，若成功输出版本号则说明安装完成：

bash 复制代码

git --version

示例输出（版本号以实际安装为准）：

bash 复制代码

git version 2.39.5 (Apple Git-154)

2. 安装 Node.js 和 npm

通过官方安装包安装，步骤如下：

访问 Node.js 官网，下载 macOS 版本的 Node.js 20.0 及以上安装包；
双击安装包，按照向导提示完成安装（默认安装路径即可）。

安装验证：打开终端，分别执行以下命令，均能输出对应版本号则安装成功：

bash 复制代码

# 验证 Node.js 版本
node -v

# 验证 npm 版本
npm -v

示例输出：

bash 复制代码

v23.11.0  # node 版本输出
10.9.2    # npm 版本输出

3. 安装 Python 和 uv

（1）安装 Python

通过 Homebrew 安装 Python：

bash 复制代码

brew install python

安装验证：终端输入以下命令，输出版本号即成功：

bash 复制代码

python3 --version

示例输出：

bash 复制代码

Python 3.13.3

（2）安装 uv

通过 Homebrew 安装 uv 工具：

bash 复制代码

brew install uv

安装验证：终端输入以下命令，输出版本号即成功：

bash 复制代码

uv --version

示例输出：

bash 复制代码

uv 0.7.6 (Homebrew 2025-05-19)

4. 安装 MySQL

通过 Homebrew 安装并配置 MySQL，步骤如下：

bash 复制代码

# 若未安装 pkg-config，先执行此命令（依赖工具）
brew install pkg-config

# 安装 MySQL
brew install mysql

（1）启动 MySQL 服务

bash 复制代码

brew services start mysql

（2）登录 MySQL 并创建所需数据库

bash 复制代码

# 本地登录 MySQL（默认无密码，直接回车即可）
mysql -u root

登录成功后，执行以下 SQL 语句创建数据库和授权用户（your_user_name、your_password 替换为自定义用户名和密码）：

注意：密码若包含特殊字符，后续配置 .env 文件时需参考官方文档进行 URL 编码，避免连接失败。

sql 复制代码

-- 创建 openJiuwen 所需数据库
CREATE DATABASE openjiuwen_agent;
CREATE DATABASE openjiuwen_ops;

-- 创建本地用户并授权
CREATE USER 'your_user_name'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON openjiuwen_agent.* TO 'your_user_name'@'localhost';
GRANT ALL PRIVILEGES ON openjiuwen_ops.* TO 'your_user_name'@'localhost';

-- 刷新权限使配置生效
FLUSH PRIVILEGES;

示例（替换为自定义信息）：

sql 复制代码

CREATE DATABASE openjiuwen_agent;
CREATE DATABASE openjiuwen_ops;
CREATE USER 'jianguo'@'localhost' IDENTIFIED BY 'nutpi';
GRANT ALL PRIVILEGES ON openjiuwen_agent.* TO 'jianguo'@'localhost';
GRANT ALL PRIVILEGES ON openjiuwen_ops.* TO 'jianguo'@'localhost';
FLUSH PRIVILEGES;

5. 安装 Milvus（可选）

Milvus 是 openJiuwen 记忆功能的依赖组件，按需安装：

需体验记忆功能：参考如何启用记忆功能完成安装配置；
仅需基础功能：可直接跳过本步骤。

三、安装 openJiuwen 系统

1. 获取源码

openJiuwen 源码仓开源，无需额外权限，直接通过 Git 克隆：

提示：安装过程需多次执行 Git 操作，建议配置凭证存储，避免重复认证。

bash 复制代码

# 配置全局凭证存储（可选，推荐）
git config --global credential.helper store

# 克隆源码到本地
git clone https://atomgit.com/openJiuwen/agent-studio.git

# 进入源码根目录
cd agent-studio

2. 生成 AES 密钥（可选）

仅需对关键字段进行加密存储时执行此步骤，无需加密可跳过：

bash 复制代码

# 进入后端目录
cd backend

# 执行脚本生成 AES 密钥
bash build_AES_master_key.sh

脚本执行后会在终端输出密钥，建议作为环境变量保存（密钥需稳定，更换后已加密数据无法解密）：

bash 复制代码

export SERVER_AES_MASTER_KEY_ENV=your_aes_key  # 替换为实际生成的密钥

3. 配置并启动服务

（1）配置环境变量文件

复制示例配置文件并修改关键参数：

bash 复制代码

# 在源码根目录执行（若当前在 backend 目录，先执行 cd .. 返回）
cp .env.example .env

# 打开配置文件（默认使用系统文本编辑器）
open .env

在 .env 文件中修改以下核心变量（其他变量保持默认，勿随意修改）：

说明：DB_USER、DB_PASSWORD 需与前文创建的 MySQL 用户信息一致；若未安装 Milvus，记忆相关配置可忽略。

env 复制代码

# 数据库配置（必填）
DB_HOST=localhost       # 数据库主机地址（本地默认 localhost）
DB_PORT=3306            # 数据库端口（MySQL 默认 3306）
DB_USER=your_user_name  # 自定义 MySQL 用户名
DB_PASSWORD=your_password  # 自定义 MySQL 密码

# Milvus 配置（可选，启用记忆功能时必填）
MILVUS_HOST=127.0.0.1   # Milvus 服务地址
MILVUS_PORT=19530       # Milvus 默认端口
MILVUS_COLLECTION_NAME=memory_vector  # 向量集合名称

# 记忆功能相关配置（可选）
EMBEDDING_MODEL_DIMENTION=1024
EMBED_API_BASE=""
EMBED_MODEL_NAME=""
EMBED_API_KEY=""
EMBED_TIMEOUT=5
EMBED_MAX_RETRIES=1

核心变量说明：

变量名	说明	配置样例	必填性
DB_HOST	数据库主机地址	localhost	必填
DB_PORT	数据库端口号	3306	必填
DB_USER	数据库访问用户名	your_user_name	必填
DB_PASSWORD	数据库访问密码	your_password	必填
MILVUS_HOST	Milvus 服务地址	127.0.0.1	可选
EMBED_API_KEY	嵌入模型 API 密钥	sk-xxx	可选

（2）启动后端服务

打开新终端，进入源码根目录，执行以下命令：

bash 复制代码

# 进入后端目录
cd backend

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装后端依赖（耐心等待，若卡死或失败参考下方提示）
uv sync

常见问题解决：

uv sync 卡死超过 20 分钟：按 Ctrl + C 终止，修改 backend 目录下 pyproject.toml 文件中 [[tool.uv.index]] 的 url 为其他可用源，重新执行 uv sync；
uv sync 失败（HTTPS 兼容问题）：执行uv sync --native-tls 强制使用系统原生 TLS 库。

依赖安装完成后，启动后端服务：

bash 复制代码

# 创建日志目录
mkdir -p logs/run

# 启动后端服务
python main.py

提示：若执行 python main.py 时出现 "No Module named 'greenlet'" 错误，解决方案见本文第四部分 FAQ。启动成功后会输出 "Application startup complete"。如需启用插件，需参考如何启用沙箱功能配置沙箱服务。

（3）启动前端服务

打开新终端（后端服务终端保持运行），进入源码根目录，执行以下命令：

bash 复制代码

# 进入前端目录
cd frontend

# 安装前端依赖
npm install

说明：执行 npm install 时若出现 npm 官方已知漏洞提示，无需处理，不影响后续服务启动。

依赖安装完成后，启动前端服务：

bash 复制代码

npm run dev

启动成功后，终端会输出访问地址，示例：

bash 复制代码

Local:   http://localhost:5173/  # 本地访问地址
Network: http://192.168.1.100:5173/  # 局域网访问地址

4. 访问 openJiuwen 系统

本地访问：在终端中按住 Control 键单击本地访问地址，或复制地址到浏览器地址栏，按回车键即可打开系统界面；
局域网访问：在同一网络环境的其他设备上，复制网络访问地址到浏览器地址栏，按回车键访问。

四、常见问题（FAQ）

问题 1：启动后端时出现 "No Module named 'greenlet'" 如何解决？

原因：Apple Silicon 芯片的 macOS 系统中，Python 标准库可能缺失 greenlet 包，导致依赖加载失败。

解决方案：

bash 复制代码

# 1. 若当前处于虚拟环境，先退出
deactivate

# 2. 安装 greenlet 包
uv add greenlet

# 3. 重新激活虚拟环境并启动服务
source .venv/bin/activate
python main.py

关于 openJiuwen

openJiuwen 社区聚焦 AI Agent 通用平台能力，致力于构建易用、灵活且稳定的开源智能体平台，推动商用级 Agentic AI 技术广泛应用与落地。

基于该开源项目，开发者可以：

✨ 快速构建能处理各种复杂任务的智能体
🤖 实现多智能体协同交互
🏢 高效搭建企业级 AI Agent 系统
🎯 零编程基础也能上手使用

加入社区

🎉 欢迎加入 openJiuwen 开源社区，与全球开发者一起探索 AI Agent 的无限可能！

如果这个项目对你有帮助，欢迎：

⭐ 在各个代码仓库给我们点 Star，保持关注
💬 提交 Issue 或参与讨论
🤝 贡献代码，一起完善项目
📢 分享给更多对 AI Agent 感兴趣的朋友

让我们一起推动 AI Agent 技术的发展！

macOS 系统本地安装 openJiuwen 完整指南