指南

作者： Matt Connor 2026-08-03 · 更新于 2026-08-13

Omnigent怎么统一编排多个Agent CLI？

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等Agent 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 是将模型包装在循环中的程序。它读取您的提示，调用工具，编辑文件并返回结果。Claude Code 是 Harness。Codex 是 Harness。您安装它、登录，然后它就能独立运行。

框架是您基于其编写代码的库。您导入它，在 Python 中定义步骤，然后您的程序就成为 Agent。更换供应商时，需要编辑您的代码，因为供应商的客户端已经接入您的程序。

元工具控制层位于两者之上。它是一个监督程序，以子进程方式运行多个 Harness。Omnigent 启动供应商 CLI，将任务交给它，然后读取返回结果。您可以继续使用已经安装的 CLI，也可以继续使用现有的订阅或 API（application programming interface）密钥为其付费。区别仅此而已，而这也决定了该工具适合谁：已经在使用多个 Agent CLI、厌倦了每次只能在一个终端中驱动一个工具的用户。

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

更换供应商只需修改一行。 代理定义将 harness 和 model 作为数据保存，因此将某个角色从一家供应商迁移到另一家供应商，只需编辑 YAML 文件，无需重写代码。
审查可以跨供应商进行。 一个模型生成的差异内容由另一家公司提供的模型审查。同一模型系列中的两个模型往往有相同的盲点，因此，来自同一供应商的第二意见价值较低。
策略集中管理。 支出上限和审批提示在代理文件中声明，并应用于其下的所有子代理。
会话不会受单个工具限制。 一个会话记录涵盖多个 CLI 完成的工作，因此无需拼接 4 个滚动缓冲区即可回顾发生的情况。

代价是编排层本身。Omnigent 中的每个错误，现在都可能成为介于您和原本可以独立运行的代理之间的错误。在 alpha 阶段，这是真实存在的成本，而不是理论上的成本。

多智能体编排框架与单智能体工具的关系

如果您还没有在服务器上运行过单个智能体，应先从这一步开始。我们的在 VPS 上运行编码智能体指南完整介绍了单智能体场景，而 Omnigent 假定您已经完成了这种配置。更广泛的自托管 AI 智能体领域用于选择智能体本身；如果这里的术语对您来说还不熟悉，建议先阅读了解智能体的实际工作方式。

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

安装前的准备条件

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 解析为自己的选项，安装程序就无法获取该标志，因此最终安装的是当天最新的版本。对于每隔几周就发布不兼容变更的仓库来说，这决定了服务器配置是否可复现，还是会出现意外变更。

安装程序使用 Astral 的 Python 软件包管理器 uv。如果系统中没有 uv，安装程序会先询问是否安装 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。规范中的其他 harness 值包括 antigravity、copilot、kimi、qwen 和 acp:<slug>，适用于使用通用协议的组件。规范还支持在子代理上设置 pass_history: true，将父级对话传递给子代理。每次委派都会消耗令牌，因此对于只需要处理当前任务的子代理，应保持该选项关闭。若 coder 的 prompt 要求其进行可行的最小改动，它就会向 reviewer 提供一份足够简短、可以实际审阅的 diff。在这里，这一点比为任一角色选择哪个模型更重要。

为什么长时间运行的编排任务适合放在 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 -N -L 6767:localhost:6767 you@your-server 通过 SSH 转发，然后在本机打开 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。这个数值仅适用于 supervisor。每个子代理都是独立进程，拥有自己的检出目录和模型客户端，因此应根据代理数量为服务器配置规格。服务器启动后，先运行 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。2026-06-19 至 2026-07-27 期间发布了 7 个带标签的版本，其中任意两个版本之间的最长间隔为 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 中应固定一个标签；这不是代码风格偏好。

目前我还不会让它承担的任务

截至 August 2026，该仓库约有 8.1k 个 stars、1.2k 个 forks，以及约 350 个 open issues；首次公开 release 距今只有 seven weeks。Stars 反映的是关注度，而不是成熟度。项目自称 alpha，上面的 release 历史也表明它确实处于 alpha 阶段。

我不会在存放生产凭据的主机上运行它，因为 sandbox 不涵盖 MCP servers 或 supervisor。
如果没有 cost_budget policy，我不会让一次运行无人值守，因为 three vendors 可能并行计费，除此之外没有其他机制会阻止它们。
如果未设置 OMNIGENT_AUTH_ENABLED，且前端没有 TLS，我不会将服务器暴露在公网 IP 地址上。
目前我不会认为 agent YAML 在 minor versions 之间保持稳定，因此应固定版本，并在升级前阅读 release notes。

还有一点需要提前了解，以免之后感到意外：v0.6.0 添加了 anonymised usage telemetry，项目在专门的 telemetry 页面中对此进行了说明。如果这台机器处理客户工作，请阅读该页面并慎重决定。

Omnigent 目前真正擅长的是它设计之初要解决的问题。你有 three or four 个 agent CLI，已经在为它们付费，并且希望其中一个负责编写、另一个负责审查。现在可以在一台 Linux 机器上实现这一点，并获得真正的 sandboxing。除此之外的功能都应视为有潜力但尚未完成。

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