Omnigent怎么用：统一编排多个Agent CLI

Omnigent 是什么

Omnigent 是一个开源元级运行框架：它提供一个编排层，用于驱动您已经安装的智能体命令行工具（CLI）。它不会替代 Claude Code、Codex、Cursor、OpenCode、Hermes 或 Pi。它会启动这些工具，为每个工具分配任务，并在单个会话中使用统一的策略集监督执行结果。Databricks 于 2026 年 6 月以 Apache 2.0 许可证发布了该仓库，PyPI 目前仍将此软件包归类为 alpha 版本。

它的实际定位很明确，也值得直接说明。您只需在 YAML 中定义一次智能体，并指定运行它的 harness。修改这一行后，同一个智能体即可使用其他厂商的 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，因为终端 harness 在其中运行。
• 至少安装并登录一个供应商 CLI。
• Node.js 22 或更高版本，以及 npm，因为 Claude、Codex 和 Pi harness 需要这些组件。安装程序会检查 Node 22.10 或更高版本；如果缺少，则发出警告。Omnigent 本身不需要 Node：PyPI 上的软件包已包含构建好的 Web 资源，只有从 git checkout 构建时，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 解析为自身的选项，安装程序根本不会运行。当 sh 为 Bash 时，它会输出 Bash 自身的版本并成功退出，因此既不会安装任何内容，也不会显示警告。使用 -s -- 后，sh会从管道读取脚本，并将 --version 0.7.0 传递给安装程序。对于每隔几周就发布破坏性变更的仓库，这决定了服务器是可复现的环境，还是会带来意外变更的环境。

截至 29 October 2026，Release 0.7.0 仍发布在 PyPI 上，但最新版本现在是 0.21.0，发布日期为 5 November 2026。较早的 0.19.1 版本是一个专注于安全性的补丁版本，不包含新功能：它在 eMudhra 中间证书颁发机构遭到入侵后更新了依赖项，项目也建议升级。重要的是固定版本，而不是版本号本身：固定为已测试的版本，并在升级前阅读发布说明中的破坏性变更。不过，固定版本并不意味着可以跳过安全版本，因此在安全版本发布后应及时升级。

安装程序使用 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]"。除非传入 --no-databricks，脚本还会添加 databricks extra；上面的 uv 命令则会在不添加该 extra 的情况下安装软件包。请注意，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 定义运行框架、模型和身份验证信息。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。main 上的当前规范还记录了适用于任何 Agent Client Protocol 服务器的 acp:<slug>，但 v0.7.0 规范未列出该配置项。因此，在依赖它之前，请确认它在你固定使用的版本上有效。该规范还支持在子代理上设置 pass_history: true，将父级对话传递给子代理。每次委派都会因此消耗额外 token，因此对于只需处理当前任务的子代理，应将其关闭。若 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，改用 omni server --background；v0.9.0 将其作为已弃用的别名恢复。

不要在公网地址上发布 6767。有两种安全方式。让防火墙保持该端口关闭，并使用 ssh -N -L 6767:localhost:6767 you@your-server 通过 SSH 转发，然后在自己的计算机上通过 http://localhost:6767 打开 Web 界面。或者在其前面终止 TLS（传输层安全），并启用身份验证：

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

其中防火墙部分属于常规工作，VPS 的 ufw 防火墙基础已对此进行说明。如果服务器已经通过 位于多个 Docker Compose 应用前的 Traefik 运行容器，那么 Omnigent 只是采用相同模式的另一个服务。

对于容器部署，仓库的 deploy/docker/ 目录包含 Compose 配置：./bootstrap.sh 将密钥生成到 .env，然后 docker compose up -d 启动 Omnigent 和 Postgres；此时服务器使用端口 8000，而不是 6767。OMNIGENT_PORT 修改该主机端口。Compose 会为你计算 DATABASE_URL（在其他部署目标上，同一变量用于选择 Postgres 或 SQLite），而 OMNIGENT_AUTH_ENABLED 在容器内默认使用 1，对于任何需要从外部访问的服务，这是正确的默认值。

关于规格，部署说明称服务器的空闲内存使用量约为 275 MB RSS，而 Fly.io 配置固定使用 1 GB 机器。空闲测量值仅针对 supervisor；1 GB 是分配给机器的内存。子代理可以共享父代理的工作目录和环境，包括通过 os_env: inherit 使用其沙箱。单独的 git worktree 属于编排选择，因此应根据并发运行的 harness 和代理为服务器配置规格。服务器启动后，先运行 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 之前，该目录为只读。因此，出错的代理无法在工作区之外写入内容。工作目录顶层的点文件以及每个 read_paths 根目录默认保持隐藏，除非在 cwd_allow_hidden 中明确指定。这意味着，即使授予广泛的读取权限，也不会意外暴露顶层的 .ssh 或 .aws 目录。嵌套点文件默认仍然可见；将 cwd_hidden_scan_recursive: true 设置为在整个目录树中屏蔽这些文件。设置 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]

cost_budget 策略会在达到软阈值时请求批准，并默认在 max_cost_usd 处阻止所有模型。设置非空的 expensive_models 列表后，该限制会变为降级门槛：列表之外的模型仍可继续产生支出。如果一次运行先使用一家供应商进行规划，再使用第二家供应商进行实现，最后使用第三家供应商进行审查，就会同时产生 3 处支出。因此，应在首次无人值守运行前设置阈值，而不是等到收到第一张账单后再设置。内置策略还包括 max_tool_calls_per_session 和 ask_on_os_tools，它们会在执行文件操作和 shell 操作前请求批准。我们关于控制 VPS 上 AI 代理成本的说明同样适用于这里，而且更为重要，因为并行子代理会成倍提高消耗速度。

该仓库的开发速度有多快？

[
  {
    "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
  }
]

这些是项目自身 releases 页面发布的版本日期，数据读取于 3 August 2026。7 个带标签的版本发布于 2026-06-19 至 2026-07-27 之间，任意两个版本之间的最长间隔为 11 天。v0.5.1 与前一个版本在同一天发布。最初的两个 PyPI 版本（0.1.0 于 13 June 2026 发布，0.1.1 于 16 June 2026 发布）没有出现在 GitHub releases 页面中，因此未计入图表；v0.2.0 显示的 3 天是从 0.1.1 开始计算的。

其中两个版本修改了指南已经记录的命令。v0.7.0 移除了 omni server start，改用 omni server --background。v0.6.0 将 omnigent[memory] extra 重命名为 omnigent[hindsight]，但保留 memory 作为兼容性别名，该别名一直可用到 0.10.0。从 25 August 2026 发布的 0.11.0 开始，该别名已移除，因此从 June 的文章中复制的安装命令不再安装 Hindsight client。这就是安装命令中应使用 --version，并在 git clone 中固定版本标签的原因，而不是样式偏好。

自那次读取以来，发布速度并未放缓。截至 29 October 2026，PyPI 已列出 0.20.0，该版本于 28 October 发布；在 0.7.0 之后又发布了 13 个 minor 版本，项目的 release notes 标明其中多个版本包含破坏性变更。对于从本页复制的内容，有两项变更需要注意：v0.12.0 使单独使用 omni 时启动后台 host，而不再启动 Polly agent（现在使用 omni run 启动默认 agent）；v0.13.0 要求使用 tmux 3.3 或更高版本来管理终端。

目前不应交给它处理的任务

截至 2026 年 10 月 27 日，该仓库约有 11k 个 star、1.8k 个 fork，以及约 910 个未解决 issue。首次公开发布距今只有四个多月。star 数量反映的是关注度，而不是成熟度。项目将自身标记为 alpha，上面的发布历史也表明它确实仍处于 alpha 阶段。

• 我不会在存放生产凭据的主机上运行它，因为沙箱不涵盖 MCP 服务器或 supervisor。
• 没有设置 cost_budget policy 时，我不会让运行过程无人值守，因为三个供应商可能并行产生费用；如果 expensive_models 列表非空，系统可能继续在更便宜的模型上产生支出。
• 未设置 OMNIGENT_AUTH_ENABLED 并在其前方配置 TLS 时，我不会将服务器暴露在公网 IP 地址上。
• 目前我不会认为 agent YAML 在小版本之间保持稳定。因此应固定版本，并在升级前阅读 release notes。

还有一点需要提前了解，以免它在运行时让您感到意外：v0.6.0 增加了匿名使用遥测功能。README 说明该功能默认收集数据，项目也在专门的 telemetry 页面中介绍了相关信息，包括退出收集的方法。如果这台机器处理客户工作，请阅读该页面并慎重决定。

Omnigent 目前真正擅长的是它的设计目标。您有三个或四个 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 会将 --version 当作自己的选项，安装程序不会运行：例如，Bash 会打印自己的版本并退出。如果已经安装 uv，则 uv tool install --force --python 3.12 "omnigent==0.7.0" 可完成相同的工作。Git 标签是 v0.7.0，而 PyPI 版本字符串是 0.7.0。

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

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

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

项目的部署说明显示，服务器空闲时的 RSS 约为 275 MB；其 Fly.io 配置分配了一台 1 GB 的实例。该空闲测量值仅包含服务器本身，不包含其子代理。子代理可以共享父进程的工作目录和环境，包括通过 os_env: inherit 共享其沙箱；但不能保证使用独立的工作副本。Polly 风格的运行会并行使用 Git worktree，因此应根据计划同时运行的代理数量规划内存和磁盘，而不是只按服务器本身规划。