AutoGPT Classic 技术解析：自主 Agent、Benchmark 基准、Forge 框架与分层权限体系

本文以 AutoGPT 仓库中 AutoGPT Classic 的官方文档（docs/content/classic/index.md）为主线，系统梳理这个"让 LLM 反复决定下一步行动"的半自主 Agent 项目：它将讲解 AutoGPT Classic 的四大组件（Agent、Benchmark、Forge、Frontend）与统一 CLI 的职责边界，并结合当前仓库 classic/ 目录下的真实源码，深入剖析 Agent CLI 的完整参数、工作区（workspace）目录结构、三层配置体系与"先匹配先裁决"的权限模式系统，帮助你在理解概念后能够实际安装、运行和配置这套经典实验性框架。

什么是 AutoGPT Classic

AutoGPT Classic 诞生于 OpenAI 发布 GPT-4 模型及其阐述模型高级推理与任务求解能力的论文之后。其核心概念简单而深刻：让 LLM 反复自主决定要做什么，并把每次行动的结果回灌到提示词中，从而让程序以迭代、渐进的方式逼近既定目标。

由于程序能代表用户执行操作，它就是一个 Agent（智能体）。在 AutoGPT Classic 中，用户仍须为每一个动作授权；随着项目演进，设计目标是逐步放权，只对部分敏感操作要求用户同意。同时它是一个通才型（generalist）Agent——不为特定任务设计，只要能在计算机上完成，就尝试覆盖跨学科的大范围任务。文档原文也坦承"it isn't quite there yet"：这是仍在追求的最终目标。

位置与维护状态（务必注意）：

• 代码位于仓库中的 classic/original_autogpt/ 目录（对应文档 docs/content/classic/index.md 所述 Location）；
• 官方维护声明明确指出：AutoGPT Classic 从安全角度不再受支持——依赖不会被更新，已知问题不会被修复；若有社区贡献者提交新的开发，官方仅对能通过现有 CI 的变更做尽力合并（best effort）。仓库的 classic/README.md 进一步说明其代码库存在已知漏洞，建议仅将本代码用于学习研究目的，实际使用请转向 AutoGPT Platform（见 docs/content/index.md）。

项目总体架构：四大组件 + 统一 CLI

文档将 AutoGPT Classic 划分为四个主要组件，再由一个位于项目根部的 CLI 把它们串联起来：

组件	别称 / 目录	职责	当前仓库对应位置
Agent	"AutoGPT Classic" 本体	由 LLM 驱动的半自主 Agent，执行用户任务	classic/original_autogpt/
Benchmark	agbenchmark	衡量 Agent 性能的严格测试环境，支持 Agent Protocol	classic/direct_benchmark/
Forge	—	现成的 Agent 应用模板，免去样板代码	classic/forge/
Frontend	—	面向任意 Agent Protocol 合规 Agent 的开源前端界面	见下文说明
CLI	项目根入口	安装依赖、创建/启动/停止 Agent、运行基准测试	见下文说明

从源码结构看，当前仓库将上述组件整合进 classic/ 下的单一 Poetry 项目（单一 classic/pyproject.toml 与 classic/poetry.lock），目录组织与 classic/CLAUDE.md 中给出的结构一致：

classic/
├── pyproject.toml          # 单一整合的 Poetry 项目
├── poetry.lock
├── forge/                  # 核心自主 Agent 框架
│   └── forge/              # agent、llm、components、config、file_storage 等包
├── original_autogpt/       # AutoGPT Agent 实现
│   └── autogpt/            # app、agents、agent_factory 等包
├── direct_benchmark/       # 基准测试 harness
│   └── direct_benchmark/   # CLI 与 harness 代码
└── benchmark/              # 挑战定义（数据而非代码，历史路径）

需要说明两点历史演变：其一，文档描述的 ./run 根脚本（Usage: cli.py [OPTIONS] COMMAND）在当前快照的仓库根目录中已不存在，当前实际的运行入口改为在 classic/ 目录下通过 Poetry 调用 autogpt、forge、direct-benchmark 等可执行入口；其二，文档中提到的 classic/frontend/ 目录在当前仓库的 classic/ 下也未再保留，可以推断前端部分已从当前 classic 代码树中分离。

组件一：Agent（AutoGPT Classic 本体）

AutoGPT Classic 是整个项目的起点与"心脏"：一个由 LLM 驱动、能够为你执行任何任务的半自主 Agent。其源码入口是 classic/original_autogpt/autogpt/ 包，关键模块包括：

• classic/original_autogpt/autogpt/app/main.py：run 与 serve 两条主流程的实现（run_auto_gpt / run_auto_gpt_server）；
• classic/original_autogpt/autogpt/app/agent_protocol_server.py：Agent Protocol 服务器，为每个任务创建定制 Agent；
• classic/original_autogpt/autogpt/agents/agent.py：Agent 核心实现；
• classic/original_autogpt/autogpt/agent_factory/：Agent 创建逻辑（default_factory.py、generators.py、configurators.py、profile_generator.py）。

Agent CLI 的完整命令与参数

CLI 定义在 classic/original_autogpt/autogpt/app/cli.py，基于 click 构建，包含三个子命令。不带子命令时默认执行 run（源码注释说明这是出于兼容旧版的考虑）。

autogpt run——按用户给定的任务设置并运行一个 Agent，或恢复已有 Agent（cli.py#L24-L176）：

选项	说明
-c, --continuous	启用连续模式（Continuous Mode），Agent 无需每步确认
-l, --continuous-limit INTEGER	定义连续模式下的运行轮数上限
--speak	启用语音模式
--install-plugin-deps	安装第三方插件的外部依赖
--skip-news	抑制启动时的"最新新闻"输出
-y, --skip-reprompt	跳过脚本开头的重复提示
--ai-name TEXT	覆盖 AI 名称
--ai-role TEXT	覆盖 AI 角色
--constraint TEXT（可多次）	向提示词追加/覆盖 AI 约束
--resource TEXT（可多次）	向提示词追加/覆盖 AI 资源
--best-practice TEXT（可多次）	向提示词追加/覆盖 AI 最佳实践
--override-directives	指定后，上述三项覆盖而非追加默认 directives
--debug	隐含 --log-level=DEBUG --log-format=debug
--log-level	日志级别（取 DEBUG/INFO/WARNING/ERROR 等标准级别）
--log-format / --log-file-format	控制台与日志文件各自的格式；structured_google_cloud 格式会禁用日志文件输出
--component-config-file TEXT	指向组件 JSON 配置文件（必须存在且为文件）
-w, --workspace PATH	工作区目录，默认为当前目录；Agent 数据存于其 .autogpt/ 子目录

autogpt serve——启动符合 Agent Protocol 的 AutoGPT 服务器，为每个任务创建定制 Agent，并对外提供 API 与前端，默认监听 http://localhost:8000（cli.py#L179-L238）。可选 --debug、--install-plugin-deps、--log-level/--log-format/--log-file-format 以及 -w, --workspace。

autogpt config——打开一个交互式设置浏览器（SettingsUI），用 Tab/1-9 切换分类、方向键导航、Enter 编辑、S 保存、Q 退出；设置保存到 .env 文件（默认 ~/.autogpt/.env），AutoGPT 启动时会读取（cli.py#L241-L261）。

文档中的根 CLI 用法（历史形态）

原始文档记录的根级 CLI 用法如下，保留在此供对照：

$ ./run setup   # 安装系统所需依赖后即可使用

$ ./run
Usage: cli.py [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  agent      Commands to create, start and stop agents
  benchmark  Commands to start the benchmark and list tests and categories
  setup      Installs dependencies needed for your system.

常用命令：

• ./run agent start autogpt——运行 AutoGPT Classic Agent；
• ./run agent create <name>——在 agents/<name> 下创建一个基于 Forge 的新 Agent 项目；
• ./run benchmark start <agent>——对指定 Agent 执行基准测试。

在当前仓库中，等价操作按 classic/CLAUDE.md 与 classic/README.md 从 classic/ 目录执行：

# 运行 forge agent
poetry run python -m forge

# 运行 original autogpt 服务器（默认 http://localhost:8000）
poetry run serve --debug

# 运行 autogpt CLI（无子命令时默认 run）
poetry run autogpt

组件二：Benchmark（agbenchmark / direct-benchmark）

Benchmark 用于测量 Agent 的性能：它对任何支持 Agent Protocol 的 Agent 都可用，并与项目 CLI 集成，使 AutoGPT Classic 及基于 Forge 的 Agent 能直接接入。它提供严格的测试环境，框架支持自主、客观的性能评估，确保 Agent 面向真实场景做好准备。

从源码结构看，基准测试由 classic/direct_benchmark/direct_benchmark/ 包承载（含 runner.py、harness.py、evaluator.py、challenge_loader.py、report.py、ui.py 等模块），而挑战（challenges）定义在 classic/direct_benchmark/challenges/ 下，按类别组织为 abilities、alignment、library、verticals 等目录，并配有 CHALLENGE.md 说明如何编写挑战。

典型用法（均来自 classic/CLAUDE.md）：

# 运行基准测试
poetry run direct-benchmark run

# 指定策略与模型，4 路并行
poetry run direct-benchmark run \
    --strategies one_shot,rewoo \
    --models claude \
    --parallel 4

# 只运行单个测试
poetry run direct-benchmark run --tests ReadFile

# 列出可用命令
poetry run direct-benchmark --help

值得注意的是，文档同时强调 AutoGPT Classic 采用 AI Engineer Foundation 提出的 Agent Protocol 标准，以保证与项目内外众多 Agent 的兼容性——这也是 serve 命令、Benchmark 与 Frontend 三者能够互通的协议基础。

组件三：Forge（构建自己的 Agent）

Forge 是一个"开箱即用"的 Agent 应用模板：所有样板代码已处理完毕，开发者可以把创造力集中在让自己的 Agent 与众不同的部分（个性与能力）上。

从源码结构看，forge 包是整个 classic 的基础框架，其他组件都依赖它（见 classic/CLAUDE.md 的 Architecture 一节）：

• forge/agent/——Agent 实现与协议（如 BaseAgent，导入方式为 from forge.agent.base import BaseAgent）；
• forge/llm/——多供应商 LLM 集成（OpenAI、Anthropic、Groq 等）；
• forge/components/——可复用的 Agent 组件（约 57 个 Python 文件）；
• forge/file_storage/——文件系统抽象（支持 local/s3/gcs）；
• forge/config/——配置管理；
• forge/permissions.py——权限系统实现，被上层 Agent 复用。

Forge 概念文档入口为 docs/content/forge/get-started.md，组件文档位于 docs/content/forge/components/。

工作区（Workspace）：Agent 数据在哪里

文档与源码一致地描述了 Agent 的"家"——工作区：一个包含该 Agent 全部数据与文件的目录，默认为当前工作目录。其标准结构如下（引自 classic/CLAUDE.md 与 classic/original_autogpt/README.md）：

{workspace}/
├── .autogpt/
│   ├── autogpt.yaml              # 工作区级权限
│   ├── ap_server.db              # Agent Protocol 数据库（serve 模式）
│   └── agents/
│       └── AutoGPT-{agent_id}/
│           ├── state.json        # Agent 画像、directives、行动历史
│           ├── permissions.yaml  # 该 Agent 的权限覆盖
│           └── workspace/        # 该 Agent 的沙箱工作目录

关键特性：

• 多个 Agent 可共存于同一工作区（各自占用独立子目录）；
• 文件访问默认被沙箱化到该 Agent 的 workspace/ 子目录内；
• 状态通过 state.json 持久化，跨会话可恢复（对应 run 子命令"或恢复已有 Agent"的语义）；
• 存储后端可通过环境变量 FILE_STORAGE_BACKEND 切换为 local、s3、gcs。

三层配置体系与权限系统

AutoGPT Classic 采用分层配置系统，按优先级从高到低分为三层。这是理解其安全模型的核心。

第 1 层：环境变量（全局，.env）

复制模板后填入 API Key（模板见 classic/original_autogpt/.env.template）：

# 必需
OPENAI_API_KEY=sk-...

# 可选 LLM 设置
SMART_LLM=gpt-4o                    # 复杂推理用模型
FAST_LLM=gpt-4o-mini                # 简单任务用模型
EMBEDDING_MODEL=text-embedding-3-small

# 可选搜索提供商（Web 搜索组件）
TAVILY_API_KEY=tvly-...
SERPER_API_KEY=...
GOOGLE_API_KEY=...
GOOGLE_CUSTOM_SEARCH_ENGINE_ID=...

# 可选基础设施
LOG_LEVEL=DEBUG                     # DEBUG、INFO、WARNING、ERROR
DATABASE_STRING=sqlite:///agent.db  # Agent Protocol 数据库
PORT=8000                           # 服务端口
FILE_STORAGE_BACKEND=local          # local、s3 或 gcs

更多配置项说明见 docs/content/classic/configuration/options.md（可选项总表）、docs/content/classic/configuration/search.md（搜索提供商）与 docs/content/classic/configuration/voice.md（语音）。

第 2 层：工作区设置（{workspace}/.autogpt/autogpt.yaml）

对工作区内所有 Agent 生效的权限；缺失时会自动生成合理默认值：

allow:
  - read_file({workspace}/**)
  - write_to_file({workspace}/**)
  - list_folder({workspace}/**)
  - web_search(*)

deny:
  - read_file(**.env)
  - read_file(**.env.*)
  - read_file(**.key)
  - read_file(**.pem)
  - execute_shell(rm -rf:*)
  - execute_shell(sudo:*)

第 3 层：Agent 设置（{workspace}/.autogpt/agents/{id}/permissions.yaml）

单个 Agent 的权限覆盖：

allow:
  - execute_python(*)
  - web_search(*)

deny:
  - execute_shell(*)

文件	作用域	位置
autogpt.yaml	工作区内所有 Agent	.autogpt/autogpt.yaml
permissions.yaml	单个 Agent	.autogpt/agents/{id}/permissions.yaml

权限判定顺序（First Match Wins）

权限系统使用模式匹配，判定顺序固定（Agent 侧的 deny 优先级最高，其次是工作区 deny，依次放行）：

1. Agent deny 列表 → 拦截
2. 工作区 deny 列表 → 拦截
3. Agent allow 列表 → 放行
4. 工作区 allow 列表 → 放行
5. 会话内被拒列表 → 拦截（本次会话中已被用户拒绝的命令）
6. 询问用户 → 交互式审批（交互模式下）

模式语法：command_name(glob_pattern)，其中 {workspace} 会被替换为实际工作区路径，** 匹配任意路径（含 /），* 匹配除 / 外的任意字符。示例：

模式	含义
read_file({workspace}/**)	读取工作区内任意文件（递归）
write_to_file({workspace}/*.txt)	只允许写工作区根目录下的 .txt 文件
execute_shell(python:**)	只允许执行 Python 命令
execute_shell(git:*)	允许任意 git 命令
web_search(*)	允许所有 Web 搜索

交互式审批的作用域：当系统提示授权时，用户可以选择四种粒度——

作用域	效果
Once	仅本次放行（不保存）
Agent	对该 Agent 永久放行（写入 permissions.yaml）
Workspace	对全部 Agent 永久放行（写入 autogpt.yaml）
Deny	拒绝该命令（写入相应 deny 列表）

默认安全基线（开箱即拦截）：读取敏感文件（.env、.key、.pem）、破坏性 shell 命令（rm -rf、sudo）、工作区目录之外的任何操作。该模型与文档"用户仍须为每个动作授权，随项目演进逐步放权"的表述完全呼应——权限系统正是"半自主"落地的机制载体。

安装与运行速查

前置条件（以当前仓库 classic/original_autogpt/README.md 为准）：

• Python 3.12+
• Poetry
• OpenAI API Key

安装与启动（所有命令从 classic/ 目录执行）：

cd classic
poetry install
cp .env.template .env     # 模板实际位于 original_autogpt/.env.template，放入后填入 OPENAI_API_KEY

poetry run python -m forge        # Forge 模板 Agent
poetry run serve --debug          # AutoGPT Agent Protocol 服务器
poetry run autogpt                # AutoGPT 经典 CLI（默认 run 子命令）

测试（需要 API Key 的测试在未设置对应变量时会自动跳过）：

poetry run pytest                                  # 全部测试
poetry run pytest forge/tests/                     # 仅 Forge
poetry run pytest original_autogpt/tests/          # 仅 AutoGPT
poetry run pytest -k test_name                     # 按名称跑单个测试
poetry run pytest --cov                            # 带覆盖率

更完整的安装流程（含 Docker 与开发者环境）见 docs/content/classic/setup/index.md 与 docs/content/classic/setup/docker.md，测试规范见 docs/content/classic/testing.md。

术语表（Glossary）

继承原文档的术语约定，便于跨文档阅读时对齐概念：

• Repository（仓库）：项目代码所在之处。
• Forking（派生）：将仓库复制到自己名下。
• Cloning（克隆）：制作仓库的本地副本。
• Agent（智能体）：你将要创建和开发的 AutoGPT。
• Benchmarking（基准测试）：在基准框架中测试 Agent 的技能。
• Forge：构建 AutoGPT Agent 的模板。
• Frontend（前端）：用于任务、日志与任务历史的 UI。

小结与延伸阅读

AutoGPT Classic 是"LLM 自主决策循环"这一范式的经典实现：Agent 本体负责执行、Benchmark 负责客观度量、Forge 负责降低开发门槛、Frontend 负责交互呈现，统一的 CLI 与工作区/权限体系把"每个动作需授权"的半自主原则落到了文件与模式匹配的层面。需要再次强调：该组件已处于不支持维护状态，依赖不再更新，适合作为研究自主 Agent 架构与权限模型的范本，生产场景请使用 AutoGPT Platform。

继续深入可阅读：Agent 使用指南 docs/content/classic/usage.md、Forge 入门 docs/content/forge/get-started.md、平台文档 docs/content/index.md，以及各组件源码入口 classic/original_autogpt/autogpt/app/cli.py、classic/forge/forge/、classic/direct_benchmark/direct_benchmark/runner.py。