AutoGPT Platform 安装部署全指南：一键安装脚本、手动安装与完全离线本地 LLM 方案

导读：AutoGPT Platform 为 Linux、macOS 与 Windows 提供了开箱即用的安装脚本（setup-autogpt.sh / setup-autogpt.bat），帮助你自动完成环境检查、仓库克隆、Docker 后端与前端启动的全过程。本文以官方安装文档 docs/platform/installer.md 为核心骨架，结合仓库内两个安装脚本的真实源码逐行讲解其行为，并完整覆盖 --with-ollama 离线部署模式——让 AutoPilot 对话在没有任何云端 API Key 的情况下也能完全本地运行。读完你既能"一键装机"，也能在隔离、隐私敏感的网络环境中自主搭建可用的本地 LLM 平台。

安装器做什么：从环境检查到服务启动的五步流程

根据 installer.md 的说明，安装脚本会依次完成以下五件事：

1. 检查必需前置条件（Git、Docker、npm，以及 --with-ollama 模式下的 curl）；
2. 克隆 AutoGPT 仓库；
3. 用 Docker 启动后端服务；
4. 启动前端应用；
5. 同时运行后端与前端服务。

对照仓库内脚本源码，这一流程在 setup-autogpt.sh 的 main() 函数中有清晰的映射：check_prerequisites → detect_repo → clone_repo →（可选）bootstrap_ollama + write_local_env → run_docker，最终打印 Setup Complete! 并提示访问地址。

值得留意的是，实际脚本源码中前端并非单独以 npm 进程启动——从 docker-compose.yml 可以看到 frontend 服务同样通过 Docker Compose 运行（extends 自 docker-compose.platform.yml），整个后端 + 前端栈都在同一套 Compose 编排之内。因此官方文档所说的"用 Docker 启动后端、启动前端"在现代实现中统一收敛为一条 docker compose up -d 命令。

前置条件清单

运行安装脚本前，机器上必须准备好：

依赖	用途	版本与说明
Git	克隆 AutoGPT 仓库	若在已有仓库内运行脚本（检测到 .git），可跳过克隆步骤
Docker	运行后端与前端全部容器化服务	脚本会尝试 docker info；失败时自动退化为 sudo docker 前缀执行
curl	仅 --with-ollama 模式需要	用于下载 Ollama 安装脚本并对本地/远端 Ollama 做 API 探测（源码检查点）
Node.js / npm	文档提及的前端依赖	现代 Docker 化部署中由前端镜像封装，无需宿主机单独预装

脚本对宿主机 OS 有明确的家族检测（uname -s 判定 Linux / Darwin），其他系统会直接以 Unsupported OS 报错并提示 Windows 用户改用 .bat 脚本（见 setup-autogpt.sh）。

快速一键安装（Quick One-Liner）

官方为习惯脚本管道的用户提供了托管在 setup.agpt.co 的一键命令，执行前请确保上面三（或四）项前置条件已就绪：

Linux / macOS

curl -fsSL https://setup.agpt.co/install.sh -o install.sh && bash install.sh

Windows（PowerShell）

powershell -c "iwr https://setup.agpt.co/install.bat -o install.bat; ./install.bat"

这两种形式下载的正是仓库内维护的两份脚本，等同"先下载、后执行"：下载完成后可先浏览脚本内容（脚本自带 --help / /help 帮助输出），确认无异议再运行。这也意味着离线或内网环境无法访问 setup.agpt.co 时，完全可以从仓库手动获取脚本（见下一节）。

手动安装：直接从仓库运行安装脚本

如果你更信任仓库内的脚本本身（也适用于审阅后再执行、离线拷入、或自定义改造的场景），官方推荐直接使用：

• Linux/macOS：setup-autogpt.sh
• Windows：setup-autogpt.bat

两者位于仓库的 autogpt_platform/installer/ 目录下，即 autogpt_platform/installer/setup-autogpt.sh 与 autogpt_platform/installer/setup-autogpt.bat。获取到脚本后按对应平台执行即可：

# Linux / macOS（脚本带有可执行位可直接运行，否则使用 bash 前缀）
bash setup-autogpt.sh

REM Windows
setup-autogpt.bat

脚本源码级行为剖析

两个脚本在功能上对齐，但从源码看有几处值得关注的设计：

• 智能仓库探测：脚本并非"无条件克隆"。当检测到当前路径已在仓库内（PWD 处于 */autogpt_platform/installer 且上层存在 .git，或当前目录本身就是仓库根）时，直接复用已有仓库；只有身处陌生目录时才克隆 https://github.com/Significant-Gravitas/AutoGPT.git 到当前目录的 AutoGPT/ 子目录（detect_repo / clone_repo）。
• Docker 权限自适应：docker info 失败时，脚本会把内部命令切换为 sudo docker / sudo docker compose，避免用户在无权限组环境中手工加 sudo（check_prerequisites）。
• 完整日志落盘：Compose 输出写入 autogpt_platform/logs/docker_setup.log，失败时脚本会引导你查看该文件并提示常见原因（Docker 未运行、磁盘不足、端口冲突如 3000 / 8006 被占用）。
• 参数兼容差异（Windows 特殊性）：cmd.exe 会把 /ollama-model=foo 中的 = 当作参数分隔符拆成两个 token，因此 .bat 同时支持 /ollama-model=NAME 与 /ollama-model NAME（空格形式）两种写法并额外 shift 一次（setup-autogpt.bat）；.sh 则由 bash 保持 --ollama-model=foo 为单参数，无此问题。

完全离线运行：使用本地 LLM（Ollama）部署 AutoPilot

官方文档用专门章节强调：两个安装脚本都支持一个可选的启用开关，用于安装 Ollama、拉取默认聊天模型、并写入 backend/.env，使 AutoPilot 无需任何云端 API Key 即可运行。这对气隙（air-gapped）或隐私敏感部署尤其有价值。

该模式的核心配置语义在配套参考文档 docs/platform/copilot-local-llm.md 中有更完整的阐述：AutoPilot 的 ChatConfig 通过 CHAT_USE_LOCAL=true 切换到名为 local 的传输层，只要目标端点能讲 OpenAI 的 /v1/chat/completions 协议（含 tools=[...] 函数调用），Ollama、vLLM、LocalAI、LM Studio、LiteLLM Proxy 乃至受管 OpenAI 兼容 API 全部适用。注意：本文仅覆盖 AutoPilot 对话路径（/copilot）；若需在自建 Agent 图里使用 AI Text Generator 块，请另见 docs/platform/ollama.md（两条路径读取不同的环境变量）。

Linux / macOS 启用方式

cd autogpt_platform/installer
./setup-autogpt.sh --with-ollama
# 可选参数：
#   --ollama-model=qwen3:14b-instruct-q4_K_M
#   --ollama-host=http://gpu-rig.lab:11434   # 复用一台已有的 Ollama 服务器

Windows 启用方式

cd autogpt_platform\installer
setup-autogpt.bat /with-ollama
REM 可选参数：
REM   /ollama-model=qwen3:14b-instruct-q4_K_M
REM   /ollama-host=http://gpu-rig.lab:11434

两个脚本还都支持 -h / --help（Linux/macOS）与 /help、/h（Windows）输出帮助。

离线模式下安装器实际执行的四个步骤

对照源码，--with-ollama 模式会走 bootstrap_ollama → write_local_env 两条子流程，官方文档归纳为四件事：

1. 安装 Ollama——已在系统上（或 --ollama-host 指向现成实例）则跳过：
   • Linux：curl -fsSL https://ollama.com/install.sh | sh，随后写入 systemd drop-in（bootstrap 逻辑）；
   • macOS：优先走 Homebrew，但刻意安装 cask ollama-app 而非 ollama formula——因为该 formula 的 darwin-arm64 包缺少 llama-server runner，能拉模型却会在每次 GGUF 推理时 500（macOS 分支）；无 Homebrew 时报错引导手动下载官方 .dmg；
   • Windows：优先 winget install --id Ollama.Ollama --silent ...，无 winget 则引导到官方安装包（setup-autogpt.bat 的 bootstrap 子例程）。
2. 配置 OLLAMA_HOST=0.0.0.0:11434 与 OLLAMA_CONTEXT_LENGTH=32768，使容器可达，并避免 AutoPilot 约 8k token 的 system prompt 被 Ollama 默认 4k 上下文截断。三个平台的落点不同：Linux 写入 systemd drop-in /etc/systemd/system/ollama.service.d/host.conf；macOS 用 launchctl setenv 写入 launchd 环境表并重启 Ollama；Windows 用 setx 写入用户环境并重启进程。
3. 拉取聊天模型，默认 hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M（可通过 --ollama-model 覆盖）。
4. 在 autogpt_platform/backend/.env 追加一块带起止标记（marker）的配置，包含 CHAT_USE_LOCAL=true 与 CHAT_BASE_URL / CHAT_API_KEY / CHAT_*_MODEL 覆盖项。

--ollama-host：指向现成 Ollama 时的智能归一化与校验

若局域网内已有一台 GPU 服务器跑着 Ollama，可用 --ollama-host 跳过本地安装。脚本会：

• 自动剥离尾部 / 与可选的 /v1 后缀——这样无论传 http://host:11434 根地址，还是直接抄一段 CHAT_BASE_URL（形如 .../v1）都不会出错（归一化处理）；
• 用 curl /api/version 探测可达性（不可达直接报错，提示"是否正在监听 0.0.0.0"）；
• 检查目标模型的 api/tags，缺失才发起 /api/pull，且用 grep -F 固定字符串匹配避免模型名中的 .、: 被当作正则元字符；
• 对 /api/pull 返回的 NDJSON 流显式检查 "error" 与 "status":"success" 帧——因为拉取失败时 HTTP 状态可能仍是 200，仅靠 curl -f 会"假成功"。

幂等重跑与精确的 .env 覆写

官方文档明确承诺：重复执行 --with-ollama 是幂等的，配置块会被原地重写。实现上的关键点（见 write_local_env）：

• 写入块用 # === Local-LLM AutoPilot wiring ... === 起始标记和 # === End Local-LLM AutoPilot wiring === 结束标记包围；
• 重跑时先按起止标记区间删除旧块再追加新块，而非"删到文件末尾"，从而不会误删用户在标记块之后自行添加的配置行；
• 文件不存在时先从 .env.default 复制（Linux 版本；Windows 版本用 copy /Y .env.default .env 对应处理）。

最终写入的配置块内容为（以 Linux 为例）：

# === Local-LLM AutoPilot wiring (added by setup-autogpt.sh --with-ollama) ===
# See docs/platform/copilot-local-llm.md for the full reference.
CHAT_USE_LOCAL=true
CHAT_BASE_URL=http://<宿主机LAN-IP>:11434/v1
CHAT_API_KEY=ollama
CHAT_FAST_STANDARD_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
CHAT_FAST_ADVANCED_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
OLLAMA_HOST=http://<宿主机LAN-IP>:11434
# === End Local-LLM AutoPilot wiring ===

容器访问宿主机的网络细节：为什么不是 127.0.0.1

安装器会为 CHAT_BASE_URL 智能挑选宿主机地址，这是"离线可用"成败的关键，背后逻辑因平台而异（地址推导源码）：

• Linux（原生 Docker）：容器里没有自动注入的 host.docker.internal，脚本用 hostname -I 取宿主机第一个非回环 IPv4，容器经 Docker bridge 即可访问；拿不到时回退 127.0.0.1（此时需手动覆写 CHAT_BASE_URL）。
• macOS + Docker Desktop：探测 docker context show 结果为 desktop-linux / default 时使用 http://host.docker.internal:11434（Desktop 自动注入该条目）；若是 Colima / Rancher Desktop / Lima 这类不注入的运行时，则改取 ipconfig getifaddr en0/en1 得到 LAN IP。
• Windows：Docker Desktop 同样自动注入 host.docker.internal，.bat 直接使用之。

之所以不用 127.0.0.1：容器内的回环地址指向容器自身，并非宿主机。而在另一台局域网机器或公网提供 Ollama 时，CHAT_BASE_URL 直接填目标主机名/IP，如 http://gpu-rig.lab.local:11434/v1（详见 copilot-local-llm.md 的部署形态表）。

.env 变量语义与源码依据

上述写入项在 backend/.env.default 中均有注释说明，含义如下：

变量	含义	离线模式取值
CHAT_USE_LOCAL	开启 local 传输层；.env.default 默认 false	true
CHAT_BASE_URL	OpenAI 兼容端点地址，容器内不可用回环地址	http://<host>:11434/v1
CHAT_API_KEY	任意非空字符串（Ollama 不校验）；local 传输刻意不回退到 OPENAI_API_KEY	ollama
CHAT_FAST_STANDARD_MODEL	聊天主模型，只接受裸模型名；anthropic/... 这类 provider/model 前缀 slug 会被原样传给 Ollama 而无法解析	hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
CHAT_FAST_ADVANCED_MODEL	高级档模型，缺省时由 fast_standard 自动派生	同左
OLLAMA_HOST	指向块层（block）AI 文本生成所用的同一后端，让构建器里的相关块也复用本机 LLM	http://<host>:11434

值得强调的源码事实：local 传输层下，title_model（对话标题）、simulation_model（干跑模拟器）与 CHAT_FAST_ADVANCED_MODEL 都会从 CHAT_FAST_STANDARD_MODEL 自动派生（见 ChatConfig 的 _apply_local_aux_models，实现在 backend/backend/copilot/config.py），所以安装器无需显式写出三者。另一方面，extended_thinking（SDK/扩展思维）模式因依赖 Anthropic 私有协议会自动降级到 fast 路径，安装完成后终端会给出对应提示。关于模型选型、上下文窗口设置、Graphiti 记忆层在本地传输下的默认改写（GRAPHITI_LLM_MODEL 改写为同一 Qwen 模型、GRAPHITI_EMBEDDER_MODEL 改写为 nomic-embed-text 并需额外 ollama pull nomic-embed-text）等更深入话题，请参阅 docs/platform/copilot-local-llm.md。

安装完成后的验证

官方文档提示安装完成后应确认两件事：

• 后端各服务正在 Docker 容器中运行；
• 前端应用可从 http://localhost:3000 访问。

从 setup-autogpt.sh 与 setup-autogpt.bat 的收尾输出还能看到更多信息：API 基址为 http://localhost:8006，--with-ollama 模式还会提示 AutoPilot 已接线到 Ollama（模型名随附）。若要用 Docker 查看服务明细，可在仓库的 autogpt_platform/ 目录执行：

docker compose ps
docker compose logs -f

离线模式下推荐按官方参考文档做端到端验证（Verifying the wiring）：docker exec 检查容器内是否有 CHAT_USE_LOCAL=true、在 UI 发一条消息后从日志确认 Using baseline service、并在 Ollama 侧日志（Linux journalctl -u ollama、macOS tail -F ~/.ollama/logs/server.log、Windows %LOCALAPPDATA%\Ollama\server.log）看到返回 200 的 POST /v1/chat/completions。

停止服务

安装完成后若需停止整套服务：在运行前端的终端按 Ctrl+C，然后执行：

cd AutoGPT/autogpt_platform
docker compose down

脚本源码给出的等效提示也是 docker compose down（停止）与 docker compose logs -f（跟随日志），且强调所有命令都应在 autogpt_platform/ 目录下执行（见 main() 收尾）。注意 docker compose down 不会删除镜像与数据卷；如需连数据一并清理，可另用 docker compose down -v（谨慎，会清空数据库卷）。

故障排查（Troubleshooting）

官方文档给出的通用排查顺序：

1. 确认所有前置条件安装正确；
2. 检查 Docker 是否正在运行；
3. 确保网络连接稳定（首次运行需拉取多个容器镜像）；
4. 确认你拥有创建目录、运行 Docker 的足够权限。

结合脚本源码与配套文档，补充以下高频问题的定位思路：

• Compose 启动失败：优先查看 autogpt_platform/logs/docker_setup.log；脚本提示的常见原因包括 Docker 未运行、磁盘空间不足、以及 3000 / 8006 等端口冲突（用 docker compose ps 确认端口占用）。
• Ollama 装好但 AutoPilot 报 connection refused：典型原因是容器访问宿主机路径不对。确认 CHAT_BASE_URL 用的是 LAN IP 或 host.docker.internal（而非容器内无意义的 127.0.0.1），并确认 Ollama 已 OLLAMA_HOST=0.0.0.0:11434 监听所有接口。
• model "..." not found：先在 Ollama 侧 ollama pull <完整模型slug> 补齐模型（默认模型为 hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M）。
• api_key 为 None 但已设 OPENAI_API_KEY：这是设计行为——local 传输层要求显式 CHAT_API_KEY，不会让为 graphiti/embedder 而设的云端 key 静默充当本地端点的 bearer token。
• 标题生成失败 / 显示 "Untitled chat"：确认没有显式残留 CHAT_TITLE_MODEL=openai/gpt-4o-mini 之类的云默认值（local 传输下 title_model 应自动继承 fast_standard_model）。
• CPU 上首轮回复极慢：属预期现象。AutoPilot 携带约 8k token 的 system prompt，Ollama 必须先完成整个 prompt 的 prefill 才开始生成；CPU-only 主机上 8B Q4 模型 prefill 约 3–4 token/s，首轮可能要几十分钟，可用 POST /v1/chat/completions 返回 200 作为 prefill 完成的判据，加装消费级 GPU 可将耗时降到秒级。

小结

AutoGPT Platform 的安装器把"检查环境 → 克隆仓库 → 编排整套容器服务"压缩为一行命令（setup-agpt.co 一键脚本或仓库内 setup-autogpt.sh / setup-autogpt.bat）；--with-ollama 开关则进一步把 AutoPilot 的 LLM 依赖整体迁移到本机或局域网内的 Ollama 实例，让平台在零云端 API Key 的隔离环境中也能完整运转。阅读脚本源码（setup-autogpt.sh、setup-autogpt.bat）与配套深度参考 docs/platform/copilot-local-llm.md，有助于你在离线部署、GPU 服务器复用、模型替换等场景下做出正确的配置决策。