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

Agentlas OS 的本质

Agentlas OS 是一个开源代理运行时。它将专业代理以软件包的形式存储在磁盘上，并为每个任务临时组装一个编排器。您可以通过将其安装到 Linux VPS 的个人用户账户下来实现自托管。它不是一项服务。该仓库中没有守护进程、没有监听端口、没有 Web 界面，也没有容器镜像。

最后这一句决定了本页面的所有后续内容。大多数多代理系统运行一个持续驻留并持有代理的监控进程。Agentlas 则反其道而行之：专业代理是静态文件，而编排器仅在任务运行时存在。其实际结果是，闲置的中心节点仅占用磁盘空间，而不占用内存。

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

坦诚地讲，该项目处于什么阶段

该仓库创建于 2026 年 6 月 4 日。截至 2026 年 8 月 12 日，项目仅运行了约十周，拥有约 1,150 个星标和 112 个分支。对于用于实际生产环境的项目而言，这个时间太短了。

发布频率比项目时长更重要。版本 v1.1.103 发布于 2026 年 8 月 8 日，而 v1.2.0 发布于 2026 年 8 月 12 日。在 1.1 系列中，通过自动化工具发布的带标签版本已超过一百个，有时一天内会发布多次。以这种速度迭代的项目，其行为可能在周二到周四之间发生变化。

因此，请锁定版本。安装程序会读取一个环境变量来实现此目的，下文中的所有指南均使用该变量。如果安装时不锁定版本，对于一个每天发布多次的项目，你最终得到的版本取决于 main 当时所处的具体状态。

VPS 所需环境

由于后台无常驻进程，系统资源占用极低。

• 一台 Linux VPS。推荐使用 Ubuntu 24.04 作为基础环境。安装程序会通过 uname -s 检测操作系统，并为 Linux 选择非 macOS 分支，因此支持无头服务器（headless box）。
• 服务器上需安装 curl、tar 和 git，以及可用的 Python 解释器。
• 允许访问 raw.githubusercontent.com 和 github.com 的出站 HTTPS 流量。安装程序需下载发布包并校验 SHA-256，因此无法连接外网的服务器无法完成安装。
• 一个宿主工具（host harness），即负责与模型交互的编码代理。支持 Claude Code、Codex、opencode、goose 和 Hermes 等适配器。

无需 root 权限。安装程序仅向用户主目录和 ~/.local/bin 写入数据；若路径不可写，程序会发出警告而非直接中断。如果您仍在选择服务器，在 VPS 上运行编码代理 一文涵盖了此环境所需的基础镜像和访问配置。

安装指定版本

上游 README 文档提供了一行命令，直接将 main 的脚本通过管道传输给 bash 执行。请先下载并阅读该脚本。它会写入你的 shell 配置文件以及它发现的每一个 agent harness，因此花十秒钟检查非常值得。

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

HEPHAESTUS_REF 是版本锁定变量。脚本内部的对应行是 version="${HEPHAESTUS_REF:-v1.2.0}"，如果不设置该变量，今天默认安装 v1.2.0，下周可能就会变成其他版本。请显式设置该变量，以确保你在 10 月重新构建时，安装的依然是你 8 月测试过的版本。

一个客观的限制是：上述脚本 URL 跟踪的是 main，而 HEPHAESTUS_REF 锁定的是脚本下载的运行时负载。这两者是不同的。若要同时锁定两者，请从标签（tag）获取脚本，而不是从 main 获取；只需将 URL 中的 main 替换为 v1.2.0 即可。

运行成功后，终端会打印出写入的路径，包括以下两行：

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)

第二行往往被用户忽略。在全新的 Ubuntu 系统上，~/.local/bin 通常不在 PATH 中，这会导致所有 hep-* 命令因 command not found 而失败，即使安装过程本身是成功的。请修复并确认：

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

hep-global status 会报告全局路由器安装的内容以及检测到的 harness。只要该命令能运行，说明你的 PATH 配置就是正确的。

状态存储位置

所有内容均以文件形式存储在您的主目录下，这使得备份和迁移变得简单。

• ~/.agentlas/runtime/v1.2.0/ 存放运行时本身，~/.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 选择对应的分支。

内存文档明确指出，密钥、原始凭据和完整转录内容不得进入任何内存作用域。凭据值应保留在 gitignored 的本地文件中，内存记录仅包含名称和路径。备份 ~/.agentlas 和您的项目 .agentlas 目录，即可在新的 VPS 上重建环境。

它支持指向哪些模型后端

以下细节重新定义了整个架构：Agentlas 本身不调用模型 API，而是由宿主工具（harness）负责调用。

架构文档描述了将核心逻辑转换为各工具适配器的运行时适配器，并指出宿主运行时拥有模型凭据。Agentlas 提供了两个供工具调用的接口：一个 AgentSkills 文件和一个通过 stdio 通信的 MCP（模型上下文协议）服务器。因此，“Agentlas 支持哪些模型”这一问题的本质是“您的工具支持哪些模型”，答案是任何 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 以及其他工具配置中。如果您要在同一台机器上配置多个此类服务，在 VPS 上运行 MCP 服务器 一文更深入地介绍了 stdio 和进程模型。

指向自托管的 Ollama 端点

由于 harness 负责管理模型连接，将 Agentlas 指向本地模型意味着需要将 harness 指向 Ollama。Ollama 在 v0.15 版本中专门为此添加了 launch 子命令，截至 2026 年 8 月 11 日的 v0.32.9 版本中该功能依然可用。它无需设置任何环境变量即可将现有的 harness 配置为使用本地模型：

ollama pull qwen3-coder:30b
ollama launch opencode

根据你安装的 harness，将 opencode 替换为 claude、codex 或 droid。然后通过本地运行时路由请求：

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

路由成功后会返回一个 JSON 决策结果，其中包含所选代理或团队的名称以及 receipt_id。如果返回结果无效，通常原因是上下文长度不足。Agentlas 文档要求在路由密集型会话中使用至少 64k 上下文的模型，并列举了 qwen3-coder、gemma3 和 deepseek-r1 作为示例。Ollama 针对编码工具的官方指南也设定了同样的 64k 下限。路由决策会在提示词中携带代理清单，因此 8k 或 32k 上下文的模型会截断清单，导致选择错误。

标语中不会提及的一个注意事项是：Ollama、Gemma 和 DeepSeek 本身没有插件或命令系统，因此 /agentlas 斜杠命令在这些环境中不存在。在本地模型设置中，你需要通过 MCP 服务器和 hephaestus route 命令来驱动系统。这确实减少了功能面，但这是将模型权重保留在本地服务器上所必须付出的代价。

闲置专家中心占用的内存成本

零。这就是全部答案，你可以通过验证来证明这一点，而不必盲目相信。

借用的中心专家以软件包工件的形式存在，而非进程。一个专家由一个 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

前两个命令在空闲机器上不会输出任何内容，因为没有任何驻留进程。第三个命令显示了停驻的中心对你产生的唯一成本，即磁盘占用；该成本会随着你保留的专家数量以及运行时附带的嵌入模型而增加。

因此，内存问题完全取决于突发负载，而突发负载由你的工具链和模型后端决定。如果工具链与托管 API 通信，驻留成本仅为一个几百 MB 的进程。如果你自行托管权重，则权重就是主要开销：

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "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 层本身的内存占用几乎可以忽略不计。

与运行单个测试工具的对比

针对托管 API 运行单个测试工具时，VPS 仅承载一个进程。添加 Agentlas 后，它同样只承载这一个进程，外加一些磁盘文件。编排器并非一个长期运行的额外程序，它只是由磁盘上的软件包组装而成的一个大型提示词（prompt），任务完成后即被丢弃。

发生变化的成本是上下文，而非内存。编排器在调用多个专用卡及其路由元数据时，每个任务消耗的 Token 比单纯的测试工具更多。对于托管 API 而言，这意味着资金成本而非内存占用。对于本地权重模型，这意味着时间成本，因为更长的提示词会导致 CPU 预填充（prefill）时间变长，或 GPU 负载更高。

这就是为什么此类设备的规格建议取决于模型选择，而非代理框架。为编码代理 VPS 配置 RAM 和 CPU 一文对此进行了详细分析，结论同样适用于此：根据你计划运行的后端选择方案，然后为测试工具预留几 GB 的冗余内存。如果你想对比“常驻监督者”架构，Omnigent 多代理测试工具 会将协调器常驻内存，这属于完全相反的权衡，会直接反映在空闲内存占用上。

故障模式及常见错误信息

hep-build: command not found 在全新安装后出现。 安装程序写入了 ~/.local/bin，但在默认的 Ubuntu 镜像中，该路径不在 PATH 中。安装程序的最后一行提示了这一点，但该行已滚动消失。请添加上述 export 语句。

重建服务器后行为发生变化。 您未设置 HEPHAESTUS_REF，因此安装程序默认使用了当天的最新标签。请锁定版本号，并将其与您的其他版本号记录在一起。

路由在本地模型上选择了错误的专家。 模型的上下文窗口对于代理清单来说太小。请更换为 64k 或更大上下文的模型，并相应设置 Ollama 的上下文长度，因为默认值低于编码工具的要求。

ollama launch 无法识别。 该子命令是在 Ollama v0.15 中引入的。发行版仓库中的旧软件包版本较早，请安装当前的 Ollama 版本。

安装程序写入了您未预期的挂载点。 该脚本会自动检测并配置它发现的所有挂载点，并写入 ~/.claude/、~/.codex/、~/.gemini/、~/.cursor/ 等位置。在共享构建服务器上，请在运行脚本前阅读其内容，并确认您需要关注哪些目录。

现在是否应该运行此项目

一个仅发布十周、每天多次自动更新的项目，不适合承载生产环境的工作负载。其架构确实很有趣，采用 Apache-2.0 许可证，且基于文件的设计意味着卸载只需删除两个目录。这些特性使其试用成本很低，但作为生产依赖的成本很高。

目前合理的做法是：锁定 v1.2.0 版本，将其运行在可重建的服务器上，确保备份中包含 ~/.agentlas，并在更改版本锁定前重新阅读更新日志。若需更全面地了解该领域其他方案及其成熟度，自托管 AI Agent 综述 是更好的起点，而 在 VPS 上自托管 Hermes Agent 则涵盖了 Agentlas 所适配的其中一种运行环境。

FAQ

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

不会。该存储库中没有守护进程、监听端口或容器镜像。安装程序会将运行时写入 ~/.agentlas/runtime/，并将命令包装器写入 ~/.local/bin。Hephaestus Network 是一个进程内调度程序，而非后台服务。你可以在空闲的机器上确认这一点：pgrep -af hephaestus 不会输出任何内容，且没有需要启用的 systemd 单元。此处的“自托管”是指代码和状态位于你的机器上，而不是指有服务在监听。

一组空闲的专家（specialists）会占用多少内存？

不占用内存，因为空闲的专家不是进程。一个专家由一个 agent.md 文件加上一个存放 routing-card.json、memory-map.json 及类似元数据的 .agentlas/ 目录组成，因此驻留的中心仅占用磁盘空间。请使用 du -sh ~/.agentlas 进行测量。内存仅在任务运行时消耗，且消耗内存的是你的工具进程（harness process）和模型后端，而非 Agentlas 层。

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

Agentlas 本身不调用模型 API。主机工具负责凭据和连接，因此支持的模型取决于你的工具所支持的模型。对于本地权重，请运行 ollama launch opencode（替换 claude、codex 或 droid），这会将工具配置为指向你的 Ollama 服务器，且无需设置环境变量。请使用上下文窗口至少为 64k 的模型，例如 qwen3-coder 或 gemma3，因为路由提示（routing prompts）包含代理清单，在较小的窗口中会严重截断。

我应该安装哪个版本？为什么在这里锁定版本很重要？

请通过在运行安装程序前设置 HEPHAESTUS_REF=v1.2.0 来安装 v1.2.0 版本，这是 2026 年 8 月 12 日时的标记版本。脚本的默认设置是 version="${HEPHAESTUS_REF:-v1.2.0}"，它会追踪维护者后续标记的任何版本。锁定版本比平时更重要，因为该项目在 1.1 系列中发布了超过一百个版本，有时一天内会发布多个，因此几周后进行未锁定的重新构建将无法得到你之前测试过的系统。