SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

如何自托管 Agentlas OS:VPS 安装与配置指南

在 Linux VPS 上自托管 Agentlas OS v1.2.0。本指南详述如何锁定安装版本、配置 Ollama 模型路径、管理代理状态存储,并分析无常驻进程架构下的真实资源开销。

Agentlas OS 的实际形态

Agentlas OS 是一个开源代理运行时。它将专用代理以软件包形式保存在磁盘上,并为每项任务组装一个临时编排器。您可以将它安装到 Linux VPS 上自己的用户账户中,从而自行托管。下面固定使用 v1.2.0 命令行安装方式。这不是一个服务:安装程序不会启用守护进程,也不会打开监听端口。当前项目还提供了单独的桌面应用文档。

这一点决定了本页其余内容的理解方式。大多数多代理系统都会运行一个持续存在的监督进程,并由它持有各个代理。Agentlas 则相反:专用代理以文件形式静态存储,编排器只在任务运行期间存在。实际结果是,空闲的中心节点只占用磁盘空间,不占用内存。

该项目将其开放核心称为 Hephaestus。您会在命令、路径和环境变量中看到这个名称。该仓库位于 agentlas-ai/Agentlas-OS,采用 Apache-2.0 许可证,主要使用 Python 编写。

这个项目究竟有多早期

截至 2026 年 10 月 13 日的记录显示,该仓库创建约 4 个月,约有 1,580 个 star 和 110 个 fork。对于要用于实际工作的项目来说,这仍然很早期。

发布节奏比项目年龄更重要。版本 v1.1.103 于 2026 年 8 月 8 日发布,v1.2.0 于 2026 年 8 月 12 日发布。1.1 系列已经发布了 100 多个带标签的版本,有些日期甚至发布多个版本,并且由自动化流程完成。1.2 系列也保持了这一速度:截至 2026 年 10 月 10 日,已经发布到 v1.2.62。更新如此频繁的项目,可能在周二和周四之间就改变行为。

因此,请固定版本。安装程序通过环境变量读取版本号,下面的整篇指南都会使用该变量。对于这样高频发布的项目,如果不固定版本,安装程序就会安装脚本最近一次编辑时最新发布的版本。

VPS 上的要求

要求很少,因为空闲的专家是文件,而不是进程。

  • 一台 Linux VPS。Ubuntu 24.04 是合适的基线。安装程序使用 uname -s 检测操作系统,并在 Linux 上选择非 macOS 分支,因此支持无头服务器。
  • 服务器上需要有 curl、tar 和 git,以及 Python 3.9 或更高版本。固定版本的安装程序使用 Python 检查随附的嵌入模型。
  • 正常安装需要能够通过出站 HTTPS 访问 raw.githubusercontent.com 和 github.com。安装程序会下载发行版归档文件并校验其 SHA-256。当前的独立安装程序会使用 standalone_local_source_unverified 拒绝 HEPHAESTUS_SOURCE_DIR;不再支持通过该变量进行离线安装。
  • 一个主机端 harness,即实际与模型通信的编码代理。Claude Code、Codex、opencode、goose 和 Hermes 都有受支持的适配器。

不需要 root。安装程序只会在您的主目录下写入文件,包括 ~/.local/bin。如果某一步失败,例如某个路径不可写,安装程序会发出警告并继续执行其余步骤;如果有任何步骤失败,最后会以非零状态退出。如果您还在选择服务器本身,请参阅在 VPS 上运行编码代理,了解基础镜像和访问配置;本节内容建立在这些配置之上。

安装固定版本

上游 README 中记录了一条命令,将脚本从 main 直接通过管道传给 bash。请先下载 v1.2.0 安装程序并阅读其内容。它会写入找到的每个代理运行环境,因此值得花十秒钟检查。

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/v1.2.0/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF 是固定版本。到 2026 年 11 月 8 日为止,main 上的脚本使用 release_ref="${HEPHAESTUS_REF:-os-v1.2.89}";发布页面将今天在 os-v1.2.89 下发布的 Agentlas OS 1.2.89 标记为 Latest。当前安装程序要求使用 os-v 标签,并通过 standalone_channel_tag_invalid 拒绝 HEPHAESTUS_REF=v1.2.0。上面的历史安装程序接受该固定版本。

上面的脚本 URL 同时将安装程序和运行时负载固定为 v1.2.0。当前的独立安装使用 ~/.agentlas/os-runtime 和 ~/.agentlas/os-bin/agentlas-os 启动器,默认不再安装全局包装器,也不再永久注册主机插件和 MCP。这些默认设置不同于下面介绍的历史安装方式。

固定版本只适用于安装过程,不限制后续行为。在 v1.2.0 中,hephaestus 命令会启动后台更新检查;如果存在较新的版本,它会在不询问的情况下安装新版本,并重新指向 ~/.agentlas/runtime/current。安装程序通过 HEPHAESTUS_AUTO_UPDATE=0 在本次运行期间禁用该功能;要保持此历史固定版本,也需要使用同一个变量。下一步会将它添加到 shell 配置文件中。当前的独立安装默认关闭自动更新。

安装成功后会输出它写入的路径。如果 ~/.local/bin 不在 PATH 中,还会包含以下几行:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

这条 PATH 警告最容易被忽略。在全新的 Ubuntu 主机上,~/.local/bin 通常不在 PATH 中,因此每个 hep-* 命令都会因 command not found 而失败,尽管安装已经成功。将它添加到 ~/.bashrc,同时关闭历史后台更新程序,然后确认:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'export HEPHAESTUS_AUTO_UPDATE=0' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global 是 hephaestus global 的原始拼写方式;status 用于显示每个运行环境指令文件是否包含受管理的路由器代码块。该路由器默认关闭,因此预计会显示 none。如果命令能够运行,说明你的 PATH 配置正确。

状态存储位置

所有内容都位于主目录下的文件中,因此备份和迁移都很简单。

  • ~/.agentlas/runtime/1.2.0/ 存放运行时本身(安装程序会从标签中去掉开头的 v),~/.agentlas/runtime/current/ 是指向活动版本的符号链接。两个固定版本可以并存。
  • ~/.local/bin/ 存放 shell 包装脚本,包括 hephaestus、hep-build、hep-network、hep-search、hep-storm、hep-cloud 和 hep-upload。
  • ~/.agentlas/networking/memory/ 存放持久化记忆,包括 playbook-registry.json、playbook-candidates.jsonl 和 memory-events.jsonl。
  • ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite 存放按所有者划分的每个代理的经验数据。
  • <project>/.agentlas/ontology-runtime.sqlite 存放每个项目的状态,因此状态会随代码仓库迁移,而不是绑定在服务器上。
  • ~/.cache/agentlas/python 在 Linux 上存放 Python 缓存。macOS 使用不同的路径,安装程序通过 uname 选择对应分支。

v1.2.0 的记忆文档明确规定,任何记忆作用域都不得存储机密、原始凭据和完整会话记录。凭据值保存在已加入 gitignore 的本地文件中,记忆记录中只保存名称和路径。备份 ~/.agentlas 和项目的 .agentlas 目录后,就可以在新的 VPS 上重建环境。

有一项数据会离开服务器:在固定的 v1.2.0 版本中,hep-build 默认发送匿名构建计数器,不包含提示内容、路径或代理内容。设置 AGENTLAS_TELEMETRY=0 或 DO_NOT_TRACK=1,或者将 "telemetry": false 和 "telemetrySetBy": "user" 都写入 ~/.agentlas/networking/config.json,即可关闭此功能。当前的独立遥测默认处于关闭状态。

它可以连接哪些模型后端

这里有一个会重新定义整个配置方式的细节:Agentlas 不会调用模型 API,调用模型 API 的是宿主 harness。

架构文档介绍了运行时适配器,这些适配器会将一个核心分别转换为各个 harness;README 则说明,适配器负责提供商身份验证,调用方需要提供自己的模型和 API 访问权限。Agentlas 提供两个供 harness 使用的接口:一个 AgentSkills 文件,以及一个通过 stdio 通信的 MCP(model context protocol)服务器。因此,“Agentlas 支持哪些模型”实际上等同于“你的 harness 支持哪些模型”,答案是 Claude Code、Codex、opencode、goose 或 Hermes 能够访问的任何模型。

在 Codex 风格的 TOML 配置中,MCP 服务器的注册方式如下:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

安装期间,同一个服务器也会自动注册到 ~/.cursor/mcp.json、~/.config/goose/config.yaml 和其他 harness 配置中。如果要在同一台主机上配置多个此类服务器,请参阅在 VPS 上运行 MCP 服务器,其中会更详细地介绍 stdio 和进程模型。

指向自托管的 Ollama 端点

由于运行框架负责连接模型,因此要让 Agentlas 使用本地模型,就需要将运行框架指向 Ollama。Ollama 在 v0.15 中新增了 launch 子命令,专门用于此目的;截至 11 August 2026,v0.32.9 仍提供该命令。它可以针对本地模型配置现有运行框架,无需设置环境变量:

ollama pull qwen3-coder:30b
ollama launch opencode

根据已安装的运行框架,将 opencode 替换为 claude、codex 或 droid。然后通过本地运行时发送请求:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

成功的请求会返回一个 JSON 决策,其中包含它所选代理或团队的名称,并带有 receipt_id。如果返回的内容没有用,请检查上下文长度。v1.2.0 的本地模型文档要求路由负载较重的会话使用上下文长度至少为 64k 的模型,并将 qwen3-coder、gemma3 和 deepseek-r1 列为示例。Ollama 针对编码工具的官方建议同样将 64k 作为最低值。路由决策会将代理清单放入提示词,因此上下文长度为 8k 或 32k 的模型会截断该清单,导致选择错误。

还有一点,宣传语不会告诉你。Ollama、Gemma 和 DeepSeek 都没有自己的插件或命令系统,因此其中不存在 /agentlas 斜杠命令。针对 Ollama 启动的运行框架仍会提供自身的命令、技能和插件;而原始 Ollama API 循环则使用 MCP 服务器或 hephaestus route 命令。这确实会减少原始 API 循环可用的功能范围。

空闲专家中心会占用多少内存

答案是零。完整答案就是这样,而且你可以自行验证,无需盲目信任。

借用的中心专家以软件包工件的形式到达,而不是以进程形式运行。一个专家由一个 agent.md 和一个包含 JSON 文件的 .agentlas/ 目录组成:routing-card.json 定义触发器和能力,memory-map.json 定义写入边界,mode-map.json 定义它是单独运行还是组队运行。Hephaestus Network 文档描述了一种会为任务启动工作进程的运行器,但其中没有任何内容会打开监听端口,也不会要求你启用服务。在任务之间,你可以自行检查:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

命令触发的工作进程退出后,前两个命令在空闲主机上不会输出任何内容,因为专家不是常驻进程。固定版本 v1.2.0 可能会在命令返回后留下短暂运行且已脱离的更新和构建遥测工作进程。HEPHAESTUS_AUTO_UPDATE=0 会禁用其更新器;遥测需要使用上文所述的独立退出选项。当前版本默认关闭独立更新检查和遥测。第三个命令只会显示一个已停放中心实际产生的成本,即磁盘空间。该成本会随着你保留的专家数量以及运行时附带的嵌入模型而增加。

因此,内存问题完全取决于突发运行,而突发运行取决于你的工具进程和模型后端。如果工具进程调用托管 API,常驻成本就是工具进程本身,其内存使用量取决于工具进程和工作负载。如果你自行托管模型权重,权重就是主要开销:

图表Model weights resident on the VPS, published Ollama download sizes, November 2026
此图表背后的数据
[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.4
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.2
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

这些是 Ollama 模型库公布的下载大小,不是基准测试运行结果;对于 64k 上下文,KV 缓存还会叠加在上述所有非零数值之上。Agentlas 文档首先列出的模型 qwen3-coder:30b 在加载上下文前就需要 19 GB 权重;即使是 27B Gemma 变体,也需要 17 GB。相比这些数值,Agentlas 层本身不会明显增加内存预算。

与运行单个 harness 的比较

针对托管 API 运行一个 harness 时,您的 VPS 只需承载一个进程。加入 Agentlas 后,它承载的仍是同一个 harness,同时还会承载文件和任务范围内的运行时进程。编排器不是额外的常驻程序,而是根据磁盘上的软件包组装出的更大提示词,使用后即丢弃。

发生变化的是上下文,而不是内存。编排器加载多个专业卡片及其路由元数据后,每个任务消耗的 token 会多于基础 harness;对于托管 API,这表现为成本增加,而不是 RAM 增加。使用本地权重时,增加的是耗时,因为更长的提示词会让 CPU 预填充时间更长,或让 GPU 更繁忙。

因此,这类服务器的容量建议应依据模型选择,而不是 agent 框架。为编码 agent VPS 估算 RAM 和 CPU对此有详细说明,结论在这里同样适用:根据您计划运行的后端选择套餐,然后为 harness 额外预留几 GB 的余量。如果您想改为采用常驻 supervisor 设计进行比较,Omnigent 多 agent harness 会让协调器常驻内存。这是相反的取舍,并会直接反映在空闲内存占用上。

故障模式及其输出信息

安装完成后紧接着出现 hep-build: command not found。 固定版本的安装程序写入了 ~/.local/bin,但部分新建 shell 的 PATH 中没有该路径。安装程序在输出末尾附近提示了这一点,但警告已经滚过。将上文所示的 export 添加到 ~/.bashrc。

重建服务器后行为发生变化。 您未设置 HEPHAESTUS_REF,因此安装程序使用了其脚本当天指定的默认标签。固定该值,并将固定版本记录在其他版本号旁边。

未重建服务器但行为发生变化。 在固定版本 v1.2.0 中,后台更新程序可能安装更新版本,并将 ~/.agentlas/runtime/current 切换到该版本。检查 current 当前指向的内容,并在运行 harness 的环境中设置 HEPHAESTUS_AUTO_UPDATE=0,不要只在交互式 shell 中设置。当前版本默认关闭独立运行的自动更新。

本地模型的路由选择了错误的 specialist。 检查模型的上下文窗口是否太小,无法容纳 agent 清单。改用上下文窗口为 64k 或更大的模型,并将 Ollama 的上下文长度设置为相同值。Ollama 在 VRAM 少于 24 GiB 时默认为 4k,在 24 GiB 至少于 48 GiB 时默认为 32k,在 48 GiB 或更大时默认为 256k,因此较小的配置需要显式增加上下文长度。

无法识别 ollama launch。 该子命令在 Ollama v0.15 中加入。发行版软件仓库中的旧软件包早于该版本,因此请安装当前版本的 Ollama。

安装程序写入了您未预期的 harness。 固定版本的脚本会检测并配置找到的每个 harness,将内容写入 ~/.claude/、~/.codex/、~/.gemini/、~/.cursor/ 等目录;对于已存在的配置文件(例如 ~/.codex/config.toml),脚本也会修改,并在原文件旁保留备份。在共享构建服务器上运行脚本前,请先阅读脚本,并确认需要关注其中哪些目录。

是否现在就应该运行它

这个项目还很新,并且会自动发布,有时一天会发布多个版本,因此不适合承载生产工作负载。其架构确实很有意思,许可证是 Apache-2.0,所有状态都保存在可以备份的文件中。但卸载并不像这些信息所暗示的那样简单:v1.2.0 的 README 没有说明卸载方法,固定版本的安装程序会在主目录中的多个位置写入文件,并修改现有的 harness 配置;而 hephaestus global remove 只会删除可选的路由器配置块。这些事实意味着,在一次性测试机上试用的成本很低,但将其作为依赖的成本很高。

目前更合理的做法是:使用带标签的安装程序固定到 v1.2.0,设置 HEPHAESTUS_AUTO_UPDATE=0 以保持这一历史版本固定,在可以重建的主机上运行它,将 ~/.agentlas 纳入备份,并在更新版本固定之前重新阅读变更日志。若要全面了解这一领域中的其他项目及各选项的成熟度,自托管 AI agent 汇总是更好的起点;在 VPS 上自托管 Hermes agent则介绍了 Agentlas 所适配的其中一种 harness。

FAQ

Agentlas OS 会在我的 VPS 上作为服务器运行吗?

固定为 v1.2.0 的命令行安装不会启用守护进程,也不会打开监听端口。安装程序会将运行时写入 ~/.agentlas/runtime/,并将命令包装器写入 ~/.local/bin。Hephaestus Network 会在任务启动时运行,而不是作为后台服务运行。由命令触发的工作进程退出后,在空闲主机上执行 pgrep -af hephaestus 不会输出任何内容。固定版本可以启动短时运行的更新和构建遥测工作进程:HEPHAESTUS_AUTO_UPDATE=0 会禁用更新器,AGENTLAS_TELEMETRY=0 或 DO_NOT_TRACK=1 会禁用遥测。当前的独立更新检查和遥测功能默认处于关闭状态。这里所说的自行托管,是指代码和状态存储在您的计算机上,而不是指有服务正在监听端口。

空闲专家组成的 hub 占用多少 RAM?

不占用,因为空闲专家不是进程。一个专家由 agent.md 文件和 .agentlas/ 目录组成,目录中保存 routing-card.json、memory-map.json 以及类似元数据,因此停放的 hub 只占用磁盘空间。使用 du -sh ~/.agentlas 测量其大小。任务和短时运行的后台工作进程会占用内存;停放的专家不会。

我可以使用哪些模型?可以将它指向自己的 Ollama 吗?

Agentlas 不会自行调用模型 API。凭据和连接由主机上的 harness 管理,因此支持的模型取决于您的 harness 支持哪些模型。对于本地权重,运行 ollama launch opencode,将 claude、codex 或 droid 替换为相应值。该命令会将 harness 配置为连接到您的 Ollama 服务器,无需设置环境变量。请使用上下文至少为 64k 的模型,例如 qwen3-coder 或 gemma3,因为路由提示会包含代理清单,在较小的上下文窗口中会严重截断。

应安装哪个版本?为什么这里必须固定版本?

请安装 v1.2.0。这是 2026 年 8 月 12 日当前带标签的版本。按照上文所示,从 v1.2.0 标签获取安装程序,并设置 HEPHAESTUS_REF=v1.2.0。截至 2026 年 11 月 8 日,脚本在 main 上的默认值为 release_ref="${HEPHAESTUS_REF:-os-v1.2.89}",Agentlas OS 1.2.89 是最新版本,今天已在 os-v1.2.89 下发布。该当前安装程序只接受 os-v 版本标签,并会拒绝旧的 v1.2.0 固定值。这里固定版本比通常更重要,因为该项目在 1.1 系列中发布了 100 多个版本,有些日期甚至发布了多个版本。因此,数周后重新执行未固定版本的构建时,得到的系统可能不是您测试过的系统。此外,请为历史 v1.2.0 运行时设置 HEPHAESTUS_AUTO_UPDATE=0,否则其更新器会在后台安装更新版本,版本固定会在无提示的情况下失效。当前的独立自动更新默认处于关闭状态。

这篇文章对您有帮助吗?