Agent Zero：可自我进化的开源个人 AI Agent 操作系统｜部署与使用全指南
定位一句话：Agent Zero 是一个完全透明、可运行代码、能联网与操控本机的通用个人 AI Agent「操作系统」——它把一台完整的 Linux 桌面、浏览器、终端与文件环境交给你的人工智能助手，自带工具与持久记忆，并能在使用中不断学习、自我进化。
当前版本：v0.9.6（2025-09-19 发布），仓库持续活跃维护（2025-11 仍有提交）。 许可证：MIT（可商用、可修改、可再分发）。 官网/文档：https://agent-zero.ai ｜ GitHub：https://github.com/agent0ai/agent-zero
⚠️ 链接勘误（重要）：本教程原始需求中给出的两个链接均已失效/错位，撰写时以项目真实当前状态为准： -
https://github.com/AgentZero-ai/AgentZero→ 404。Agent Zero 已被官方迁移到新命名空间agent0ai/agent-zero（早期也曾用frdel/agent-zero）。 -https://agentzero.readthedocs.io→ 那是另一个完全不同的项目（一个名为 AgentZero 的 ZeroMQ socket 管理 Python 库 v0.4.3），与 AI Agent 无关。Agent Zero AI 的官方文档在 https://agent-zero.ai/p/docs/。 下文所有链接、命令、参数均基于agent0ai/agent-zero的真实文档与源码。
一、项目简介与适用场景
Agent Zero 不是一个「只会聊天的机器人」，而是一个把计算机本身当作工具的开放式 Agent 工作平台。它的核心理念来自官方标语：Give your agent a full Linux computer.（给你的 Agent 一台完整的 Linux 计算机）。
它运行在一个 Docker 容器内，容器里是一套真实的 XFCE Linux 桌面 + 浏览器 + 终端 + LibreOffice 办公套件。你通过网页 UI（Web UI）下达任务，Agent 自己写代码、执行命令、上网搜索、操作文件、驱动 GUI 软件，并把学到的经验存进持久记忆，下次用得更好。
与「预设式 Agent 框架」的区别：Agent Zero 没有把工具写死。默认工具只有四类——联网搜索、记忆、通信（与你及其他 Agent）、代码/终端执行。其余能力（画图、爬网页、处理表格、调外部 API）都由 Agent 自己用代码现写，或由你通过插件/MCP/A2A 扩展。
典型适用场景：
不适合的场景：需要 100% 可控、不可执行任意代码的封闭环境；对「AI 自主执行命令」零容忍的高敏生产系统（除非先做隔离，见第十一章）。
二、核心功能逐条拆解
以下是 Agent Zero v0.9.x 已具备的核心能力，逐条说明。
2.1 完整 Linux 桌面（Canvas 中的 XFCE）
Agent Zero 在容器里运行一个真实 XFCE 桌面会话。你可以让 Agent 打开 Blender 这类 GUI 软件、用终端敲命令、用文件管理器整理资料，整个过程你能在「Desktop」画布里实时观看。
2.2 带 DOM 标注的内置浏览器
内置浏览器支持标注模式：你点击页面上的元素，Agent 会把它转成 inspect（审查）/ change（修改）/ lift（抽取）/ review（评论）指令，再据此修改你的项目。比纯文本描述页面精准得多。
2.3 实时文档协作
支持 Markdown 实时协作编辑器，以及通过 LibreOffice 驱动的 Writer（文档）/ Calc（表格）/ Impress（演示）。Agent 可以创建、更新、保存并验证这些文件，你也能手工同时编辑。
2.4 插件中心（Plugin Hub）
可安装 100+ 社区插件，或发布自己的扩展。插件能添加工具、面板、自动化助手与记忆后端。安装前请读插件的说明、README、权限与源码链接——它们和你工作区里跑的其他代码一样需要信任。
2.5 项目与记忆隔离
「项目（Projects）」给每次对话独立的世界：自己的文件、指令、密钥、记忆、仓库与模型预设。Agent 的持久记忆让它记住过往的解决方案、代码片段、事实与指令，越用越聪明。
2.6 宿主机桥接（A0 CLI）
默认 Agent 与你的电脑是分开的。安装 A0 CLI 后，Agent 能申请访问你本机文件、在宿主机终端执行命令、使用你的浏览器配置（Bring Your Own Browser）。
2.7 多 Agent 协作
主 Agent 可以派生子 Agent（subordinate agents）去调研、编码、分析或审查某个细分任务，再汇总回报。适合研究、Code Review、对比与并行工作。
2.8 透明且可扩展
提示词、工具、插件、技能、设置全部可查看与编辑。支持 MCP（Model Context Protocol）、A2A（Agent-to-Agent）、自定义工具与 Instruments（可调用函数）。
2.9 记忆管理面板
专门的 Memory 面板可搜索、审查、编辑、复制、删除记忆条目，支持按目录、区域过滤、匹配阈值与结果上限调节。
2.10 时间旅行（Time Travel）
对 /a0/usr 工作区提供快照历史、差异对比与回滚（非 Git 替代），可在误操作前看清「改了什么」。
2.11 语音接口
内置 _kokoro_tts（容器侧语音合成）与 _whisper_stt（本地 Whisper 转写），以及浏览器原生 speechSynthesis 兜底；任何语音路径都不依赖 OpenAI API。
2.12 技能 / Agent Profile / 模型预设
Skills：可加载的聚焦指令，可钉在当前对话。
Agent Profiles：切换角色、语气与系统提示（如「金融分析」专家）。
Model Presets：如
Best / Balanced / Fast Cheap的模型快捷组合。
三、全套官方链接
注：需求中给出的
https://agentzero.readthedocs.io指向一个无关的 ZeroMQ 库，请勿使用。
四、硬件与环境前置要求
Agent Zero 的主体运行在一个 Docker 容器内，因此Docker 是硬性前置；源码方式也仍依赖 Docker 来提供代码执行沙箱与浏览器。
最小可行清单：一台装好 Docker 的机器 + 一个 LLM API Key（或本地 Ollama）+ 浏览器。
五、多平台部署实战
Agent Zero 提供四条部署路径，按便利度排序：Launcher（桌面）＞ A0 Install（终端脚本）＞ 直接 Docker ＞ 源码/venv（高级）。
5.1 Windows 部署
方式 A：Launcher（推荐） 1. 下载 a0-launcher-1.9-windows-x64.exe（或 ARM64 版）：https://github.com/agent0ai/a0-launcher/releases/download/v1.9/a0-launcher-1.9-windows-x64.exe 2. 先安装 Docker Desktop for Windows，用默认设置安装并启动。 3. 运行 Launcher → 按引导 Download / Run Agent Zero → 选 latest → Create → 等状态变 Running → 点 Open UI。
方式 B：A0 Install（PowerShell）
irm https://ps.agent-zero.ai | iex
无桌面/服务器环境用 Quick Start（后台单实例，端口 5080）：
& ([scriptblock]::Create((irm https://ps.agent-zero.ai))) -QuickStart -Name agent-zero -Port 5080
方式 C：直接 Docker
docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
5.2 Linux 部署
方式 A：A0 Install（终端）
curl -fsSL https://bash.agent-zero.ai | bash
服务器/无桌面 Quick Start：
curl -fsSL https://bash.agent-zero.ai | bash -s -- --quick-start --name agent-zero --port 5080
方式 B：直接 Docker
# 若用 docker-ce，先把当前用户加入 docker 组（需注销重登）
sudo usermod -aG docker $USER
# 拉取并运行（数据持久化到命名卷 a0_usr）
docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
打开 http://localhost（或 http://<服务器IP>）完成 LLM 配置。
方式 C：Launcher（Linux 桌面） 下载 a0-launcher-1.9-linux-x64.AppImage（或 ARM64），赋予可执行权限后运行：
chmod +x a0-launcher-1.9-linux-x64.AppImage
./a0-launcher-1.9-linux-x64.AppImage
5.3 macOS 部署
安装 Docker Desktop for macOS；Apple Silicon 选 Apple Silicon 版。
Docker Desktop → Settings → Advanced，勾选 Allow the default Docker socket to be used (requires password)（macOS 必需）。
Launcher：下载
a0-launcher-1.9-macos-x64.dmg或a0-launcher-1.9-macos-arm64.dmg拖入 Applications。或终端 A0 Install：
curl -fsSL https://bash.agent-zero.ai | bash
5.4 Docker 部署（通用，含持久化与自定义端口）
基础运行（容器 80 端口映射到宿主机 80）：
docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero
自定义宿主机端口（例如 5080）：
docker run -d -p 5080:80 -v /path/to/local/folder:/a0/usr --name agent-zero agent0ai/agent-zero
注意：只映射
/a0/usr这一个干净目录，而不要映射整个/a0，升级时才安全。升级前务必先备份。
5.5 源码 / Python venv 安装（高级）
适合二次开发、离线构建或无法用安装脚本的场景。Agent Zero 主体仍跑在容器里，venv 主要用于本地开发调试 run_ui.py；代码执行沙箱与浏览器仍需 Docker。
# 1. 克隆
git clone https://github.com/agent0ai/agent-zero.git
cd agent-zero
# 2. 创建并激活虚拟环境（推荐 Python 3.11/3.12）
python3.11 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. 安装依赖
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements2.txt # 开发/附加依赖
# 4.（可选）本地开发模式预装浏览器内核
PLAYWRIGHT_BROWSERS_PATH=tmp/playwright patchright install chromium --no-shell
# 5. 启动 Web UI（端口/主机见第六章环境变量）
python run_ui.py
# 浏览器访问 http://localhost:50001 （或你设置的 WEB_UI_PORT）
源码方式下，若要在 Agent Zero 里执行代码/命令，必须保证本机 Docker 可用（代码执行工具会调用 Docker）。纯 venv 不装 Docker 则代码执行工具不可用。
六、配置文件参数全解
Agent Zero 的主要配置在 Web UI 的 Settings 里完成（模型、凭证、插件、备份）。此外还有少量环境变量与声明式配置文件。下面逐条说明。
6.1 环境变量（.env / 启动环境）
当前版本通过环境变量控制 Web 服务绑定（在 run_ui.py 中读取）：
旧版（0.8 及更早）教程里常见的
CHAT_MODEL_ANTHROPIC、API_KEY_OPENAI、example.env等.env写法已不是当前版本的主路径，请勿照抄旧文。
6.2 LLM 提供方配置（model_providers.yaml）
位于仓库 conf/model_providers.yaml，通过 LiteLLM 统一接入多家模型。支持：OpenAI、Anthropic、OpenRouter、Google、Venice、xAI、GitHub Copilot、Codex/ChatGPT（OAuth）、Ollama、LM Studio 等。一般用 Web UI 的 Onboarding 向导添加，无需手改；高级用户可在此文件新增/微调提供方。
Web UI 中每个模型槽有三类角色：
6.3 凭证与密钥（secrets.env）
API Key 等敏感值通过 Settings → Secrets，存于容器内 /a0/usr/secrets.env，不会总被备份包含。也可在 Web UI Onboarding 中粘贴提供方 Key。切勿把密钥写进提示词或公开文件。
6.4 工具与插件开关
在 Settings → Agent Config / Agent Plugins 中启用/停用工具与插件（如 _kokoro_tts、_whisper_stt、浏览器、代码执行等）。自定义工具放在 tools/ 或插件里；MCP 服务器在 MCP 设置中接入。
6.5 记忆设置
记忆目录、区域、匹配阈值在 Memory 面板与设置中调整；/a0/usr 下的 memory/ 存储长期记忆。项目级记忆与全局记忆隔离。
6.6 沙箱 / 隔离
代码执行与命令在 Docker 容器内运行，天然与宿主机隔离。
文件工作区默认是
/a0/usr（容器内），映射到宿主机的卷或目录。宿主机桥接（A0 CLI）开启后，Agent 可访问真实本机文件与终端——仅在可信机器上授予 Read+Write 与远程代码执行权限。
macOS 需在 Docker Desktop 中授权文件共享，代码执行工具才能访问项目文件。
6.7 全局设置文件
/a0/usr/settings.json 保存 UI 设置；若配置损坏，删除该文件后重启容器会自动重建默认设置。
七、启动 / 后台常驻 / 开机自启 / 改端口 教程
7.1 启动
Launcher：实例卡片显示 Running 后点 Open UI，在 Web UI 完成 Onboarding（连模型）即可聊天。
Docker：容器启动后访问
http://localhost（或映射端口）。
7.2 改端口
Docker（推荐）：用
-p <宿主端口>:80映射。bash docker run -d -p 5080:80 -v a0_usr:/a0/usr --name agent-zero agent0ai/agent-zero # 访问 http://localhost:5080若 80 被占用，直接换宿主端口即可（如-p 5080:80），不必改容器端口。源码/venv：设置环境变量
WEB_UI_PORT或WEB_UI_HOST后启动python run_ui.py。A0 Install Quick Start：用
--port 5080/-Port 5080参数。
7.3 后台常驻
Docker：加
-d以分离模式运行；查看日志docker logs -f agent-zero。Launcher：本身是常驻应用，随实例常开。
服务器无桌面：用 A0 Install 的
--quick-start模式，它创建实例并后台运行。
7.4 开机自启
Docker 重启策略（最稳）：
bash docker update --restart=always agent-zeroLauncher（桌面）：在系统「登录项/开机启动」中加入 A0 Launcher。
systemd（自建服务，源码/自管容器）：写一个
agent-zero.service，Restart=always，WantedBy=multi-user.target。注意事项：开机自启会暴露服务，务必先配置 Web UI 鉴权（Settings → 启用 Basic Auth / 密码保护），否则任何人可访问。
八、功能实操教程
8.1 连接 LLM（首次 Onboarding）
打开 Web UI 后，Onboarding 向导让你选三类接入方式之一：
Cloud：OpenRouter、Agent Zero 代理 API、Anthropic、OpenAI、Google、Venice、xAI 等托管提供方。
AI account：Codex/ChatGPT、GitHub Copilot、Google Cloud Gemini、xAI Grok，走 OAuth 设备码登录。
Local：Ollama、LM Studio 等本机模型服务器。
流程：选提供方 → 粘贴 API Key（如需要）→ 选主模型 → 选工具/嵌入模型 → Finish setup。
本地模型（Ollama）示例：
# 宿主机安装并启动 Ollama
curl -fsSL https://ollama.com/install.sh | sh # Linux
ollama pull llama3.2
在 Agent Zero 模型设置里选 Ollama，Base URL 填 http://host.docker.internal:11434（不要用 localhost/127.0.0.1，容器内那是指向容器自身），填模型名后保存。
8.2 第一个任务
在 Web UI 输入框直接描述结果即可，不必点名工具。例如：
「调研这个 App 的三种部署方案，引用来源，最后给出推荐。」
常用入口：New Chat（新对话）、Projects（项目）、Memory（记忆）、Tasks（任务）、Files（文件浏览器）、Settings（设置）、Browser（浏览器画布）、Desktop（桌面画布）。
8.3 使用内置工具
浏览器：让 Agent「用 Browser 工具对比这几个页面并截图」；或你先在浏览器画布里标注页面，再让 Agent 按标注修改。
代码/终端执行：Agent 自己写 Python/Shell 并运行（在容器沙箱内）。例：「打开附件 CSV，找主要趋势，生成可编辑图表。」
文件：上传/下载/整理文件；重要工作放在
/a0/usr或项目工作区，避免只放临时目录。知识（Knowledge）：把文档喂给 Agent 做 RAG 问答。
插件：在 Plugins → Browse 安装扩展能力。
8.4 文件与命令执行
想让 Agent 直接操作你的文件/目录：把文件放进
/a0/usr，Agent 即可对其执行任务。想操作真实本机：先装 A0 CLI，连接后 Agent 可请求访问本机文件、在宿主终端执行命令、使用你的浏览器配置。
桌面画布里可打开终端窗口手动敲命令，或让 Agent 驱动 GUI 软件（如 Blender 建 3D logo）：
8.5 记忆机制
Agent 会把有用的解决方案、代码、事实、指令存入记忆。
打开 Memory 面板搜索/审查/编辑/删除条目；项目记忆与全局记忆隔离。
记忆需要人工策展：删除过期测试数据、修正不准确记忆，否则错误记忆会「毒化」处理。
大批量清理记忆前先备份。
8.6 项目、任务与多 Agent
Projects：给某类工作（客户项目、仓库、周期报告）独立文件/指令/密钥/记忆/模型。
Tasks：定时/计划/手动自动化（如「每周文档审查」）。项目级任务继承项目指令与密钥。
多 Agent：在对话中让主 Agent 派生子 Agent 分工调研/审查，再汇总。
九、全套报错故障排查
下面按出现频率整理，凡涉及容器内操作均需 Docker 在运行。
9.1 Docker 未运行 / 容器起不来
现象：Launcher 报错、或
docker run直接失败。解决：启动 Docker Desktop（Windows/macOS）或服务（Linux
sudo systemctl start docker）；重开 Launcher 或重跑安装命令；确认镜像已更新（docker pull agent0ai/agent-zero）。
9.2 端口被占用（Port 80 in use）
现象：启动报 80 已被占用，或 Web UI 打不开。
解决：换宿主端口，如
docker run -p 5080:80 ...，访问http://localhost:5080；Launcher 里换端口；或用 Quick Start 的--port。
9.3 Web UI 不可达
现象：浏览器连不上。
解决：确认至少有一个宿主端口映射到了容器
80；若用了0:80，去 Docker Desktop 看实际分配端口；检查防火墙/云安全组是否放行该端口。
9.4 输入后没反应 / 没配 API Key
现象：发消息毫无响应。
解决：八成是没在 Settings 配 LLM 提供方与 Key。打开 Onboarding 或 Settings → 连至少一个提供方与主模型。
9.5 "Invalid model ID"（模型名错误）
现象：调用时报无效模型 ID。
解决：检查提供方与模型命名。例如
openai/gpt-5.3对 OpenRouter 正确，但原生 OpenAI 提供方不带前缀；确认模型名与所选提供方匹配。
9.6 ChatGPT Plus 不含 API 额度
现象：用 Plus 账号却调不通。
解决：ChatGPT Plus 不包含 API 额度，必须在 Settings 里填独立的 OpenAI API Key（或改用 OAuth 登录 ChatGPT/Codex 账号）。
9.7 浏览器工具失败 / 提示 Chromium 缺失
现象：Browser 工具报错或截图空白。
解决：正常 Docker 安装浏览器已自带；本地开发 checkout 可首次需要时自动安装，或手动：
bash PLAYWRIGHT_BROWSERS_PATH=tmp/playwright patchright install chromium --no-shellBring Your Own Browser 失败：保持 A0 CLI 连接、在浏览器开启远程调试后重连、在 A0 CLI 跑/browser status、确认 Browser 设置仍是「Bring Your Own Browser」、检查页面内容访问权限。
9.8 code_execution_tool 不工作
现象：让 Agent 跑代码/命令无反应或报错。
解决：确保 Docker 已安装并运行；macOS 在 Docker Desktop 授权项目文件访问；确认镜像为最新（Docker Desktop 删掉旧镜像重新拉取）。
9.9 本地模型从 Docker 内连不上
现象：Ollama/LM Studio 在宿主机跑，Agent Zero 报连接失败。
解决：在 Agent Zero 里不要用
localhost/127.0.0.1（那指向容器自己），改用http://host.docker.internal:11434（Linux 默认桥可用172.17.0.1）；确认模型服务监听在非127.0.0.1的可达地址（如0.0.0.0）。
9.10 终端命令不执行
现象：Agent 说要执行命令却没动静。
解决：确认容器在运行且配置正确；检查 SSH 相关设置；更新镜像（删旧镜像重拉）。
9.11 卡在更新界面 / 更新后起不来
现象：浏览器一直显示 updating。
解决：先刷新当前窗口；仍不恢复则重启容器；若还不恢复，在容器内排队下次自更新：
bash docker exec -it <容器名> /exe/trigger_self_update.sh ready latest docker exec -it <容器名> tail -n 200 /exe/a0-self-update.log然后重启容器，查看/exe/a0-self-update-status.yaml。
9.12 备份还原后密钥丢失
现象：还原备份后 Secrets 不见了。
解决：密钥在
/a0/usr/secrets.env，不一定进备份包；请单独保存重要密钥并手动拷回。
9.13 源码安装 ModuleNotFoundError
现象：
python run_ui.py报缺模块。解决：确认已
source venv/bin/activate并pip install -r requirements.txt requirements2.txt；确认 Python 版本为 3.11/3.12。
十、升级 / 回滚 / 卸载 教程
10.1 升级
Launcher：实例卡片 → Check for Updates，按引导更新；或重开 Launcher 下载最新版。
Docker（推荐零停机）： 1. 保留旧容器运行。 2.
docker pull agent0ai/agent-zero:latest。 3. 用不同宿主端口起新容器：docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero:latest。 4. 旧实例：Settings → Backup & Restore → Create Backup，下载 zip。 5. 新实例：导入该备份 zip。 6. 验证聊天与数据无误后，再删旧容器。在删旧容器前，务必确认新容器已拿到你的数据。
容器内自更新脚本：
docker exec -it <容器> /exe/trigger_self_update.sh ready latest。
10.2 回滚
保留旧容器：升级时别删旧容器，验证失败直接回到旧实例。
版本固定：生产环境用具体版本标签（如
agent0ai/agent-zero:v0.9.5）而非latest，回滚只需切回旧标签。备份还原：用升级前创建的备份 zip 还原到旧版本容器。
设置损坏：删
/a0/usr/settings.json后重启，自动重建默认设置。
10.3 卸载
停止并删除容器：
bash docker stop agent-zero && docker rm agent-zero删除数据卷（会清空所有聊天/记忆/文件，先备份！）：
bash docker volume rm a0_usr删除镜像（可选）：
bash docker rmi agent0ai/agent-zero桌面用户：在系统「应用/登录项」卸载 A0 Launcher 并移除开机启动项。
十一、商用许可与合规风险提示
11.1 许可证：MIT（可商用）
Agent Zero 采用 MIT License（见仓库 LICENSE，Copyright © 2025 Agent Zero, s.r.o）。MIT 是最宽松的开源许可之一：
✅ 可商用、可修改、可再分发、可闭源打包、可售卖。
✅ 可用作「Agent Zero 操作系统」底座构建商业产品（官方另有商业化产品 Space Agent 即基于此生态）。
⚠️ 义务：在副本或重要部分中保留原始版权声明与 MIT 许可声明；软件按「原样」提供，作者不承担任何担保或责任。
11.2 安全风险：Agent Zero 会「在本机执行代码」
Agent Zero 的核心卖点也是核心风险——它把计算机当工具，会写并运行代码、执行终端命令、访问文件系统、联网。若缺乏隔离，恶意或被误导的指令可能损坏数据、外泄隐私或影响生产系统。官方明确提示：
「不要把整个 home 目录挂进去，除非你清楚风险。」
「仅对你信任的机器与工作区，授予 A0 CLI 读+写与远程代码执行权限。」
「审查一切触碰账户、资金、生产系统或私密数据的操作。」
「为重要工作区保留备份。」
11.3 隔离与加固措施（强烈建议）
11.4 合规提示
调用云端 LLM 需遵守对应服务商的使用条款与数据出境规定（企业数据注意合规）。
用 Agent 操作第三方账号/API 时，确保你有授权，避免越权或滥用。
MIT 不提供任何担保；将其用于医疗、金融、安全等关键决策前，务必人工复核 Agent 输出。
总结：Agent Zero 是一个把完整 Linux 桌面、浏览器与终端交给 AI 的开源「Agent 操作系统」，以 Docker 一键部署、MIT 协议可商用，并通过记忆与插件不断自我进化。部署与使用时务必保留 Docker 隔离、最小挂载与对外鉴权，才能在享受「自动执行」能力的同时守住安全底线。