Windows、macOS 和 Linux 用户安装指南

Windows、macOS 和 Linux 用户安装指南

点击查看如何安装 Agent Zero 的教学视频：

本用户指南提供了使用 Docker 安装并运行 Agent Zero 的详细步骤，Docker 是该框架的主要运行环境。对于开发者和贡献者，我们还提供了完整开发环境的安装指南。

Windows、macOS 和 Linux 安装步骤

1. 安装 Docker Desktop：

Docker Desktop 提供 Agent Zero 的运行环境，确保在各平台上一致的行为和安全性
整个框架运行在 Docker 容器中，具有良好的隔离性，便于部署
提供图形化界面，适用于所有主流操作系统

1.1 访问 Docker Desktop 下载页面。如果链接失效，可搜索 “docker desktop download”。

1.2 下载适合你操作系统的版本。Windows 用户点击主按钮下载 Intel/AMD 版本。

docker download

💡 注意： Linux 用户： 你可以安装 Docker Desktop 或 docker-ce（社区版）。

Docker Desktop 安装请参考各 Linux 发行版的官方说明：安装链接
docker-ce 安装请参考：安装链接

若你使用 docker-ce，请将当前用户加入 docker 用户组：
sudo usermod -aG docker $USER
退出登录后重新登录，再运行：
docker login

1.3 运行安装程序并选择默认设置。macOS 用户请将应用拖拽至 “Applications” 文件夹中。

docker install

1.4 安装完成后，启动 Docker Desktop：

docker installed

⚠️ 重要提示（macOS）： 在 Docker Desktop 的 “Settings → Advanced” 中启用 “Allow the default Docker socket to be used（需要密码）”。

docker socket macOS

2. 运行 Agent Zero：

💡 注：Agent Zero 还提供了基于 Kali Linux 的 Hacking Edition（黑客版），内置专为网络安全任务设计的 prompt。安装流程相同，仅需将镜像名替换为 frdel/agent-zero-run:hacking。

2.1 下载 Agent Zero 镜像：

在 Docker Desktop 中搜索 frdel/agent-zero-run
点击 Pull 按钮下载镜像，过程可能需数分钟

docker pull

💡 或者在终端执行以下命令：
docker pull frdel/agent-zero-run

2.2 创建本地数据目录：

创建或选择一个用于存储 Agent Zero 数据的文件夹，例如：
- C:/agent-zero-data 或 /home/user/agent-zero-data
此目录将包含以下结构和内容：
- /memory - 记忆与学习内容
- /knowledge - 知识库
- /instruments - 工具与函数
- /prompts - Prompt 文件
- /work_dir - 工作目录
- .env - API 密钥
- settings.json - Agent Zero 设置

💡 建议选择一个易于访问和备份的位置，所有 Agent Zero 数据将保存在此目录中。

2.3 启动容器：

在 Docker Desktop 中点击 “Images” 标签页
找到 frdel/agent-zero-run 镜像，点击 Run
打开 “Optional settings”
设置第二个 Host port 为 0（表示自动分配端口）

如需挂载本地文件夹用于数据持久化：

在 “Volumes” 中配置：
- Host path: 本地目录路径（如 C:\agent-zero-data）
- Container path: /a0

docker port mapping

点击 Run 启动容器，它将在 “Containers” 标签页中显示：

docker containers

💡 你也可以使用命令行启动容器：
docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run
替换 $PORT 为你想用的端口（如 50080）替换 /path/to/your/data 为你的数据目录路径

2.4 打开 Web UI：

容器启动几秒钟后，Docker 日志会显示系统初始化信息
在 Docker Desktop 中查看 <PORT>:80 映射的端口，点击端口号即可打开

docker logs

在浏览器访问 http://localhost:<PORT>
Web UI 打开后，Agent Zero 即可开始配置使用！

docker ui

💡 也可在 Docker Desktop 中点击容器 ID 下方的端口号访问 UI

📁 启动后，你的数据目录中会出现所有 Agent Zero 文件，直接编辑会实时生效

3. 配置 Agent Zero

请参考以下配置说明，完成 Agent Zero 的初始化设置：

设置界面详解

Agent Zero 提供了完整的设置界面，用于自定义系统行为。点击侧边栏中的齿轮图标即可进入。

Agent 配置项

Prompts 子目录： 指定 /prompts 中的子目录用于定义 agent 行为（如使用 default）
Memory 子目录： 自定义 agent 记忆存储路径，适合多实例隔离
Knowledge 子目录： 自定义知识文件路径，扩展 agent 知识

settings

Chat Model 聊天模型配置

Provider： 选择模型提供方（如 Ollama）
Model Name： 输入具体模型名（如 llama3.2）
Temperature： 控制回复的随机性（0 为确定性回复）
Context Length： 最大上下文长度
Context Window Space： 设置上下文用于聊天历史的比例

chat model settings

Utility Model 实用模型配置

适用于摘要、内存管理等任务，建议使用轻量模型以提升效率

Embedding Model 向量嵌入模型

用于生成记忆和知识库中的嵌入向量（如 text-embedding-3-small）

语音识别配置

Model Size： 选择语音识别模型体积
Language Code： 设置识别语言
Silence Settings： 配置静音阈值、超时和延时等参数

API 密钥配置

可直接在 Web UI 中设置所需服务的 API key
点击 Save 保存设置

认证配置

UI Login： 设置登录用户名
UI Password： 设置登录密码
Root Password： 设置容器 root 密码，用于 SSH

settings

开发设置

RFC（远程函数调用）： 本地实例间调用的配置，包括 URL、端口和密码详情可见：远程函数调用设置

⚠️ 重要提示： 请妥善保管你的 API 密钥和登录密码，防止泄漏

选择你的 LLM（大语言模型）

在设置页面中，你可以选择为不同角色配置不同的 LLM：

LLM 角色	说明
`chat_llm`	主聊天模型，用于生成回复
`utility_llm`	用于摘要、内存管理等内部任务
`embedding_llm`	用于生成向量嵌入，用于知识查找与记忆检索

更改方法：

打开 Web UI 中的设置页面
为每个角色选择模型提供者并输入模型名
点击 “Save” 应用更改

⚠️ 注意：更换 embedding_llm 会导致向量数据库需要重新索引，并需要清空 /memory 文件夹，否则会出错。此操作会删除所有 Agent Zero 的记忆数据。

安装并使用 Ollama（本地运行模型）

如果你希望在本地运行大型语言模型，可使用 Ollama 工具：

第一步：安装 Ollama

Windows： 从官网下载安装点击下载
macOS：

brew install ollama

或从官网下载页面

Linux：

curl -fsSL https://ollama.com/install.sh | sh

获取模型名：

访问 Ollama 模型库，查看模型及名称格式通常为 provider/model-name 或 model-name

第二步：拉取模型

ollama pull <model-name>

将 <model-name> 替换为所需模型名，例如：

ollama pull mistral-large

命令行提示下载完成后，模型即可使用

在 Agent Zero 中选择模型

下载完成后，打开 Agent Zero 的设置页面
在 Chat / Utility / Embedding 模型设置中选择 Provider 为 Ollama
输入模型名称（如 llama3.2 或 qwen2.5:7b）
点击 Save 保存设置

ollama

管理本地模型

列出所有模型：

ollama list

删除模型：

ollama rm <model-name>

尝试不同的模型组合，以在性能和成本之间找到最佳平衡。例如，选择更快、更低延迟的大语言模型（LLM），并使用 faiss_gpu 替代 faiss_cpu 以优化内存使用。

在手机设备上使用 Agent Zero

Agent Zero 的 Web UI 可通过 Docker 容器在局域网内任意设备访问：

Docker 容器会自动在所有网络接口上开放 Web UI。
在 Docker Desktop 中查看端口映射：
- 查看容器名称下的 <PORT>:80 格式
- 例如，若显示 32771:80，则端口为 32771
用下列方式访问 Web UI：
- 本地访问：http://localhost:<PORT>
- 局域网访问：http://<你的电脑IP>:<PORT>

💡 提示

通常你的电脑 IP 形式是 192.168.x.x 或 10.0.x.x
Windows 下用 ipconfig，Linux/macOS 用 ifconfig 查 IP
Docker 默认会自动分配端口，除非你手动指定

📝 注意如果你不是通过 Docker 而是直接在系统上运行 Agent Zero（传统方式），需要在 run_ui.py 中手动设置监听地址为 host="0.0.0.0" 才能对外开放访问。

完整本地运行方法详见完整二进制安装指南。

如何更新 Agent Zero

1. 从旧版本升级

你的数据会保存在 Agent Zero 文件夹内的多个子目录中。
若要从旧版本升级到 Docker 版本，请备份以下文件和目录：
- /memory：Agent 的记忆
- /knowledge：自定义知识库（如果你导入过）
- /instruments：自定义工具和函数（如果你创建过）
- /tmp/settings.json：配置文件
- /tmp/chats/：聊天记录
备份后，参考上方的安装指南重新安装新版 Docker 容器
将备份的数据拷贝到新的 Agent Zero 文件夹中，新版程序会自动加载这些数据

⚠️ 重要提示 如果设置无法加载，可以删除 /tmp/settings.json 文件重新生成聊天记录 /tmp/chats/ 在新版中可能不兼容，可酌情删除

2. Docker Desktop 升级流程

在 Docker Desktop 中停止容器（Containers 标签页）
右键点击容器选择“删除”
在“Images”标签页中删除旧镜像（frdel/agent-zero-run）

docker 删除镜像

搜索并拉取新镜像（如果删除了）
使用原来的数据卷路径重新运行新容器

⚠️ 确保使用相同的 volume 路径，以保留数据。路径取决于你保存 Agent Zero 数据的位置。

💡 终端更新命令如下：

# 停止旧容器
docker stop agent-zero
# 删除旧容器（数据安全）
docker rm agent-zero
# 删除旧镜像
docker rmi frdel/agent-zero-run
# 拉取新镜像
docker pull frdel/agent-zero-run
# 运行新容器，使用相同的数据卷
docker run -p $PORT:80 -v /path/to/your/data:/a0 frdel/agent-zero-run

3. 全量二进制安装（Full Binaries）

使用 Git/GitHub 拉取最新代码。
自定义知识、解决方案、记忆等数据不会被覆盖；.env 和 settings.json 也会保留。

⚠️ 手动更新注意事项：

保存好 .env 文件中的 API 密钥
查看是否有新的依赖项（requirements.txt 变化）
激活 a0 conda 环境后执行以下命令安装新依赖：

pip install -r requirements.txt

完整本地安装指南（Full Binaries）

Agent Zero 是一个框架，支持自定义开发和拓展，因此你需要安装必要的依赖。
这个指南配有视频教程，帮助你搭建完整的开发环境：点击观看视频教程

小贴士：

不需要单独安装 Python，Conda 会自动管理。
不一定需要 API key，Agent Zero 支持本地模型运行（默认使用 OpenAI API）。
推荐使用 VS Code 以便编辑文件，但不是必须。
不需要强制使用 Git，也可以直接下载源代码。
安装全量二进制版本时，不强制使用 Docker。Web UI 可通过 Docker 容器访问。
不使用 Docker 运行适合开发者和贡献者，过程更复杂。

⚠️ Linux 用户注意： 非 Debian/Ubuntu 发行版用户请根据自己系统调整命令。Debian/Ubuntu 可参考 macOS 安装步骤。

1. 安装 Conda（miniconda）

Conda 是 Python 环境管理工具，方便隔离不同项目的依赖。
推荐安装 Miniconda（轻量版），只包含基础包。

步骤：

访问 Miniconda 下载页：https://docs.anaconda.com/miniconda/#miniconda-latest-installer-links
根据操作系统下载合适的安装包（macOS 推荐 .pkg，Windows 为 .exe）。
运行安装程序，默认配置下一步完成安装。
安装后，打开终端（Windows 打开 “Anaconda Powershell Prompt”），输入 conda --version 验证安装。

2. 下载 Agent Zero 代码

访问 Agent Zero Releases
下载最新版本的 Source Code (zip)
解压到你想存放的目录，如：
- Windows: C:\Users\你的用户名\Desktop\agent-zero
- macOS: /Users/你的用户名/Desktop/agent-zero

3. 创建并激活 Conda 环境，安装依赖

打开终端（Anaconda Powershell Prompt / Terminal）：

# 进入 agent-zero 目录
cd /path/to/agent-zero
# 创建环境，命名为 a0，安装 Python 3.12
conda create -n a0 python=3.12 -y
# 激活环境
conda activate a0
# 安装依赖
pip install -r requirements.txt

注意：每次新开终端都要执行 conda activate a0 激活环境。
安装依赖时如遇版本冲突，确认环境已激活且 Python 版本正确。

4. 安装 Docker Desktop

访问 Docker Desktop 下载
下载安装对应你操作系统的版本（Windows/macOS）
完成安装后启动 Docker Desktop，登录或创建 Docker Hub 账号
macOS 用户请在 Docker 设置 -> Advanced 中勾选 “Allow the default Docker socket to be used (requires password)”

5. 运行 Agent Zero Web UI

在 Conda 激活的环境终端中，运行：

python run_ui.py

终端会显示 Web UI 地址，如 http://localhost:port
在浏览器打开该地址，访问 Agent Zero 界面

6. 配置 Agent Zero（选择模型、API Key 等）

进入 Web UI 的设置页面，配置你的模型、API 密钥等
详细配置参考官方 Usage 文档

7. 配置 Agent Zero RFC（远程函数调用）

在本地 Agent Zero Web UI 中，设置：
- RFC Destination URL: http://localhost
- HTTP 和 SSH 端口填你 Docker 容器时映射的端口（如 55022）
在 Docker 容器中的 Agent Zero Web UI 中，设置访问密码（同 Docker 容器密码）
保存后启用开发环境，完成开发环境配置

额外说明

Docker 容器运行命令示例（需替换 /path/to/your/data）：

docker run -p 55022:55022 -p 0:80 -v /path/to/your/data:/a0 frdel/agent-zero-run

如果之前安装过 Agent Zero，更新时请备份以下目录：
```
/memory
/knowledge
/instruments
/tmp/settings.json
/tmp/chats/
```
如遇配置加载问题，删除 /tmp/settings.json 及聊天记录让系统重新生成。

结语

完成上述步骤后，Agent Zero 即安装成功并运行，你可以开始尝试自定义智能体或开发新功能。过程中如遇问题，欢迎参考官方文档，或者加入官方 Skool 与 Discord 社区寻求帮助。