Agent Zero 容器运行环境与 WebUI JSON API 调用指南Kali Linux Docker 下的双 Python 运行时与 CSRF 防护机制【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文围绕 Agent Zero 框架的系统级运行环境说明文档展开深入讲解其在 Kali Linux Docker 容器中的部署布局、/a0项目目录结构、框架运行时与任务执行运行时两个 Python 环境的职责划分以及 WebUI JSON API 的调用方式与 CSRF 防护机制。读完本文你将能够在容器终端中正确选择 Python 解释器安装依赖并通过curl携带 CSRF Token 与 Cookie 安全地调用/api/handler_name接口。环境总览Kali Linux Docker 容器中的 Agent ZeroAgent Zero 框架的官方运行环境是一个基于Kali Linux 的 Docker 容器其基础镜像构建逻辑直接体现在 docker/base/Dockerfile 中FROM kalilinux/kali-rolling基础镜像阶段会完成 localeen_US.UTF-8、时区UTC、基础软件包、Python 多版本、SearXNG 搜索服务与 SSH 的安装配置运行镜像 docker/run/Dockerfile 则以agent0ai/agent-zero-base:latest为基础接收BRANCH构建参数依次执行安装脚本最终通过supervisord托管 WebUI、SearXNG 与隧道 API 等服务见 docker/run/fs/exe/initialize.sh并对外暴露22、80、9000-9009端口。环境文档明确了三条容器内的基本事实操作系统Kali LinuxDebian 系可通过apt直接安装 Debian/Kali 软件包项目位置Agent Zero 框架本身是 Python 项目安装在容器的/a0文件夹下权限Linux 系统完全以root身份通过终端访问无权限限制。/a0目录的定位可从 docker/run/fs/ins/copy_A0.sh 得到印证安装阶段先将仓库克隆至/git/agent-zero并执行uv pip install -r requirements.txt见 docker/run/fs/ins/install_A0.sh随后在容器启动时拷贝到目标目录/a0若/a0通过卷挂载且缺少run_ui.py则会重新拷贝仓库文件。容器初始化脚本还会创建mkdir -p /a0/usr/uploads以保障上传目录存在见 docker/run/fs/exe/initialize.shrun_tunnel.py、self_update_manager.py等运行时脚本也均以/a0为工作根目录。可以推断/a0是框架代码、usr/运行时状态与上传文件的统一挂载点。双 Python 运行时框架运行时与任务执行运行时环境文档中最关键、也最容易踩坑的约束是容器内存在两个独立的 Python 虚拟环境各自承担完全不同的职责运行时解释器路径Python 版本职责框架运行时/opt/venv-a0/bin/python3.12运行 Agent Zero 本体、WebUI 后端、API 处理器、插件/钩子hooks以及框架自身的 importAgent 执行运行时/opt/venv/bin/python3.13默认的任务/用户代码执行环境即 Agent 终端中运行任务代码时使用的解释器这一两运行时模型在仓库的 docker/AGENTS.md 中有正式定义the Python 3.12 framework runtime under/opt/venv-a0runs the WebUI, APIs, scheduler, framework imports, and plugin hooks; the Python 3.13 agent execution runtime under/opt/venvruns agent terminal tasks and user code与本文档完全一致。两个环境的具体构建过程位于 docker/base/fs/ins/install_python.sh全局安装 Python 3.13并创建默认 venvpython3.13 -m venv /opt/venv source /opt/venv/bin/activate pip install --no-cache-dir --upgrade pip pipx ipython requests该环境是 Agent 执行任务的默认环境同时通过 docker/run/fs/ins/install_playwright.sh 将 Playwright 浏览器缓存指向/a0/tmp/playwright。通过 pyenv 安装 Python 3.12.4并创建框架 venvpyenv install 3.12.4 /opt/pyenv/versions/3.12.4/bin/python -m venv /opt/venv-a0 source /opt/venv-a0/bin/activate pip install torch2.4.0 torchvision0.19.0 --index-url https://download.pytorch.org/whl/cpu框架运行时额外预装了 CPU 版 PyTorch供框架自身的向量检索等能力使用。安装依赖时的选择原则文档给出了明确的实操准则任务依赖装到/opt/venv/bin/pythonAgent 在终端中执行用户任务代码时使用的是执行运行时。要为任务安装第三方包例如数据处理库、网络请求库应安装到该环境/opt/venv/bin/pip install task-package框架依赖装到/opt/venv-a0/bin/python只有当框架运行时确实需要某个包如自定义插件、hook 或后端逻辑需要 import时才安装到框架环境/opt/venv-a0/bin/pip install framework-package导入检查必须用框架解释器验证框架/后端代码能否 import 某个包时一律使用/opt/venv-a0/bin/python不能把/opt/venv中已安装的包当作框架可用的证据。因为两个环境相互独立/opt/venv里的包对运行 WebUI 与 API 的框架进程不可见。高文件描述符限制可选调优容器初始化时还会尝试提升进程可打开的文件数上限默认目标值为65535可通过环境变量A0_NOFILE_LIMIT覆盖见 docker/run/fs/exe/initialize.sh。在运行大量并发任务或 WebUI 长连接场景下可以关注此值。WebUI JSON API路由、认证与 CSRF 三层防护环境文档后半部分聚焦 WebUI 的 JSON API 调用规范这是与 WebUI 前端、外部脚本乃至其他 Agent 集成的核心通道。API 路由机制/api/handler_nameAPI 处理器统一注册在/api/handler_name路径下。从源码看路由分发由 helpers/api.py 中的register_api_route完成app.add_url_rule( /api/path:path, api_dispatch, _dispatch, methods[GET, POST, PUT, PATCH, DELETE], )分发器会先在api/目录下按path.py查找对应的处理器类继承自ApiHandler若路径以plugins/开头则继续在插件目录的api/子目录中查找见 helpers/api.py。因此框架自带的处理器文件即仓库根目录下 api/ 中的各.py文件例如api/message.py、api/chat_create.py、api/csrf_token.py请求方法不匹配时返回405处理器不存在时返回404大多数处理器接受 JSON POST 请求基类ApiHandler.get_methods()默认返回[POST]见 helpers/api.py请求体为 JSON 时会被解析为input_data字典传给process()见 helpers/api.py。防护链路auth → api_key → loopback → CSRF每个处理器按声明顺序被套上多层安全装饰器具体取决于其类方法的返回值见 helpers/api.pyrequires_csrf()默认与requires_auth()一致见 helpers/api.py即登录启用时默认需要 CSRF Tokenrequires_api_key()默认False开启后要求请求携带X-API-KEY头或 JSON 体中的api_key见 helpers/api.pyrequires_auth()默认True若系统配置了登录凭据则校验 session 中的authentication见 helpers/api.pyrequires_loopback()默认False开启后仅允许回环地址访问见 helpers/api.py。CSRF 防护的完整机制CSRF 校验由csrf_protect实现见 helpers/api.pytoken session.get(csrf_token) header request.headers.get(X-CSRF-Token) cookie request.cookies.get(csrf_token_ runtime.get_runtime_id()) sent header or cookie if not token or not sent or token ! sent: return Response(CSRF token missing or invalid, 403)从中可以提取出三个关键事实服务端将 CSRF Token 存于session客户端提交 Token 的方式有两种HTTP 头X-CSRF-Token或名为csrf_token_runtime_id的 CookieCookie 名称中的runtime_id由 helpers/runtime.py 的get_runtime_id()生成secrets.token_hex(8)每次进程启动会变化这解释了为什么文档要求从同一个 WebUI origin 获取 token 并保留 cookies——token 与 runtime id 绑定的 session Cookie 必须配套使用。获取 CSRF TokenGET /api/csrf_tokenToken 的获取入口是 api/csrf_token.py 中的GetCsrfToken处理器方法为GET且显式声明requires_csrf() - False自身不需要 CSRF否则会形成死循环首次访问时通过secrets.token_urlsafe(32)生成 Token 并写入 session响应同时返回token与runtime_id在登录未启用的情况下该接口还会执行Origin 校验以防止 DNS rebinding 攻击请求必须携带Origin或Referer头且来源需在允许列表中。默认允许*://localhost、*://127.0.0.1、*://0.0.0.0及其端口变体见 api/csrf_token.py也可通过环境变量ALLOWED_ORIGINS逗号分隔的通配符列表扩展若 WebUI 运行在服务器域名上首次访问的 Origin 会被自动写入ALLOWED_ORIGINS见 api/csrf_token.py隧道 URL 也会被自动加入允许列表。这就是环境文档要求从终端调用时包含 Origin 或 Referer、保留返回的 cookies、后续调用复用 token 与 cookie jar的原因。实战用 curl 完成一次完整的 API 调用以下命令在容器终端内以 root 执行假设 WebUI 默认端口为5000由 helpers/runtime.py 的get_web_ui_port()读取WEB_UI_PORT环境变量或--port参数默认回退到 5000实际端口请以部署配置为准。第一步获取 CSRF Token 并保存 Cookie# -c 保存服务端下发的 session cookie-H 携带 Origin 满足来源校验 curl -s -c /tmp/a0cookies.txt \ -H Origin: http://127.0.0.1:5000 \ http://127.0.0.1:5000/api/csrf_token返回示例{ok: true, token: abc123..., runtime_id: a1b2c3d4e5f6a7b8}此时/tmp/a0cookies.txt中应保存了 session Cookie其中包含csrf_token_runtime_id对应的值。第二步携带 Token 与 Cookie 调用受保护的 APITOKEN上一步返回的 token curl -s -b /tmp/a0cookies.txt -c /tmp/a0cookies.txt \ -H Content-Type: application/json \ -H X-CSRF-Token: $TOKEN \ -H Origin: http://127.0.0.1:5000 \ -X POST http://127.0.0.1:5000/api/handler_name \ -d {chat_id: ..., message: ...}要点回顾-b读取 Cookie、-c续写 Cookie保证 session 一致X-CSRF-Token头与 session 中的 token 必须一致否则返回403 CSRF token missing or invalidOrigin/Referer在登录未启用时用于通过csrf_token接口的来源校验建议始终携带若配置了登录还需先通过 WebUI 完成登录以建立authenticationsession。免 CSRF 的探活示例作为对照api/health.py 中的HealthCheck同时声明requires_auth() - False与requires_csrf() - False支持 GET/POST无需任何凭证即可探测服务状态返回 Git 版本信息curl -s http://127.0.0.1:5000/api/health返回示例{gitinfo: {commit: ..., branch: ..., version: ...}, error: null}小结Agent Zero 的容器环境设计围绕框架与任务隔离展开框架本体、WebUI、API 与插件运行在/opt/venv-a0Python 3.12中用户任务代码则默认运行在/opt/venvPython 3.13中安装依赖与验证 import 时必须严格区分这两个环境。WebUI JSON API 统一走/api/handler_name路由默认受 CSRF 保护先从GET /api/csrf_token获取 Token 并保存 session Cookie再在后续请求中通过X-CSRF-Token头或csrf_token_runtime_idCookie携带同时保留 Origin/Referer。遵循这套流程即可安全、稳定地以脚本方式驱动 Agent Zero 的 WebUI 能力。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考