AutoGPT Classic 实战指南：环境配置、Workspace 布局与分层权限体系解析

本文以 classic/README.md 为主体，完整讲解 AutoGPT Classic 实验框架的安装、分层配置、三种运行入口、Workspace 数据布局与分层权限系统，并结合 permissions.py、workspace_settings.py 等源码说明权限匹配与配置解析的底层实现，帮助读者在不依赖平台（Platform）的情况下，独立部署、运行和定制这套经典自主智能体框架。

项目定位与维护状态

AutoGPT Classic 是早期用于展示 GPT-4 自主运行能力的实验项目：让模型独立地拆解复杂目标、调用工具与 API 执行任务、根据结果调整策略，并将多个动作串联起来达成目标。需要特别注意 README 中明确声明的项目状态：

• 该项目不再受支持，依赖也不会更新，初始研究阶段已经结束；
• 如果目标是日常使用 AutoGPT，官方推荐转向 AutoGPT Platform；
• 对自主智能体感兴趣的开发者，可将本代码库作为教学与研究用途的参考实现。

此外 README 附带安全警示：代码库存在已知漏洞且依赖不更新，仅建议用于教育目的。这一状态决定了本文的读者定位——学习与研究其架构设计（尤其是权限沙箱与配置分层），而非生产部署。

仓库结构：一个 Poetry 项目整合三大包

README 给出的目录结构如下：

classic/
├── pyproject.toml          # 单一整合的 Poetry 项目
├── poetry.lock             # 单一 lock 文件
├── forge/                  # 核心自主智能体框架
├── original_autogpt/       # 原始实现
├── direct_benchmark/       # 基准测试框架（Benchmark harness）
└── benchmark/              # 挑战定义（数据）

从 classic/pyproject.toml 可以看到，整个 classic/ 确实被整合为单个 Poetry 项目 autogpt-classic（版本 0.5.0），一次声明了三个包：

packages = [
    { include = "forge", from = "forge" },
    { include = "autogpt", from = "original_autogpt" },
    { include = "direct_benchmark", from = "direct_benchmark" },
]

这解释了后文"所有命令都从 classic/ 目录运行"的原因——poetry install 一次装齐三个子项目。同一文件中的 [tool.poetry.scripts]（L31-L34）注册了三个命令行入口：autogpt、serve（均来自 autogpt.app.cli）与 direct-benchmark（来自 direct_benchmark.__main__:main）。依赖层面，pyproject.toml 声明了 python = "^3.12"，LLM 供应商覆盖 openai、anthropic、groq，文件存储支持 boto3（S3）与 google-cloud-storage（GCS），与后文 FILE_STORAGE_BACKEND 的三个取值一一对应。

安装与前置条件

前置条件

• Python 3.12+（pyproject.toml 声明 ^3.12，classifiers 覆盖 3.12/3.13/3.14）
• Poetry

安装

# 克隆仓库
git clone https://github.com/Significant-Gravitas/AutoGPT.git
cd classic

# 安装全部依赖
poetry install

分层配置体系

README 将配置描述为三层结构，优先级从高到低：

1. 环境变量（.env 文件）
2. Workspace 设置（.autogpt/autogpt.yaml）
3. Agent 设置（.autogpt/agents/{id}/permissions.yaml）

环境变量模板实际位于 forge 包内：classic/forge/.env.example（原始实现侧另有 classic/original_autogpt/.env.template），按 README 指示复制为 .env：

cp .env.example .env

README 归纳的关键环境变量如下，可结合模板文件中的注释一起理解：

# 必填
OPENAI_API_KEY=sk-...

# 可选 LLM 设置
SMART_LLM=gpt-4o                    # 用于复杂推理的模型
FAST_LLM=gpt-4o-mini                # 用于简单任务的模型

# 可选搜索供应商
TAVILY_API_KEY=tvly-...
SERPER_API_KEY=...

# 可选基础设施
LOG_LEVEL=DEBUG
PORT=8000
FILE_STORAGE_BACKEND=local          # local、s3 或 gcs

源码层面，环境变量的解析由一套自研的"可配置字段"机制完成：models/config.py 中的 UserConfigurable() 工厂函数允许任意 Pydantic 字段声明 from_env="环境变量名"，而 SystemConfiguration.from_env()（L79-L105）会在实例化配置对象时遍历所有字段，凡有 from_env 标记的字段优先取环境变量值，否则回落到字段默认值。例如 config/base.py 中的文件存储后端：

file_storage_backend: FileStorageBackendName = UserConfigurable(
    default=FileStorageBackendName.LOCAL, from_env="FILE_STORAGE_BACKEND"
)

这就是 FILE_STORAGE_BACKEND=local|s3|gcs 能生效的底层原因，默认值为 local。

关于 SMART_LLM / FAST_LLM 双模型分工，watchdog 组件 的注释给出了直观解释：当智能体陷入循环、卡住或偏离主题时，看门狗会从 FAST_LLM 切换到 SMART_LLM 重新思考——即日常推理用便宜快速的模型，异常纠正用更强的模型。

三种运行入口

README 规定所有命令均从 classic/ 目录运行：

# 运行 forge 智能体
poetry run python -m forge

# 运行 original autogpt 服务
poetry run serve --debug

# 运行 autogpt CLI
poetry run autogpt

智能体服务默认运行在 http://localhost:8000。从源码印证：forge 的入口 forge/main.py 读取 PORT 环境变量（默认 8000），加载 .env 后经 uvicorn 挂载 forge.app:app 这个 FastAPI 应用，并开启了针对 forge/**/*.py 与 .env 的自动重载——开发时修改配置或代码会立即生效。serve 与 autogpt 两个命令则对应 original_autogpt 包的 autogpt.app.cli 模块，是同一 Poetry 环境下的兄弟入口（pyproject.toml L31-L34）。

Workspace 与智能体数据布局

智能体在一个 workspace 目录内运行，该目录承载所有智能体数据与文件：

{workspace}/
├── .autogpt/
│   ├── autogpt.yaml              # Workspace 级权限
│   ├── ap_server.db              # Agent Protocol 数据库（server 模式）
│   └── agents/
│       └── AutoGPT-{agent_id}/
│           ├── state.json        # 智能体档案、指令、历史
│           ├── permissions.yaml  # 智能体级权限
│           └── workspace/        # 智能体的沙箱工作目录

README 给出的四条关键规则：

• workspace 默认为当前工作目录；
• 多个智能体可在同一 workspace 中共存；
• 智能体的文件访问被沙箱限制在其 workspace/ 子目录内；
• 状态通过 state.json 跨会话持久化。

File Manager 组件 的源码印证并细化了这套布局：CLI 模式下智能体数据存于 .autogpt/agents/{agent_id}/；而 server 模式下（agent_id 由外部传入时）路径切换为 agents/{agent_id}/，其沙箱工作目录为 agents/{agent_id}/workspace。state.json 文件名即来自该类的 STATE_FILE = "state.json" 常量（L47），与 README 描述一致。

分层权限系统（核心机制）

AutoGPT 使用基于模式匹配（pattern matching）的分层权限系统，这是整个框架中工程含量最高的部分，下面结合 classic/forge/forge/permissions.py 逐层展开。

权限文件与作用域

文件	作用域	位置
autogpt.yaml	workspace 内所有智能体	.autogpt/autogpt.yaml
permissions.yaml	单个智能体	.autogpt/agents/{id}/permissions.yaml

权限格式

allow:
  - read_file({workspace}/**)     # 读取 workspace 内任意文件
  - write_to_file({workspace}/**) # 写入 workspace 内任意文件
  - web_search(*)                 # 允许所有网络搜索

deny:
  - read_file(**.env)             # 禁止读取 .env 文件
  - execute_shell(sudo:*)         # 禁止 sudo 命令

模式语法为 命令名(参数通配符)。从 _pattern_matches 实现 可以看到匹配细节：

1. 先用正则 ^(\w+)\((.+)\)$ 把模式拆成"命令名 + 参数通配符"两部分，命令名必须精确相等；
2. {workspace} 占位符被替换为真实 workspace 绝对路径；
3. 通配符按 glob 转正则：** → .*（可跨 / 匹配任意路径），* → [^/]*（不跨 /）。

参数在匹配前还会被规范化（_format_args）：文件类命令（read_file、write_file、list_folder 等）统一解析为相对 workspace 的绝对路径（含符号链接解析，防止 symlink 绕过）；shell/python 类命令格式化为 可执行文件:参数（首个词为可执行文件），因此 execute_shell(sudo:*) 这类模式才能成立；web_search 用查询串、read_webpage 用 URL 作为匹配串。

默认权限（开箱即安全）

当 .autogpt/autogpt.yaml 不存在时，WorkspaceSettings.load_or_create 会自动创建默认文件。其内置默认值（L18-L41）就是 README 所说"默认安全"策略的落地：

• 默认 allow：read_file({workspace}/**)、write_file({workspace}/**)、list_folder({workspace}/**)、finish(*) —— 即读写权限被限定在 workspace 内部；
• 默认 deny：read_file(**.env)、read_file(**.env.*)、read_file(**.key)、read_file(**.pem)（敏感文件），以及 execute_shell(rm:-rf **)、execute_shell(rm:-r **)、execute_shell(sudo:**)（破坏性命令）。

对应 README 的"默认拒绝"清单：敏感文件（.env、.key、.pem）、破坏性命令（rm -rf、sudo）、workspace 之外的操作（默认 allow 只覆盖 workspace 内路径，workspace 外的路径不会自动放行，需要走审批，无审批通道时直接拒绝）。

检查顺序（First Match Wins）

README 给出的判定顺序为：

1. Agent deny → 拦截
2. Workspace deny → 拦截
3. Agent allow → 放行
4. Workspace allow → 放行
5. 询问用户 → 交互式审批

CommandPermissionManager.check_command 的源码与之一致，且更完整：在上述第 4、5 步之间还插入了会话内拒绝列表（session denials）——本会话中用户已拒绝过的命令会直接拦截，避免反复弹窗；若最终走到第 5 步而没有配置 prompt_fn（如非交互环境），则返回拒绝。

交互式审批的四种作用域

命中"询问用户"分支后，_ApprovalScope 枚举定义了用户的四种选择，与 README 完全对应：

• Once——仅本次放行，不落盘；
• Agent——永久允许，写入该智能体的 permissions.yaml（agent_permissions.add_permission）；
• Workspace——永久允许，写入 autogpt.yaml（workspace_settings.add_permission）；
• Deny——拦截，并把该命令记入会话拒绝列表，同时把用户反馈（feedback）回传给智能体而非执行命令。

值得注意的是，审批时保存的并非精确命令，而是泛化后的模式（_generalize_pattern）：文件路径泛化为父目录（workspace 内用 {workspace}/目录/* 占位符）；shell/python 命令泛化为 可执行文件:**；read_webpage 泛化为按域名的 *domain*。也就是说，用户批准一次"读取某目录下的文件"，实际授权的是该目录的整类操作——设计上是减少打扰，但也意味着审批时应看清泛化后的范围。

基准测试（direct-benchmark）

poetry run direct-benchmark run

该命令对应 direct_benchmark.__main__:main 入口（pyproject.toml）。挑战数据定义在 classic/direct_benchmark/challenges/ 下，按类别组织为 abilities/（读文件、写文件等基础能力）、alignment/（干扰、提示注入等对齐场景）、verticals/（代码、数据、网页抓取等垂直任务）与 library/（如 ethereum 领域任务）；框架本身（classic/direct_benchmark/direct_benchmark/）提供了 harness、runner、evaluator 以及对接 GAIA、SWE-bench、AgentBench 等外部基准的 adapters，其中 SWE-bench 评测需额外安装并依赖 Docker。

测试

poetry run pytest                            # 全部测试
poetry run pytest forge/tests/               # 仅 Forge 测试
poetry run pytest original_autogpt/tests/    # 仅 AutoGPT 测试

pyproject.toml 的 pytest 配置 声明了默认测试路径 forge/forge、forge/tests、original_autogpt/tests，异步模式为 auto，并定义了三个 marker：slow（慢速测试，可用 -m "not slow" 排除）、integration（集成测试）、requires_agent（需要已运行智能体与 API key）。权限逻辑本身也有专门的测试 test_permissions.py 覆盖上述匹配与判定规则。

安全与许可

再次强调 README 的安全边界：该代码库存在已知漏洞，依赖不会更新到新版本，仅限教育与研究用途使用；若需在生产环境运行自主智能体，应评估依赖与权限配置，或改用持续维护的 AutoGPT Platform。许可方面，Classic 这一部分遵循 MIT License，详见仓库根目录的 LICENSE。

小结

AutoGPT Classic 虽已退出维护，但 classic/README.md 所描述的体系仍是一套完整的自主智能体工程范式：单一 Poetry 项目统一三个子包的依赖与入口；环境变量经 UserConfigurable/from_env 机制注入 Pydantic 配置；workspace + 沙箱子目录 + state.json 实现多智能体共存与状态持久化；而"Agent deny → Workspace deny → Agent allow → Workspace allow → 交互式审批"的分层权限链、glob 模式匹配、{workspace} 占位符与审批作用域泛化，则构成了一份值得在自研 Agent 沙箱时参考的设计样本。建议读者从 permissions.py 与 workspace_settings.py 两个文件入手，结合 forge/tests/test_permissions.py 通读一遍，即可完整掌握这套机制的实现细节。