指南

作者： Matt Connor 2026-08-03

Omnigent 多代理 CLI 编排与 VPS 沙箱配置

Q: 如何安装指定版本的 Omnigent，而不是最新版本？

通过安装脚本传入 --version 和 sh -s --，如 sh -s -- --version 0.7.0 所示。如果不使用 -s --，该参数会由 sh 本身处理，脚本将安装最新版本。如果已经安装 uv，uv tool install --force --python 3.12 "omnigent==0.7.0" 可以完成相同的工作。Git 标签为 v0.7.0，PyPI 版本字符串为 0.7.0。

了解 Omnigent 如何统一驱动已安装的 Claude Code、Codex 等代理 CLI，固定 0.7.0 版本，并在 VPS 上为每个子代理配置隔离沙箱。

Omnigent 是什么

Omnigent 是一个开源的元级编排框架：它提供统一的编排层，用于驱动您已经安装的代理命令行工具（CLI）。它不会替代 Claude Code、Codex、Cursor、OpenCode、Hermes 或 Pi，而是启动这些工具、为每个工具分配任务，并在单个会话中使用同一套策略监督执行结果。Databricks 于 2026 年 6 月以 Apache 2.0 许可证发布了该代码仓库，其首页目前仍显示 Status: alpha。

它的实际用途很明确。您只需在 YAML 中描述一次代理，并指定运行该代理的框架。修改这一行后，同一个代理即可运行在其他厂商的 CLI 上。您的其他配置无需更改，因为 Omnigent 管理的是代理之上的循环，而不是代理内部的循环。

什么是元级 harness？它与 framework 有何不同？

harness 是将模型封装在循环中的程序。它读取您的提示，调用工具，编辑文件并返回结果。Claude Code 是 harness。Codex 是 harness。您安装并登录后，它就能自行工作。

framework 是供您编写代码调用的库。您导入它，在 Python 中定义步骤，然后由您的程序充当 agent。更换供应商时，您需要编辑代码，因为供应商的客户端已经接入您的程序。

meta-harness 位于两者之上。它是一个以子进程方式运行 harness 的监督程序。Omnigent 启动供应商 CLI，将任务交给它，并读取返回结果。您可以继续使用已经安装的 CLI，也可以继续使用现有的订阅或 API（应用程序编程接口）密钥为其付费。这就是全部区别，也决定了该工具适合谁：已经在使用多个 agent CLI、但不想再一次只通过一个终端操作它们的人。

一个编排层解决什么问题？

切换供应商只需修改一行。 agent 定义将 harness 和 model 作为数据保存，因此将一个角色从一家供应商迁移到另一家供应商，只需编辑 YAML 文件，无需重写配置。
审查可以跨供应商进行。 一个模型生成的差异由另一家公司提供的模型审阅。来自同一模型系列的两个模型往往有相同的盲点，因此，来自同一供应商的第二意见价值较低。
策略集中管理。 agent 文件中声明支出上限和审批提示，这些设置会应用于其下的所有子 agent。
会话不依赖任何单个工具。 一份转录记录涵盖多个 CLI 完成的工作，因此无需拼接 4 个滚动窗口，也能回顾发生了什么。

代价是这个编排层本身。Omnigent 中的每个缺陷，现在都位于您与原本可以独立运行的 agent 之间。在 alpha 阶段，这是真实存在的成本，而不是理论上的成本。

多代理 harness 与单代理工具的适用场景

如果您还没有在服务器上运行过单个代理，应先从这一步开始。我们的在 VPS 上运行 coding agent 指南完整介绍了单代理场景，这也是 Omnigent 假定您已经具备的环境。更广泛的自托管 AI agent 领域用于选择具体的代理；如果这里的术语对您来说还不熟悉，建议先阅读了解 agent 的实际工作方式。

Omnigent 与连接器层关注的是不同维度。让 agent 访问您自己的数据源关注 agent 可以访问哪些资源。Omnigent 关注运行哪个 agent、按什么顺序运行，以及受到哪些限制。您可以同时需要这两者，但它们的功能范围并不重叠。

安装前的准备条件

Python 3.12 或更高版本。已发布的软件包声明 requires-python >= 3.12。
tmux，因为终端处理程序会在其中运行。
至少安装一个供应商 CLI，并已完成登录。
只有从 git checkout 构建时才需要 Node.js 22。PyPI 上的 wheel 已包含构建后的 Web 资源，因此常规安装完全不需要 Node。

安装固定版本，而不是 main

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --version 0.7.0

sh -s -- 部分不是装饰。没有它，sh 会将 --version 解析为自己的选项，安装程序根本收不到该标志，因此会安装当天最新的版本。对于每隔几周就发布破坏性变更的仓库，这决定了服务器是可复现的，还是会出现意外。

安装程序使用 uv（Astral 的 Python 包管理器）。如果系统中没有 uv，安装程序会先提供安装选项。如果已经安装 uv，请跳过该脚本：

uv tool install --force --python 3.12 "omnigent==0.7.0"

附加组件遵循相同的模式，标志也会重复出现：在脚本中使用 --extra e2b --extra kubernetes，或通过 uv 使用 "omnigent[e2b,kubernetes]"。请注意，git 标签是 v0.7.0，而 PyPI 上的软件包版本是 0.7.0。

uv 会将二进制文件放入 uv tool dir --bin 报告的目录中，通常是 ~/.local/bin，安装程序会提供选项，将该目录追加到 shell 配置文件。如果全新安装后立即执行命令却提示找不到命令，原因就在这里。检查最终安装的内容：

omni upgrade --check

该命令会将已安装的版本与最新发布版本进行比较，并告知是否存在可用升级，但不会执行升级。omni 和 omnigent 是同一个程序的两个名称。

指定模型提供商

omni setup

向导会查找环境中已有的凭据，并提示您补充缺失的凭据。它支持 API 密钥、供应商订阅，以及 OpenRouter 或 Ollama 等网关和 Databricks 工作区。如果您已在同一台计算机上使用 Ollama 运行本地模型服务器，可将网关指向该服务器，网络流量就不会离开本机。

一个最小的多代理运行

示例代理位于代码仓库中，因此应检出与所安装版本相同的标签，而不是 main。

git clone --depth 1 --branch v0.7.0 https://github.com/omnigent-ai/omnigent.git
cd omnigent
omnigent run examples/polly/

Polly 是随代码仓库发布的多代理编码编排器。其配置声明了名为 claude_code、codex、opencode、cursor、hermes 和 pi 的子代理，并包含一条使整个流程值得运行的规则：审查必须始终由不同于实现者的供应商完成。Polly 本身不编写代码。它会规划任务，将目标拆分为工作项，分别委派给各个代理，并将每个差异交给其他供应商的审查代理。

在委派任何任务之前，Polly 会执行预检，确认机器上实际存在的子代理 CLI。如果只安装了一个供应商的 CLI，就没有其他代理可以接收差异，因此在评估输出前至少安装两个供应商的 CLI。另一个随附的示例 Debby 是一个双头辩论代理，分别使用一个 Claude 和一个 GPT：

omni debby

这是确认两个提供商已完成配置的简便方法，因为它必须同时获得两者的响应才能输出任何内容。

子代理以工具形式声明

代理文件采用 YAML 格式。executor 定义 harness、模型和身份验证。tools 包含 MCP（模型上下文协议）服务器、Python 函数和子代理。子代理是一种具有 type: agent 且拥有独立执行器的工具，也是上述所有功能的基础机制。

name: orchestrator
prompt: |
  You coordinate coding and review tasks.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  coder:
    type: agent
    prompt: Write and test code.
    executor:
      harness: claude-sdk
      model: databricks-claude-opus-4-7
  reviewer:
    type: agent
    prompt: Review proposed changes.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6

omnigent run path/to/my_agent.yaml

这些模型 ID 来自项目自身的 docs/AGENT_YAML_SPEC.md 示例，使用的是 Databricks 托管的名称。请将 harness 和 model 替换为您在本机配置的 omni setup。规范中还包括 antigravity、copilot、kimi、qwen 和 acp:<slug> 等其他 harness 值，用于支持通用协议的组件。该规范还支持在子代理上设置 pass_history: true，将父级会话传递给子代理。每次委派都会消耗额外 token，因此对于只需要处理当前任务的子代理，请保持此选项关闭。

为什么长时间运行的编排任务适合放在 VPS 上

多代理运行不是一个两分钟就能完成的命令。你需要规划任务、分派工作、等待并行的 Git worktree 操作、审核结果并进行修改。合上笔记本电脑后，所有任务都会停止。VPS（虚拟专用服务器）会持续运行并保持网络连接，因此即使你暂时不查看，也能让会话继续运行。

omnigent server --background
omnigent server status

服务器在 6767 端口提供 Web 用户界面。omnigent server status 可报告是否有会话正在运行，omnigent stop 可将其停止。在 v0.7.0 之前的版本中，这个命令是 omni server start，但该命令后来已被移除，因此旧教程和截图可能与终端中的实际结果不一致。

不要将 6767 发布到公网地址。有两种安全方式。可以在防火墙中关闭该端口，再使用 SSH 通过 ssh -N -L 6767:localhost:6767 you@your-server 转发，然后在本机打开 Web 界面：http://localhost:6767。也可以在前端终止 TLS（传输层安全），并启用身份验证：

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

其中防火墙部分属于常规配置，VPS 的 ufw 防火墙基础对此已有说明。如果服务器已经通过在多个 Docker Compose 应用前使用 Traefik 将容器置于代理之后，那么 Omnigent 只需按照相同模式添加为另一个服务。

对于容器部署，代码库的 deploy/ 目录包含一套 Compose 配置：./bootstrap.sh 将密钥写入 .env，然后 docker compose up -d 在 6767 端口启动 Omnigent 和 Postgres。DATABASE_URL 用于选择 Postgres 或 SQLite；在容器中，OMNIGENT_AUTH_ENABLED 默认为 1，对于任何可从外部访问的服务，这是正确的默认设置。

关于规格，部署说明将服务器工作集估算为约 512 MB 到 1 GB，Fly.io 配置固定使用 1 GB。这个数值只针对监督进程。每个子代理都是独立进程，会持有自己的代码检出目录和模型客户端，因此应根据代理数量为服务器配置资源。服务器启动后，先运行 omnigent login https://your-host，再运行 omnigent host https://your-host，即可将笔记本电脑注册到该服务器；omnigent attach <session_id> 可从其他设备恢复正在运行的会话。

离开前为每个子代理配置沙箱

Omnigent 发布了一个操作系统级沙箱，名为 Omnibox。在 Linux 上，它使用 bubblewrap 命名空间和 seccomp，因此边界由内核强制执行，而不是由代理提示词决定。受到提示注入的代理无法通过说服绕过内核规则。请先安装依赖项：

sudo apt install bubblewrap

配置位于代理文件中的 os_env 下：

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths: [.]
    write_files: []
    read_paths: []
    allow_network: true
    cwd_allow_hidden: [.venv]
    env_passthrough: []
    egress_rules: []
    credential_proxy: []

在将工作目录列入 write_paths 之前，该目录为只读，因此出错的代理无法写入工作区以外的位置。除非在 cwd_allow_hidden 中明确指定，否则点文件会保持隐藏。这意味着宽泛的读取授权不会悄然暴露 .ssh 或 .aws。设置 egress_rules 后，所有 HTTP 和 HTTPS 流量都会经过默认拒绝代理，每条规则均写为 "METHODS host/path-glob"。credential_proxy 更进一步：代理始终只持有占位符，代理会在请求离开时替换为真实密钥，因此即使请求记录泄露，也不会泄露可用的密钥。在多运行框架配置中，每个子代理都会在 agents/ 下自己的配置文件中携带独立的沙箱配置块。因此，可以禁止审查代理访问网络，同时保留实现代理的网络访问权限。

文档明确说明了限制，这一点很重要。操作系统沙箱适用于 sys_os_* 工具调用和终端，但不适用于 MCP 服务器，也不适用于 Omnigent supervisor 进程。你启动的 MCP 服务器会在沙箱外运行，并使用你的权限。正因如此，更强的方案仍然是为每个代理使用一台一次性机器，详见在一次性 VM 中运行编码代理。另一项工作是管理凭据；当 6 个子代理共享一台主机时，让密钥脱离代理可访问范围会变得更加困难，而不是更容易。

支出限制属于策略，并在同一文件中声明：

policies:
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00
      ask_thresholds_usd: [1.00, 3.00]

如果一次运行先使用一家供应商进行规划，再使用第二家供应商进行实现，最后使用第三家供应商进行审查，就会同时在 3 个地方产生支出。因此，应在首次无人值守运行前设置上限，而不是等到收到第一张账单后再设置。内置选项还包括 max_tool_calls_per_session 和 ask_on_os_tools，它们会在执行文件操作和 shell 操作前请求批准。我们关于控制 VPS 上 AI 代理成本的说明可直接应用于此，而且这里更需要遵守，因为并行子代理会成倍提高消耗速度。

此仓库的更新速度有多快？

ChartDays between tagged Omnigent releases, v0.2.0 to v0.7.0

version

released

interval

v0.2.0

2026-06-19

v0.3.0

2026-06-27

v0.4.0

2026-07-03

v0.5.0

2026-07-10

v0.5.1

2026-07-10

v0.6.0

2026-07-21

v0.7.0

2026-07-27

The data behind this chart

[
  {
    "version": "v0.2.0",
    "released": "2026-06-19",
    "interval": 3
  },
  {
    "version": "v0.3.0",
    "released": "2026-06-27",
    "interval": 8
  },
  {
    "version": "v0.4.0",
    "released": "2026-07-03",
    "interval": 6
  },
  {
    "version": "v0.5.0",
    "released": "2026-07-10",
    "interval": 7
  },
  {
    "version": "v0.5.1",
    "released": "2026-07-10",
    "interval": 0
  },
  {
    "version": "v0.6.0",
    "released": "2026-07-21",
    "interval": 11
  },
  {
    "version": "v0.7.0",
    "released": "2026-07-27",
    "interval": 6
  }
]

以上是项目自身发布页面中的正式发布日期，数据读取于 3 August 2026。7 个带标签的版本发布于 2026-06-19 至 2026-07-27 之间，其中任意两个版本之间的最长间隔为 11 天。v0.5.1 与前一个版本在同一天发布。首个版本 0.1.1 于 16 June 2026 发布。由于没有更早的标签可用于计算间隔，因此图表未包含该版本。

其中两个版本破坏了指南中已有记录的命令。v0.7.0 移除了 omni server start，改用 omni server --background。v0.6.0 将 omnigent[memory] extra 重命名为 omnigent[hindsight]，因此从 June 的文章中复制的安装命令在 July 构建中会失败。这说明安装命令中应固定 --version，并在 git clone 中指定标签；这不是格式偏好，而是兼容性要求。

目前我不会把它用于以下场景

截至 2026 年 8 月，该仓库约有 8.1k 个 stars、1.2k 个 forks 和约 350 个 open issues，首次公开发布距今仅 7 周。stars 只能反映关注度，不能代表成熟度。项目自称 alpha，上面的发布历史也表明它确实处于 alpha 阶段。

我不会在保存生产凭据的主机上运行它，因为沙箱尚未覆盖 MCP servers 或 supervisor。
没有 cost_budget 策略时，我不会让运行过程无人值守，因为三个供应商可能并行计费，除此之外没有任何机制会阻止它们。
未设置 OMNIGENT_AUTH_ENABLED 且未在前端配置 TLS 时，我不会将服务器暴露在公网 IP 地址上。
目前我不会认为 agent YAML 在小版本之间保持稳定，因此应固定版本，并在升级前阅读发布说明。

还有一点需要在它给你带来意外之前了解：v0.6.0 增加了匿名使用遥测，项目在专门的遥测页面上对此进行了说明。如果这台机器处理客户工作，请阅读该页面，再审慎决定是否使用。

Omnigent 目前真正擅长的，是它最初设计要解决的问题。你有 3 或 4 个 agent CLI，已经在为它们付费，并希望让其中一个负责编写、另一个负责审查。现在它可以在单台 Linux 机器上完成这项工作，并提供真正的沙箱隔离。除此之外的功能都应视为有潜力但尚未完成。

FAQ

Omnigent 是代理，还是运行代理的工具？

它用于运行代理。Omnigent 是一个元级运行框架：它启动您已经安装的供应商 CLI，例如 Claude Code、Codex 或 OpenCode，为每个 CLI 分配任务，并在一个会话中监督结果。它不提供自己的模型。这也是它与框架的区别：使用框架时，您会针对一个库编写 Python 代码，而您自己的程序会成为代理。

在 Omnigent 发挥作用前，我是否需要安装 Claude Code 和 Codex？

您至少需要安装并登录一个供应商 CLI，因为 Omnigent 驱动这些程序，而不是替代它们。对于随附的 Polly 示例，您需要使用来自不同供应商的至少两个 CLI。Polly 的规则是，审查必须始终由与实现者不同的供应商完成。因此，如果只有一个 CLI 可用，就没有第二个供应商可以接收差异内容进行审查。

如何安装指定版本的 Omnigent，而不是最新版本？

通过安装脚本传入 --version 和 sh -s --，如 sh -s -- --version 0.7.0 所示。如果不使用 -s --，该参数会由 sh 本身处理，脚本将安装最新版本。如果已经安装 uv，uv tool install --force --python 3.12 "omnigent==0.7.0" 可以完成相同的工作。Git 标签为 v0.7.0，PyPI 版本字符串为 0.7.0。

Omnibox 沙箱是否足以支持无人值守运行代理？

对于其覆盖的范围，它提供了较强的隔离，并明确说明了未覆盖的范围。在 Linux 上，它使用 bubblewrap 和 seccomp，因此由内核强制执行文件和网络限制，代理无法绕过这些限制。文档说明，该沙箱适用于 sys_os_* 工具调用和终端，但不覆盖 MCP 服务器或 Omnigent supervisor 进程。因此，MCP 服务器会以您的常规权限运行。对于无人值守任务，为每个代理使用一台一次性虚拟机，仍能提供更强的隔离。

VPS 上的 Omnigent 服务器需要多少内存？

项目的部署说明指出，服务器的工作集约为 512 MB 至 1 GB，Fly.io 配置固定使用 1 GB。这些资源仅用于 supervisor 和监听 6767 端口的 Web 界面。每个子代理都是独立进程，拥有自己的工作副本和模型客户端；Polly 风格的运行还会使用并行 Git worktree。因此，应根据计划同时运行的代理数量来规划内存和磁盘空间，而不是只按服务器本身规划。

#omnigent#ai-agents#orchestration#open-source #cli