开源 AI Agent 实战：openJiuwen macOS 部署教程

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

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

先看效果

image-20251229220218624

image-20251229220218624

一、环境准备

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

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 需先执行安装命令）：

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

# 安装 Git
brew install git

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

git --version

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

git version 2.39.5 (Apple Git-154)

2. 安装 Node.js 和 npm

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

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

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

# 验证 Node.js 版本
node -v

# 验证 npm 版本
npm -v

示例输出：

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

3. 安装 Python 和 uv

（1）安装 Python

通过 Homebrew 安装 Python：

brew install python

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

python3 --version

示例输出：

Python 3.13.3

（2）安装 uv

通过 Homebrew 安装 uv 工具：

brew install uv

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

uv --version

示例输出：

uv 0.7.6 (Homebrew 2025-05-19)

4. 安装 MySQL

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

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

# 安装 MySQL
brew install mysql

（1）启动 MySQL 服务

brew services start mysql

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

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

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

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

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

-- 创建本地用户并授权
CREATEUSER'your_user_name'@'localhost'IDENTIFIEDBY'your_password';
GRANTALLPRIVILEGESON openjiuwen_agent.* TO'your_user_name'@'localhost';
GRANTALLPRIVILEGESON openjiuwen_ops.* TO'your_user_name'@'localhost';

-- 刷新权限使配置生效
FLUSHPRIVILEGES;

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

CREATE DATABASE openjiuwen_agent;
CREATEDATABASE openjiuwen_ops;
CREATEUSER'jianguo'@'localhost'IDENTIFIEDBY'nutpi';
GRANTALLPRIVILEGESON openjiuwen_agent.* TO'jianguo'@'localhost';
GRANTALLPRIVILEGESON openjiuwen_ops.* TO'jianguo'@'localhost';
FLUSHPRIVILEGES;

5. 安装 Milvus（可选）

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

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

三、安装 openJiuwen 系统

1. 获取源码

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

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

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

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

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

2. 生成 AES 密钥（可选）

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

# 进入后端目录
cd backend

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

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

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

3. 配置并启动服务

（1）配置环境变量文件

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

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

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

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

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

# 数据库配置（必填）
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

核心变量说明：

（2）启动后端服务

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

# 进入后端目录
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 库。

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

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

# 启动后端服务
python main.py

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

（3）启动前端服务

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

# 进入前端目录
cd frontend

# 安装前端依赖
npm install

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

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

npm run dev

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

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 包，导致依赖加载失败。

解决方案：

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

# 2. 安装 greenlet 包
uv add greenlet

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

关于 openJiuwen

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

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

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

相关资源

官方链接

• 官网：https://www.openjiuwen.com
• 代码仓库：https://atomgit.com/openJiuwen

核心组件仓库

openJiuwen 项目由三大核心组件构成：

• Agent Studio（智能体工作室）：https://atomgit.com/openJiuwen/agent-studio 可视化智能体开发平台，提供拖拽式编排能力
• Agent Core（智能体核心）：https://atomgit.com/openJiuwen/agent-core 智能体运行引擎，负责任务编排和执行
• Agent Protocol（智能体协议）：https://atomgit.com/openJiuwen/agent-protocol 标准化通信协议，实现多智能体协同

文档中心

• MacOS 系统安装指南[4]
• 完整文档[5]

加入社区

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

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

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

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

参考资料

[1]

Node.js 官网: http://nodejs.cn/download/

[2]

如何启用记忆功能: https://www.openjiuwen.com/docs-page?path=2.安装指导/本地安装/MacOS系统安装&version=openJiuwen_v0.1.1#macos-memory

[3]

如何启用沙箱功能: https://www.openjiuwen.com/docs-page?path=2.安装指导/本地安装/MacOS系统安装&version=openJiuwen_v0.1.1#macos-sandbox

[4]

MacOS 系统安装指南: https://www.openjiuwen.com/docs-page?path=2.安装指导/本地安装/MacOS系统安装&version=openJiuwen_v0.1.1

[5]

完整文档: https://www.openjiuwen.com/docs-page