AutoGPT Classic Agent CLI 实战指南：run / serve 双模式、Agent 状态、Workspace 与命令控制

本文基于 AutoGPT 仓库中 classic 子项目的官方使用文档（docs/content/classic/usage.md），系统讲解 AutoGPT Classic Agent 的命令行使用方式：run（CLI 模式）与 serve（Agent Protocol 服务模式）两大运行模式、AI 指令覆盖参数、Agent 状态的保存与恢复、Workspace 沙箱机制、日志排查手段以及通过 DISABLED_COMMANDS 禁用命令的安全实践，并结合仓库源码（cli.py、main.py、.env.template）逐项印证各参数的实际行为，帮你把 Classic Agent 跑起来并安全地用起来。

CLI 入口与整体命令结构

使用本指南的前提是：你处于 autogpt 目录（即 Classic Agent 所在的位置，本仓库中为 classic/original_autogpt）。运行 ./autogpt.sh（或其任意子命令）并附加 --help，可以列出所有可用的子命令与参数：

$ ./autogpt.sh --help
Usage: python -m autogpt [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  run    Sets up and runs an agent, based on the task specified by the...
  serve  Starts an Agent Protocol compliant AutoGPT server, which creates...

从入口源码看，CLI 由 cli.py 中的 Click 命令组实现，run 与 serve 是两个核心子命令。值得注意的是命令组声明了 invoke_without_command=True，当未指定任何子命令时会显式 ctx.invoke(run)——这正是官方文档中提到的"遗留行为"：运行 ./autogpt.sh [OPTIONS] 等价于运行 ./autogpt.sh run [OPTIONS]，官方注明该行为未来可能改变。当前版本的 cli.py 中还可以看到 config 子命令（交互式设置浏览器，默认保存至 ~/.autogpt/.env）以及 run/serve 共用的 --log-level、--log-format、--log-file-format、-w/--workspace 等日志与工作区选项，说明该 CLI 仍在持续演进，具体以 --help 实际输出为准。

Windows 用户注意：在 Windows 上应使用 .\autogpt.bat 代替 ./autogpt.sh，其余子命令与参数完全一致。仓库中现有的 autogpt.bat 会先探测 python3/python，执行依赖检查脚本 scripts/check_requirements.py（缺失时自动 poetry install --without dev），最终通过 poetry run autogpt %* 拉起同一套 CLI。

Docker 用户注意：使用 Docker 时，把示例中的启动脚本替换为 docker compose run --rm auto-gpt（compose 配置见 docker-compose.yml）：

docker compose run --rm auto-gpt --ai-settings <filename>
docker compose run --rm auto-gpt serve

run 子命令 —— CLI 模式

run 子命令以传统 CLI 界面启动 AutoGPT：./autogpt.sh run --help 的完整输出如下（参数说明原样继承自官方文档）：

Usage: python -m autogpt run [OPTIONS]

  Sets up and runs an agent, based on the task specified by the user, or
  resumes an existing agent.

Options:
  -c, --continuous                Enable Continuous Mode
  -y, --skip-reprompt             Skips the re-prompting messages at the
                                  beginning of the script
  -l, --continuous-limit INTEGER  Defines the number of times to run in
                                  continuous mode
  --speak                         Enable Speak Mode
  --debug                         Enable Debug Mode
  --gpt3only                      Enable GPT3.5 Only Mode
  --gpt4only                      Enable GPT4 Only Mode
  --skip-news                     Specifies whether to suppress the output of
                                  latest news on startup.
  --install-plugin-deps           Installs external dependencies for 3rd party
                                  plugins.
  --ai-name TEXT                  AI name override
  --ai-role TEXT                  AI role override
  --constraint TEXT               Add or override AI constraints to include in
                                  the prompt; may be used multiple times to
                                  pass multiple constraints
  --resource TEXT                 Add or override AI resources to include in
                                  the prompt; may be used multiple times to
                                  pass multiple resources
  --best-practice TEXT            Add or override AI best practices to include
                                  in the prompt; may be used multiple times to
                                  pass multiple best practices
  --override-directives           If specified, --constraint, --resource and
                                  --best-practice will override the AI's
                                  directives instead of being appended to them
  --component-config-file TEXT    Path to the json configuration file.
  --help                          Show this message and exit.

该模式支持运行单个 Agent，并在退出时保存 Agent 状态，因此可以稍后**恢复（resume）**一个此前中断的 Agent（详见下文 Agent State 一节）。

从 main.py 的 run_auto_gpt() 调用链可以印证这些参数的底层作用：

• --ai-name / --ai-role / --constraint / --resource / --best-practice 会汇入 AIProfile 与 AIDirectives，通过 apply_overrides_to_ai_settings() 应用到 Agent 的提示词；当且仅当指定了 --override-directives 时是"整体替换"而非"追加"。另外源码中有一个实用细节：只要以上覆盖参数任一非空，程序就会跳过交互式的 AI 设置修订流程（日志提示 "AI config overrides specified through CLI; skipping revision"），方便脚本化、非交互运行。
• --component-config-file 指向一个 JSON 组件配置文件，Agent 创建后会调用 agent.load_component_configs() 加载，加载失败只记录错误日志而不中断运行；等价的配置项是 .env 中的 COMPONENT_CONFIG_FILE。
• 每次 run 启动时，AgentManager 会列出工作区中已有的 Agent 并提示你选择恢复哪一个，或直接创建新 Agent。

Continuous Mode（连续模式）

./autogpt.sh --continuous

该模式让 AI 无需用户逐步授权，100% 自动化地连续执行。官方文档明确警告：连续模式不推荐使用，它潜在危险，可能导致 AI 永远运行下去，或执行你通常不会授权的操作，须自担风险。退出程序按 Ctrl+C。

源码层面（main.py 的 _get_cycle_budget()）可以看到其实现方式：设置了 --continuous-limit N 时循环最多执行 N 次，否则循环预算为无穷大；SIGINT 信号处理器采用两级降级——第一次 Ctrl+C 停止连续执行并提示"再按一次立即退出"，第二次才直接 sys.exit()。同时启用连续模式会在控制台打印一段红色 LEGAL 法律提示（get_legal_warning()）。需要注意：即便在连续模式下，当前实现中每个命令仍会经过权限管理器（CommandPermissionManager）的允许列表/审批流程，并非完全无人把关。

serve 子命令 —— 带 UI 的 Agent Protocol 模式

serve 启动一个符合 Agent Protocol 的 AutoGPT 服务器，为每个任务创建定制 Agent，并对外暴露 API 与前端界面，默认地址为 http://localhost:8000。端口可通过环境变量 AP_SERVER_PORT 配置。

Usage: python -m autogpt serve [OPTIONS]

  Starts an Agent Protocol compliant AutoGPT server, which creates a custom
  agent for every task.

Options:
  --debug                     Enable Debug Mode
  --gpt3only                  Enable GPT3.5 Only Mode
  --gpt4only                  Enable GPT4 Only Mode
  --install-plugin-deps       Installs external dependencies for 3rd party
                              plugins.
  --help                      Show this message and exit.

服务器侧的更多 API 细节可参考 Agent Protocol 官方协议文档（agentprotocol.ai，见原文档外链说明）。结合 main.py 与 agent_protocol_server.py 的源码，该模式的实际行为可以梳理为：

• 端口与绑定：AgentProtocolServer.start() 先检查目标端口是否空闲（被占用时提示设置 AP_SERVER_PORT），然后以 Hypercorn 绑定 localhost:{port}；API 路由挂载在 /ap/v1 前缀下（app.include_router(router, prefix="/ap/v1")）。
• 数据库：默认使用内嵌 SQLite，文件位于工作区的 .autogpt/ap_server.db；可用 AP_SERVER_DB_URL 覆盖（如 sqlite:///data/ap_server.db 或外部数据库连接串）。
• CORS：默认只允许 http://localhost:{AP_SERVER_PORT} 来源，可用 AP_SERVER_CORS_ALLOWED_ORIGINS（逗号分隔）配置额外的允许来源。
• 前端：若构建产物 classic/frontend/build/web 存在，静态文件挂载到 /app，根路径 307 重定向到 /app/index.html；若不存在则仅保留 API。

常用参数与配置文件

官方文档特别提示：大多数命令行参数都等价于配置项，所有可用配置项请见 .env.template（文中 <尖括号> 内的内容替换为你要指定的值）。两个最常用的文件类参数：

• 使用不同的 AI Settings 文件运行：

  ./autogpt.sh --ai-settings <filename>
  

• 使用不同的 Prompt Settings 文件运行：

  ./autogpt.sh --prompt-settings <filename>
  

  部分 flag 有缩写形式（例如 -P 等价于 --prompt-settings），完整列表用 ./autogpt.sh --help 查看。

从 .env.template 可以看到这些参数对应的环境变量全貌，几个与日常运行最相关的条目：

### Workspace ###
## RESTRICT_TO_WORKSPACE - Restrict file operations to workspace (Default: True)
# RESTRICT_TO_WORKSPACE=True

## DISABLED_COMMANDS - The comma separated list of commands that are disabled (Default: None)
# DISABLED_COMMANDS=

### LLM MODELS ###
## SMART_LLM - Smart language model (Default: gpt-4-turbo)
# SMART_LLM=gpt-4-turbo
## FAST_LLM - Fast language model (Default: gpt-3.5-turbo)
# FAST_LLM=gpt-3.5-turbo

### LOGGING ###
## LOG_LEVEL - Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
# LOG_LEVEL=INFO
## LOG_FORMAT - Options: simple, debug, structured_google_cloud
# LOG_FORMAT=simple
## PLAIN_OUTPUT - Disables animated typing and the spinner (Default: False)
# PLAIN_OUTPUT=False

### Agent Protocol Server Settings ###
## AP_SERVER_PORT - (Default: 8000)
# AP_SERVER_PORT=8000
## AP_SERVER_DB_URL - (Default: Internal SQLite)
# AP_SERVER_DB_URL=sqlite:///data/ap_server.db

.env 文件的搜索顺序（先找到者优先）：当前工作目录 ./.env → 用户配置目录 ~/.autogpt/.env → XDG 配置目录 ~/.config/autogpt/.env → 包安装目录；希望全局生效的配置可复制到 ~/.autogpt/.env。配置解析入口在 main.py 中的 ConfigBuilder.build_config_from_env(workspace=workspace)。

Agent State

单个 Agent 的状态（AI 档案、指令、事件历史等）持久化在 data/agents 文件夹下（当前源码中实际落在工作区的 .autogpt 子目录内，即 data_dir = workspace / ".autogpt"，Agent 目录为 data_dir/agents/<agent_id>，见 main.py）。基于这份状态，你可以：

• 稍后恢复 Agent：run 启动时列出已有 Agent，选择编号即可 load_agent_state() 续跑；
• 打"检查点"：复制/保留特定时刻的 Agent 目录，随时回到历史节点；
• 分享你的 Agent：把状态目录交给他人继续运行。

源码中的两处细节印证了这套机制：一是恢复交互（main.py）会打印 "Existing agents" 列表并提示 "Enter the number or name of the agent to run"；二是退出时的 handle_agent_termination()（main.py）允许你在保存状态时"另存为"另一个 ID——这实际上就是官方文档所说"创建检查点"的实现途径。若 Agent 上次以 finish 命令自行结束，恢复时还会提示输入后续任务（follow-up assignment）。

Workspace

Agent 会读写文件，所有文件操作都发生在 workspace 文件夹内（文档路径为 data/agents/<agent_id>/）。该文件夹之外的文件，Agent 一律无法访问——除非把 RESTRICT_TO_WORKSPACE 设置为 False。

官方文档明确警告：不推荐关闭 RESTRICT_TO_WORKSPACE，除非 AutoGPT 运行在一个不会造成损害的沙箱环境（例如 Docker 或虚拟机）中。.env.template 中该项默认值为 True。

源码中的执行逻辑（main.py）：

local = config.file_storage_backend == FileStorageBackendName.LOCAL
restrict_to_root = not local or config.restrict_to_workspace
file_storage = get_storage(
    config.file_storage_backend,
    root_path=workspace,
    restrict_to_root=restrict_to_root,
)

也就是说：只要文件存储后端不是 local，一律强制限制在根目录内；使用 local 后端时则由 RESTRICT_TO_WORKSPACE 决定是否把 Agent 限制在工作区内。run/serve 均提供 -w, --workspace 选项显式指定工作区目录（默认当前目录），Agent 数据存放在其下的 .autogpt/ 子目录中。

Logs

活动、错误与调试日志统一位于 logs 目录（日志目录常量定义在 classic/forge/forge/logging/config.py）。如果你的 Agent 出现奇怪行为、有值得分享的用例、或者要报告 Bug，官方建议你按下述方式打开调试日志，并把日志附在 Issue 报告中：

./autogpt.sh --debug

--debug 隐含 --log-level=DEBUG --log-format=debug；若需更细粒度控制，可单独使用 --log-level（DEBUG/INFO/WARNING/ERROR/CRITICAL）、--log-format 与 --log-file-format（可选值 simple、debug、structured_google_cloud，注意使用 structured_google_cloud 会禁用日志文件输出）。这些同样对应 .env 中的 LOG_LEVEL / LOG_FORMAT / LOG_FILE_FORMAT 配置项；此外 PLAIN_OUTPUT=True 可关闭控制台的动画打字与 spinner 输出，便于管道记录。

Disabling Commands（禁用命令）

禁用命令的最佳方式是禁用或移除提供该命令的组件（component）；若想只做选择性禁用，可在 .env 中使用 DISABLED_COMMANDS 配置：把要禁用的命令名用逗号分隔列出。内置组件的命令清单可参见 commands 与 components。

例如，禁用 Python 编码相关能力：

DISABLED_COMMANDS=execute_python_code,execute_python_file

对应地，.env.template 中该项默认注释掉（Default: None，即不禁用任何命令）。结合 cli.py 与 main.py 的源码结构可以看出，命令执行前会经过 CommandPermissionManager 的审批/允许列表流程，DISABLED_COMMANDS 则是从工具层面直接裁剪 Agent 可用命令集——两者配合，可以按"能力裁剪 + 逐命令审批"两层收紧 Agent 的操作权限，适合在生产或半自动化场景下使用。

小结：一次典型运行的核对清单

1. 进入 autogpt 目录（Windows 用 .\autogpt.bat，Docker 用 docker compose run --rm auto-gpt）；
2. 确认 .env（或 ~/.autogpt/.env）中已配置 LLM API Key、SMART_LLM/FAST_LLM 等模型参数；
3. ./autogpt.sh run 启动，输入任务描述，按提示确认或修改 AI 档案与指令；
4. 需要无人值守时加 --continuous（风险自担），需要限定轮数时加 -l N；
5. 需要 Web 前端与 API 时改用 ./autogpt.sh serve，通过 AP_SERVER_PORT/AP_SERVER_DB_URL 调整端口与数据库；
6. 退出时按需"另存为"新 ID 打检查点；排查问题用 --debug，收紧能力用 DISABLED_COMMANDS。

以上所有命令行输出、配置项默认值与源码行为均以当前仓库中 classic 子项目的实际代码为准（CLI 选项可能随版本演进，使用前请以 --help 实际输出核对）。