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

Omnigent 是什麼?整合多個 agent CLI 的 meta-harness

了解 Omnigent 如何驅動已安裝的 agent CLI、以 YAML 切換 harness,並固定使用 0.7.0,在 VPS 上為各 agent 建立隔離沙箱。

Omnigent 是什麼

Omnigent 是開放原始碼的中介協調框架:它提供單一協調層,驅動您已安裝的代理程式命令列工具(CLI)。它不會取代 Claude Code、Codex、Cursor、OpenCode、Hermes 或 Pi。它會啟動這些工具、為每個工具指派工作,並在單一工作階段中,以同一組政策監督執行結果。Databricks 於 June 2026 以 Apache 2.0 授權條款發布該儲存庫,而 PyPI 目前仍將此套件分類為 alpha。

實際用途很明確,值得直接說明。您只需在 YAML 中描述一次代理程式,並指定執行它的框架。修改該一行後,同一個代理程式即可改用其他廠商的 CLI 執行。設定中的其他內容都不必變更,因為 Omnigent 負責的是代理程式「上方」的迴圈,而不是代理程式「內部」的迴圈。

什麼是 meta-harness?它與 framework 有何不同?

harness 是將模型包裝在迴圈中的程式。它會讀取您的提示、呼叫工具、編輯檔案,並回報結果。Claude Code 是 harness。Codex 是 harness。您安裝它、登入後,就能讓它自行運作。

framework 是您用來撰寫程式的函式庫。您匯入它,以 Python 定義步驟,您的程式就會成為 agent。在這種架構中,更換 vendor 代表必須編輯程式碼,因為 vendor 的 client 已經透過您的程式接入。

meta-harness 位於兩者之上。它是以子程序方式執行 harness 的 supervisor。Omnigent 會啟動 vendor CLI、交付工作給它,再讀取傳回的結果。您可以繼續使用已安裝的 CLI,也能繼續使用原本支付該服務的 subscription 或 API (application programming interface) key。這就是全部差異,而這也決定了工具的適用對象:已經有多個可運作的 agent CLI,卻厭倦一次只在一個終端機中操作它們的人。

一個編排層能解決什麼問題?

  • 切換供應商只需修改一行。 代理程式定義會將 harness 和 model 作為資料保存,因此將某個角色從一家供應商移至另一家時,只需編輯 YAML 檔案,不必改寫程式。
  • 審查可跨供應商進行。 由某個模型撰寫的差異內容,可交由另一家公司提供的模型讀取。同一家族的兩個模型往往有相同的盲點,因此,向同一供應商取得第二意見的價值較低。
  • 政策集中管理。 預算門檻與核准提示都宣告在代理程式檔案中,並套用至其下的所有子代理程式。
  • 工作階段不受單一工具限制。 同一份逐字記錄涵蓋多個 CLI 完成的工作,因此無須拼接 4 個捲動記錄,就能回顧發生的事件。

代價就是這個抽象層本身。Omnigent 中的每個錯誤,現在都會變成介於你與原本可獨立運作的代理程式之間的錯誤。在 alpha 階段,這是實際存在的成本,不是理論上的問題。

多代理程式 harness 與單一代理程式工具的定位

如果您尚未在伺服器上執行過單一代理程式,請先從這裡開始。我們的 在 VPS 上執行 coding agent 指南涵蓋完整的單一代理程式情境,而 Omnigent 預設您已完成這項設定。更廣泛的 自架 AI 代理程式 領域,則是用來選擇代理程式本身;如果您不熟悉這裡的術語,建議先閱讀 了解代理程式的實際運作方式。

Omnigent 與 connector layer 也處於不同的層面。像是 讓代理程式存取您自己的資料來源,處理的是代理程式可以存取哪些內容。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 上的 wheel 已包含建置完成的 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,0.7.0 版本仍發布於 PyPI,但最新版本目前為 0.22.0,發布日期為 13 November 2026。較早的 0.19.1 版本是以安全性為重點的修補版本,沒有新增功能:它在 eMudhra 中繼憑證授權單位遭入侵後更新相依套件,專案也建議升級。重要的是固定版本,而不是版本號本身:固定使用已測試的版本,並在升級前閱讀版本說明中的破壞性變更。不過,固定版本並不是跳過安全性版本的理由,因此有新的安全性版本發布時仍應升級。

安裝程式使用 uv,也就是 Astral 的 Python 套件管理器;如果系統尚未安裝 uv,安裝程式會先提供安裝選項。如果已經有 uv,請略過該指令碼:

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

額外功能採用相同模式,旗標也會重複使用:在指令碼上使用 --extra e2b --extra kubernetes,或搭配 uv 使用 "omnigent[e2b,kubernetes]"。除非傳入 --no-databricks,否則指令碼也會加入 databricks 額外功能;上方的 uv 指令則會安裝不含該額外功能的套件。請注意,git 標籤是 v0.7.0,而 PyPI 上的套件版本是 0.7.0。

uv 會將執行檔放在 uv tool dir --bin 回報的目錄中,通常是 ~/.local/bin;安裝程式也會提供選項,將該目錄附加至 shell 設定檔。如果全新安裝後立即執行指令仍顯示找不到,原因就在這裡。請確認實際安裝的內容:

omni upgrade --check

這會將已安裝版本與最新發布版本進行比較,並告知是否有可用升級,但不會執行升級。omni 和 omnigent 是同一個程式的兩個名稱。

指定模型供應商

omni setup

精靈會尋找環境中已存在的認證資訊,並提示您補齊缺少的項目。它支援 API keys、廠商訂閱、OpenRouter 或 Ollama 等 gateway,以及 Databricks workspaces。如果您已在同一台機器上使用 Ollama 執行本機模型伺服器,可將 gateway 指向該伺服器,網路流量便不會離開本機。

最小多代理執行

範例代理程式位於 repository 中,因此請複製與已安裝版本相同的 tag,而不是 main。

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

Polly 是隨 repository 發布的多代理程式碼協調器。其設定會宣告名為 claude_code、codex、opencode、cursor、hermes 和 pi 的子代理,並包含一項讓整個練習值得執行的規則:審查一律由與實作者不同的供應商執行。Polly 本身不會撰寫程式碼。它會規劃工作、將目標拆分為工作項目、逐一委派,並將每個 diff 路由給其他供應商的審查者。

在委派任何工作前,Polly 會執行 preflight check,確認機器上實際存在的子代理 CLI。若只安裝一個供應商的 CLI,就沒有其他對象可以接手審查 diff,因此請至少安裝兩個,再評估輸出結果。另一個隨附的範例 Debby 是具有兩個頭的辯論代理,一個使用 Claude,另一個使用 GPT:

omni debby

這是確認已設定兩個 provider 的簡便方式,因為兩者都必須回應,它才會輸出內容。

子代理是以工具宣告

代理程式檔案採用 YAML。executor 定義 harness、模型與驗證方式。tools 則包含 MCP(模型內容通訊協定)伺服器、Python 函式與子代理。子代理是一項具備 type: agent 且使用自身 executor 的工具,也是上述所有功能背後的機制。

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。main 上的目前規格也記載了 acp:<slug>,可用於任何 Agent Client Protocol 伺服器;但 v0.7.0 規格並未列出這項設定,因此在依賴它之前,請先確認它能在你鎖定的版本上運作。規格也支援在子代理上設定 pass_history: true,將父代理的對話傳給子代理。每次委派都會增加 token 用量,因此只需要處理目前任務的子代理應保持停用。若 coder 的 prompt 指示它進行 可行的最小變更,就能交給 reviewer 一份實際可讀的精簡 diff;在這裡,這點比為任一角色選用哪個模型更重要。

為何長時間執行的協調工作適合放在 VPS

多代理程式執行不是 2 分鐘就能完成的命令。需要規劃、委派、等待平行的 git worktree 工作、檢查,再修改。闔上筆電螢幕就會讓整個流程結束。VPS(virtual private server)會持續運作並維持網路連線,因此你未監看時,工作階段仍能繼續。

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(transport layer security),並啟用驗證:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

其中防火牆部分是一般設定工作,VPS 的 ufw 防火牆基本設定已有說明。如果該主機已在 多個 Docker Compose 應用程式前方使用 Traefik,讓容器位於其後,Omnigent 就是採用相同模式的另一項服務。

若使用容器部署,儲存庫的 deploy/docker/ 目錄包含 Compose 設定:./bootstrap.sh 會將 secret 產生至 .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 使用其 sandbox。個別 git worktree 是協調方式的選擇,因此應依同時執行的 harness 與代理程式數量為主機配置規模。伺服器啟動後,omnigent login https://your-host 接著 omnigent host https://your-host 會將你的筆電註冊至該伺服器,而 omnigent attach <session_id> 可從其他裝置繼續使用執行中的工作階段。

隔離每個子代理程式後再離開

Omnigent 提供名為 Omnibox 的作業系統層級沙箱。在 Linux 上,它使用 bubblewrap namespace 與 seccomp,因此由 kernel 強制執行隔離邊界,而不是依賴代理程式的提示。遭提示注入的代理程式無法透過話術繞過 kernel 規則。請先安裝相依套件:

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 中。因此,發生錯誤的代理程式無法寫入 workspace 以外的位置。工作目錄頂層的 dotfile,以及每個 read_paths 根目錄,在列入 cwd_allow_hidden 前都會保持隱藏。這表示廣泛的讀取授權不會無意間暴露頂層的 .ssh 或 .aws 目錄。巢狀 dotfile 預設仍可見;設定 cwd_hidden_scan_recursive: true 可在整個樹狀目錄中將其遮蔽。設定 egress_rules 後,所有 HTTP 與 HTTPS 流量都會經由預設拒絕的 proxy,且每項規則都以 "METHODS host/path-glob" 撰寫。credential_proxy 更進一步:代理程式始終只持有 placeholder,proxy 會在請求離開時替換成實際 secret。因此,即使 transcript 洩漏,也不會洩漏可用的內容。在多個 harness 的設定中,每個子代理程式都會在 agents/ 下的專屬設定檔中保有自己的 sandbox 區塊。因此,可以拒絕 reviewer 存取網路,同時讓 implementer 保持網路存取權。

文件已說明限制,而且這項限制很重要。作業系統 sandbox 會套用至 sys_os_* tool call 與 terminal,但不涵蓋 MCP server,也不涵蓋 Omnigent supervisor process。你啟動的 MCP server 會在 sandbox 外部,以你的權限執行。正因如此,更強的做法仍是為每個代理程式準備一台一次性使用的機器;詳情請參閱 在可丟棄的 VM 中執行 coding agent。另一項工作是管理 credentials;當 6 個子代理程式共用一台 host 時,讓 secret 脫離代理程式可及範圍 只會變得更困難,而不是更容易。

支出閾值屬於 policy,並在同一個檔案中宣告:

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 policy 會在達到軟性閾值時要求確認,並預設在 max_cost_usd 阻擋所有 model。設定非空的 expensive_models list 會將限制轉為降級閘門:不在該清單中的 model 仍可繼續支出。一個 run 若使用第一家 vendor 進行規劃、第二家進行實作、第三家進行審查,就會同時在 3 個地方產生支出。因此,應在第一次無人值守的 run 前設定閾值,而不是等到收到第一張 invoice 後才設定。內建 policy 也包括 max_tool_calls_per_session 與 ask_on_os_tools,會在 file 與 shell operation 前要求核准。我們在 控制 VPS 上的 AI agent 成本 中的筆記同樣適用於此,而且重要性更高,因為平行執行的子代理程式會使消耗速率倍增。

此儲存庫的更新速度有多快?

圖表Days between tagged Omnigent releases, v0.2.0 to v0.7.0
此圖表背後的資料
[
  {
    "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 page 上公布的發布日期,資料讀取於 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 page 中,因此不納入圖表;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 應指定 tag 的原因,而不是排版偏好。

截至該次查閱後,發布速度並未放緩。到 29 October 2026 為止,PyPI 已列出 0.20.0;此版本於 28 October 發布,時間上是在 0.7.0 之後的第 13 個 minor release,而且專案的 release notes 已指出其中數個版本包含 breaking changes。以下兩項會影響從本頁複製的內容:v0.12.0 讓單獨執行 omni 時啟動 background host,而不是 Polly agent(omni run 現在會啟動預設 agent);v0.13.0 則要求 managed terminals 使用 tmux 3.3 或更新版本。

目前我還不會交給它處理的工作

截至 27 October 2026,該儲存庫約有 11k 顆 stars、1.8k 個 forks,以及約 910 個 open issues;首次公開 release 也才四個多月。Stars 代表關注度,不代表成熟度。專案標示為 alpha,而前述 release 歷程也顯示它確實仍處於 alpha 階段。

  • 我不會在存放 production credentials 的主機上執行它,因為 sandbox 不涵蓋 MCP servers 或 supervisor。
  • 我不會在沒有 cost_budget policy 的情況下讓執行工作無人監看,因為三家 vendor 可能同時計費;只要 expensive_models list 不為空,系統就可能繼續使用較便宜的 models,產生支出。
  • 我不會在未設定 OMNIGENT_AUTH_ENABLED 且未在前方配置 TLS 的情況下,將 server 暴露於 public IP address。
  • 目前我不會把 agent YAML 視為 minor versions 之間保持穩定的介面,因此應固定版本,並在升級前閱讀 release notes。

還有一點要先了解,以免日後措手不及:v0.6.0 加入了匿名化的使用遙測資料。README 表示系統預設會收集這些資料,而專案也在專用的 telemetry page 上說明相關內容,包括如何選擇退出。如果該機器處理 client 工作,請先閱讀該頁面,再審慎決定。

Omnigent 目前真正擅長的,是它原本設計要處理的工作。你有三或四個 agent CLIs,已經付費使用它們,並希望讓其中一個負責撰寫,另一個負責審查。這項用法目前可行:在單一機器上,於 Linux 使用真正的 sandboxing。除此之外,都應視為前景可期但尚未完成。

FAQ

Omnigent 是代理程式,還是執行代理程式的工具?

它會執行代理程式。Omnigent 是中繼執行框架:它會啟動您已安裝的廠商 CLI,例如 Claude Code、Codex 或 OpenCode,為每個 CLI 指派工作,並在同一個工作階段監督執行結果。它本身不包含模型。因此它不同於框架;使用框架時,您會針對函式庫撰寫 Python,而您自己的程式會成為代理程式。

在 Omnigent 發揮作用前,我需要先安裝 Claude Code 和 Codex 嗎?

您至少需要安裝並登入一個廠商 CLI,因為 Omnigent 是驅動這些程式,而不是取代它們。若要執行隨附的 Polly 範例,您需要來自不同廠商的 2 個以上 CLI。Polly 的規則是,審查一律由與實作者不同的廠商執行。因此,若只存在單一 CLI,就沒有第二個廠商可以接收差異內容。

如何安裝特定版本的 Omnigent,而不是最新版本?

透過安裝指令碼搭配 sh -s -- 傳入 --version,例如 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 sandbox 足以讓代理程式以無人值守方式執行嗎?

對於涵蓋的範圍,它提供強隔離;對於未涵蓋的範圍,文件也有明確說明。在 Linux 上,它使用 bubblewrap 加上 seccomp,因此檔案與網路限制由核心強制執行,代理程式無法選擇退出。文件指出,它適用於 sys_os_* 工具呼叫與終端機,但不涵蓋 MCP 伺服器或 Omnigent supervisor 程序。因此,MCP 伺服器會以您的一般權限執行;這也是為每個代理程式使用一台可拋棄式虛擬機器,仍然是無人值守工作較強隔離方式的原因。

VPS 上的 Omnigent 伺服器需要多少記憶體?

專案的部署說明指出,閒置時 RSS 約為 275 MB,Fly.io 設定則配置 1 GB 的 machine。閒置測量只涵蓋伺服器本身,不包含其子代理程式。子代理程式可以共用父程序的工作目錄與環境,包括透過 os_env: inherit 使用其 sandbox;但不保證會使用個別的工作副本。Polly 類型的執行會使用平行的 Git worktree,因此應依照計畫同時執行的代理程式數量,而不是伺服器本身,來配置 RAM 與磁碟空間。

這篇文章對您有幫助嗎?