导语
2023 年底 AutoGPT 带火「自主智能体」那阵，OpenBMB 也交了一份作业：XAgent。这社区由面壁智能和清华大学 THUNLP 实验室共同发起，XAgent 仓库 2023 年 10 月 16 日建，Apache 2.0 协议、纯 Python 写的，现在 8549 星、902 个 fork（2026 年 10 月 16 日我用 GitHub API 现查的，不是二手数据）。它跟 AutoGPT 最大的区别是不瞎跑：先把任务拆成带里程碑的计划，再一步步执行，所有可能闯祸的动作全关进 Docker 容器里。这篇把它的架构和上手路径讲清楚。
项目介绍：三层分工，双循环干活
官方把架构拆成三个角色：Dispatcher（调度器）按能力把任务派给不同的 Agent；Planner（规划器）负责生成计划、把任务切成带里程碑的子任务，跑偏了还会回头校正；Actor（行动者）用 ToolAgent 真正干活。代码里对应 XAgentDispatcher、PlanAgent、ToolAgent 三个类，外面套一个 TaskHandler 的 outer_loop 把它们串成一条流水线。
干活节奏是双循环：外层循环生成计划、逐个领子任务推进，失败就回炉走 plan_refine_mode 重新校正；内层是 ReACT 链式搜索，模型每一步先推理、再挑工具、看结果决定下一步，直到子任务完成。卡住时它不硬扛，会通过 ask_for_human_help 把问题抛回网页 GUI 问你（需要开 –enable-ask-human-for-help 开关）。
工具层是它最讲究的部分：ToolServerManager 起一个 FastAPI 服务（:8080）管容器，真正执行落在 ToolServerNode 这个 Docker 容器里，内置文件编辑、Python Notebook、网页浏览器、Shell、RapidAPI 五类工具。README 原话是「所有动作都被限制在一个 docker 容器内」。Shell 能装软件、能起服务，也跑不出这个圈。
官方演示里那个 iris.zip 数据分析案例最能说明双循环怎么转：用户丢一个压缩包进去，XAgent 自己拆成四步：看数据、验 Python 环境有没有分析库、写代码跑分析、最后出报告，中途画的图、跑的命令全在沙箱里完成。
上手：compose 一次起六个服务
前置三样：Docker 和 compose、Python 3.10+、一把 OpenAI key。
git clone https://github.com/OpenBMB/XAgent.git
cd XAgent && docker compose up -d
pip install -r requirements.txt
compose 会拉起 GUI、ToolServerManager、ToolServerNode、MongoDB、MySQL、Redis 六个容器。配置写在 assets/config.yml：README 写明至少一把 OpenAI key，推荐 gpt-4-32k 当主力、gpt-3.5-turbo-16k 当备份，上下文太短的模型别硬跑。然后直接：
python run.py --task "你的任务" --config-file assets/config.yml
跑完产物在 local_workspace，每一步的中间状态、LLM 出入参、用过的工具都落在 running_records 里，配 record_dir 能整段回放。要带初始文件就加 –upload-files；网页端也能直接传文件，传完会被拷进工作区、再同步给 ToolServer。不想碰命令行就开 http://localhost:5173，默认账号 guest、密码 xagent。
实话
先说好的：结构清楚。外层规划、内层 ReACT、工具沙箱三层各管各的，想研究「计划-执行」型 Agent 怎么落地，它是份不错的源码教材；Docker 隔离加主动求助人类这两个设计，放在 2023 年那批项目里算超前。
再说坑，三条：
- 基本停更了。2024 年 3 月 4 日之后仓库静默两年多，直到 2026 年 7 月 31 日才补了两个提交，而且全是安全修复（#432 高危代码执行、#433 路径穿越）。长期没人管、突然集中补洞，维护节奏就摆在这。
- 模型绑死 OpenAI 系。config.yml 只认 OpenAI key，gpt-4-32k 是 2023 年的推荐，想接国产模型得自己改代码。
- 部署偏重。一次起六个容器，试跑成本比 n8n、Dify 那种单栈高不少。
所以定位很清楚：当学习架构和二次开发的底子合适，直接上生产不合适。真要跑生产级自主 Agent，工程化那部分得自己补一大截。同年代的 AutoGPT 至今还在高频提交，但说实话，它也没解决这个问题。
