如何在 Mac 上本地运行 Agent Zero

Agent Zero 是一个开源智能体框架，运行在 Docker 容器中，通过 Web 界面操作。本文介绍如何在 Mac 上本地运行 Agent Zero，无论是在自己的电脑上，还是在云端的独享 Mac 上。

Agent Zero 如何运行

项目地址是 github.com/agent0ai/agent-zero。与终端编程智能体不同，Agent Zero 是一个完整的环境：智能体、工具和 Web 界面都在同一个容器里运行，智能体还可以在容器中执行代码。文档中的三点决定了下文的所有配置：

• 它运行在 Docker 中。README 称只要能运行 Docker 的地方就能运行它。
• Web 界面使用容器的 80 端口。你可以把它映射到任意主机端口。
• 数据保存在 /a0/usr。这是唯一需要持久化的路径。

Agent Zero 是独立项目，Hatmac 与其没有任何关联。

Apple silicon 上的 Docker

Agent Zero 的安装指南以 macOS 上的 Docker Desktop 为准，并涵盖 Apple silicon。

• Docker Desktop。从 Docker 安装页面 下载 Apple silicon 版本。Docker 支持当前及前两个 macOS 大版本，要求至少 4GB 内存。部分可选工具需要 Rosetta 2，建议安装：softwareupdate --install-rosetta。Agent Zero 的指南还要求在 Settings 的 Advanced 中启用 “Allow the default Docker socket to be used”。注意 Docker 的许可条款：较大企业的商业使用需要付费订阅。
• Colima。支持 Apple silicon 的命令行替代方案。用 brew install colima docker 安装，并分配足够内存启动虚拟机，例如 colima start --cpu 4 --memory 8。Agent Zero 的文档没有涉及 Colima，因此访问主机服务等细节可能与 Docker Desktop 不同。

在无显示器的云端 Mac 上，Docker Desktop 需要在图形会话中完成一次初始设置，可以通过屏幕共享或其他远程桌面完成。各种方式见 如何访问远程 Mac。

如何在 Mac 上本地运行 Agent Zero

官方文档提供两种方式。

安装脚本

curl -fsSL https://bash.agent-zero.ai | bash

快速入门文档说明，该脚本会检测 Docker、拉取镜像并创建容器，过程中会询问端口和认证设置，最后打印 Web 界面地址。和任何安装脚本一样，执行前先读一遍内容。

直接使用 Docker

如果 Docker 已在运行，README 给出了这条命令：

docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero

在可从互联网访问的 Mac 上，请改两处：使用一个高位端口，并绑定到 localhost，让本机以外无法访问：

docker run -d --name agent-zero \
  -p 127.0.0.1:5080:80 \
  -v a0_usr:/a0/usr \
  agent0ai/agent-zero

然后打开 http://localhost:5080。-d 让容器在后台运行，这里不需要 tmux。即使删除或重建容器，命名卷中的数据也会保留。

接入模型：Ollama 或 API

Agent Zero 需要一个主对话模型，以及一个处理记忆等内部任务的辅助模型。文档建议主模型要强、辅助模型要快，并提醒过小的模型（约 4B）往往无法胜任辅助任务。

云端 API

在 Web 界面的设置中填写密钥并保存。对于兼容 OpenAI 的服务商，在 External Services 的 Other OpenAI-compatible API keys 中添加密钥，再选择 OpenAI Compatible 作为服务商。文档特别指出，ChatGPT Plus 订阅不包含 API 额度。

用 Ollama 运行本地模型

在 macOS 上直接运行 Ollama，而不是放进容器，这样它才能通过 Metal 使用 Apple silicon 的 GPU。

brew install ollama
ollama serve
# 在另一个终端中
ollama pull qwen2.5:7b

在 Agent Zero 设置中选择 Ollama 作为服务商并填写模型名称。默认情况下，Agent Zero 会通过 http://host.docker.internal:11434 访问 Ollama，这个地址可以从容器内部连到主机。只有当 Ollama 运行在其他位置时才需要修改。想长期运行 Ollama，可参考 把 Ollama 作为 Mac mini 服务器运行。文档还提到 oMLX，可在 macOS 15 及以上的 Apple silicon 上作为本地模型方案。

数据持久化与更新

• 只映射 /a0/usr。文档警告不要映射整个 /a0 目录，因为其中包含应用代码，可能导致升级失败。
• 使用命名卷或文件夹。-v a0_usr:/a0/usr 把数据保存在 Docker 卷中，删除容器后数据依然存在。
• 在界面中更新。推荐路径是 Settings、Update、Self Update。手动方式是：拉取最新镜像，在另一个端口启动新容器，从旧实例备份，再恢复到新实例，确认无误后删除旧容器。
• 快照不等于备份。Agent Zero 的 Time Travel 会为 /a0/usr 中的工作区创建快照，但 README 说明它不能替代 Git 或备份。代码请推送到远程仓库，并备份数据卷。

跨大版本升级时，可能需要走备份恢复流程，而不是使用应用内更新。升级前请先查看安装指南。

加固 Web 界面

Agent Zero 可以执行代码、浏览网页。任何能访问其 Web 界面的人都能操控它，请把它当作 root shell 来对待。

1. 设置登录。在 Settings 的 Authentication 中设置 UI Login 和 UI Password。文档要求在建立任何隧道之前完成这一步。
2. 绑定到 localhost。按上文使用 -p 127.0.0.1:5080:80，不要在公网机器上直接使用 -p 80:80。
3. 通过 SSH 访问。在你的笔记本上运行：

ssh -N -L 5080:127.0.0.1:5080 you@your-mac

然后在本地浏览器打开 http://localhost:5080。流量在 SSH 内传输，端口不会对互联网开放。Ollama 也保持默认的本地地址，不要把 11434 端口开放到网络上。

资源需求与套餐选择

内存由 macOS、Docker 虚拟机、Agent Zero 容器和本地模型共同使用。模型在哪里运行，决定了该选哪个套餐。

使用方式	大致适配
只用云端 API 模型	Mac mini M4 或 M6，16GB
本地小型辅助模型 + 云端主模型	Mac mini M6，24GB
约 30B 级别的本地模型	Mac Studio M5 Max，36GB
70B 级别的本地模型	Mac Studio M5 Ultra，96GB

以上依据一个简单的经验法则：4-bit 量化模型每十亿参数大约需要 0.5–0.7 GB 内存，另需为上下文留出空间；macOS 默认允许 GPU 使用大约三分之二到四分之三的统一内存。在此之上还要为 Docker 虚拟机留出几 GB。Agent Zero 文档指出 70B 级模型或强大的云端模型效果最好，因此完全本地化的方案自然首选 Mac Studio M5 Ultra。更多细节见 本地大模型与 Apple silicon 内存。

价格为每台机器起始配置的美元月费。需要更多内存、存储或多台机器？联系我们。

Agent Zero 只是可以托管在独享 Mac 上的众多智能体之一。可在 在 Mac mini 上运行 AI 智能体 中比较不同方案，或查看 在 Mac mini 上运行 Claude Code 了解终端智能体。需要比标准配置更多的内存？告诉我们你的需求。