Omnigent 是什麼？如何整合多個 agent CLI

Omnigent 是什麼

Omnigent 是開放原始碼的 meta-harness：一個負責協調的層，驅動您已安裝的 agent 命令列工具（CLI）。它不會取代 Claude Code、Codex、Cursor、OpenCode、Hermes 或 Pi。它會啟動這些工具、為每個工具指派工作，並在單一工作階段中依照同一組政策監督執行結果。Databricks 於 June 2026 以 Apache 2.0 授權條款發布該 repository，而首頁目前仍顯示 Status: alpha。

實際用途很明確，也值得直接說明。您只需在 YAML 中描述一次 agent，並指定執行它的 harness。修改該一行後，同一個 agent 就能改用其他廠商的 CLI 執行。設定中的其他內容都不必變更，因為 Omnigent 管理的是 agent 上層 的迴圈，而不是 agent 內部 的迴圈。

什麼是 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，卻厭倦一次只在一個終端機中操作它們的人。

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

• 切換供應商只需修改一行。 Agent 定義會將 harness 和 model 作為資料保存，因此只要編輯 YAML 檔案，就能將某個角色從一家供應商移轉至另一家，不必重寫程式。
• 可以跨供應商進行審查。 由一個模型產生的 diff，可交由另一家公司的模型讀取。同一家族的兩個模型通常有相同的盲點，因此同一供應商提供的第二個意見，價值較低。
• 政策集中管理。 支出上限與核准提示都在 agent 檔案中宣告，並套用至其下的每個 sub-agent。
• 工作階段不受單一工具限制。 同一份 transcript 會涵蓋多個 CLI 完成的工作，因此你可以直接回顧發生的事情，不必拼接 4 份捲動記錄。

代價就是這個編排層本身。Omnigent 的每個錯誤，現在都會成為你與原本能獨立運作的 agent 之間的錯誤。在 alpha 階段，這是實際存在的成本，不是理論上的問題。

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

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

Omnigent 與 connector layer 也處於不同的層面。像是 讓代理程式存取您自己的資料來源，處理的是代理程式可以存取哪些內容。Omnigent 處理的則是執行哪個代理程式、依何種順序執行，以及適用哪些限制。兩者可以同時使用，功能也不重疊。

安裝前的必要條件

• Python 3.12 或更新版本。已發布的套件宣告 requires-python >= 3.12。
• tmux，因為終端機 harness 會在其中執行。
• 至少一個廠商 CLI，且已完成安裝與登入。
• 僅在從 git checkout 建置時需要 Node.js 22。PyPI 上的 wheel 已包含建置完成的網頁資產，因此一般安裝完全不需要 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 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 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（model context protocol）伺服器、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，將父代理的對話傳遞給子代理。每次委派都會因此消耗 token，因此只需要處理目前任務的子代理應省略此設定。若 coder 的 prompt 要求其執行可運作的最小變更，就能交給 reviewer 一份短到實際可讀的 diff；在這裡，這點比為任一角色選用哪個模型更重要。

長時間執行的協調工作應放在 VPS 上

多代理程式執行不是 2 分鐘就能完成的指令。你需要規劃、分派工作、等待平行 git worktree 完成、審查並修訂。闔上筆記型電腦螢幕就會中止整個流程。VPS（virtual private server）會持續運作並維持網路連線，因此即使你暫時沒有監看，工作階段仍能繼續。

omnigent server --background
omnigent server status

伺服器會在 port 6767 上提供 Web 使用者介面。omnigent server status 可回報目前是否有執行中的工作階段，omnigent stop 可將其停止。在 v0.7.0 以前的版本中，這項功能使用 omni server start；該指令後來已移除，因此舊有文章與截圖可能會與終端機中的實際結果不一致。

不要在公開位址上發布 6767。以下兩種架構是安全的。先在防火牆封鎖該 port，再使用 ssh -N -L 6767:localhost:6767 you@your-server 透過 SSH 轉送，然後在自己的電腦上開啟 http://localhost:6767。或者在前端終止 TLS（transport layer security），並啟用驗證：

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

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

若使用容器部署，repository 的 deploy/ 目錄包含 Compose 設定：./bootstrap.sh 會將 secret 產生至 .env，接著 docker compose up -d 會在 port 6767 上啟動 Omnigent 與 Postgres。DATABASE_URL 可選擇 Postgres 或 SQLite；在容器內，OMNIGENT_AUTH_ENABLED 預設為 1，對任何可從外部連線的服務而言，這是適當的預設值。

就規模而言，部署說明指出伺服器的工作集約為 512 MB 至 1 GB，而 Fly.io 設定固定使用 1 GB。這個數值只涵蓋 supervisor。每個子代理程式都是獨立程序，會持有自己的 checkout 與 model client，因此應依代理程式數量為主機配置足夠資源。伺服器啟動後，先執行 omnigent login https://your-host，再執行 omnigent host https://your-host，即可將筆記型電腦註冊至該伺服器；omnigent attach <session_id> 則可從其他裝置恢復執行中的工作階段。

離開前，先為每個子代理程式啟用 sandbox

Omnigent 提供名為 Omnibox 的作業系統層級 sandbox。在 Linux 上，它使用 bubblewrap namespace 與 seccomp，因此由 kernel 強制執行隔離界線，而不是依賴代理程式的提示詞。遭到 prompt injection 的代理程式無法透過說服方式繞過 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 之外寫入。除非在 cwd_allow_hidden 中明確指定，否則 dotfile 會保持隱藏。這表示廣泛的讀取授權不會無意間暴露 .ssh 或 .aws。設定 egress_rules 後，所有 HTTP 與 HTTPS 流量都會通過預設拒絕的 proxy，每條規則都寫成 "METHODS host/path-glob"。credential_proxy 更進一步：代理程式始終只持有 placeholder，proxy 會在請求離開時替換成真正的 secret。因此，即使 transcript 外洩，也不會洩露任何可用資訊。在多個 harness 的設定中，每個子代理程式都會在 agents/ 下自己的設定檔中保有獨立的 sandbox 區塊。因此，可以禁止 reviewer 存取 network，同時保留 implementer 的存取權。

文件已說明這項限制，而且必須注意。作業系統 sandbox 會套用至 sys_os_* tool call 與 terminal，但不涵蓋 MCP server，也不涵蓋 Omnigent supervisor process 本身。你啟動的 MCP server 會在 sandbox 外部，以你的權限執行。這項缺口正是較強隔離模式仍採用每個代理程式一台 disposable VM 的原因；相關內容請參閱 在 disposable VM 中執行 coding agent。另一項工作是管理 credentials。當 6 個子代理程式共用一台 host 時，讓 secret 遠離代理程式可存取範圍 會變得更困難，而不是更簡單。

Spend limit 是政策，並且宣告在同一個檔案中：

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]

如果某次執行先使用一家 vendor 進行規劃，再使用第二家實作，最後使用第三家審查，就會同時在 3 個地方產生費用。因此，應在第一次 unattended run 前設定上限，而不是等到第一張 invoice 產生後才設定。內建功能也包括 max_tool_calls_per_session 與 ask_on_os_tools，可在執行 file 與 shell operation 前要求核准。我們在 控制 VPS 上的 AI agent 成本 中的說明可直接套用於此，而且更加重要，因為平行執行的子代理程式會使消耗速度倍增。

這個儲存庫的更新速度如何？

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

以上是該專案在 2026 年 8 月 3 日讀取其官方 releases 頁面所得的發布日期。2026-06-19 至 2026-07-27 之間共有 7 個已標記的版本發布，其中任兩次發布之間最長間隔為 11 天。v0.5.1 與前一個版本在同一天發布。第一個版本 0.1.1 於 2026 年 6 月 16 日發布，但因為沒有前一個 tag 可供計算，因此未列入圖表。

其中兩個版本會破壞指南已記載的命令。v0.7.0 移除了 omni server start，改用 omni server --background。v0.6.0 將 omnigent[memory] extra 重新命名為 omnigent[hindsight]，因此從 6 月文章複製的安裝命令，在 7 月建置版本上會失敗。這正是安裝命令應指定 --version，並在 git clone 中固定 tag 的原因，而不是單純的格式偏好。

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

截至 2026 年 8 月，該儲存庫約有 8.1k 顆 stars、1.2k 個 forks，以及約 350 個開放 issue；首次公開發布距今只有七週。Stars 代表關注度，關注度不等於成熟度。專案自稱 alpha，而上方的發布紀錄也顯示它確實仍處於 alpha 階段。

• 我不會在存放 production credentials 的主機上執行它，因為 sandbox 不涵蓋 MCP servers 或 supervisor。
• 沒有設定 cost_budget policy 時，我不會讓執行程序無人監看，因為三個 vendor 可能同時計費，而且沒有其他機制會阻止這種情況。
• 沒有設定 OMNIGENT_AUTH_ENABLED 並在前方配置 TLS 時，我不會將 server 暴露在 public IP address 上。
• 我暫時不會把 agent YAML 視為 minor version 之間穩定不變，因此請固定 version，並在升級前閱讀 release notes。

還有一點需要先知道，以免它突然造成意外：v0.6.0 新增了匿名化使用遙測功能，專案也在專用的 telemetry page 上說明此功能。如果該機器處理 client 工作，請閱讀該頁面後再審慎決定。

Omnigent 目前真正擅長的，是它原本要解決的問題。你有三或四個 agent CLI，已經為這些工具付費，並希望其中一個負責撰寫，另一個負責審查。現在這種用法已可在單一機器上運作，而且在 Linux 上具備真正的 sandboxing。除此之外的功能，都應視為有潛力但尚未完成。

FAQ

Omnigent 是 agent，還是執行 agents 的工具？

它會執行 agents。Omnigent 是一個 meta-harness：它會啟動你已安裝的 vendor CLI，例如 Claude Code、Codex 或 OpenCode，為每個 CLI 指派工作，並在同一個 session 中監督結果。它本身不提供模型。因此，它不同於 framework；使用 framework 時，你會針對 library 撰寫 Python，而自己的程式會成為 agent。

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

你至少需要安裝並登入一個 vendor CLI，因為 Omnigent 是驅動這些程式，而不是取代它們。若要使用隨附的 Polly 範例，則需要來自不同 vendor 的兩個以上 CLI。Polly 的規則是，review 必須由與 implementer 不同的 vendor 執行。因此，若只有一個 CLI，便沒有第二個 vendor 可接收 diff。

如何安裝特定的 Omnigent 版本，而不是最新版？

透過安裝腳本搭配 sh -s -- 傳入 --version，例如 sh -s -- --version 0.7.0。如果沒有 -s --，該 flag 會由 sh 本身取用，腳本則會安裝最新 release。若已安裝 uv，uv tool install --force --python 3.12 "omnigent==0.7.0" 也能執行相同工作。git tag 是 v0.7.0，PyPI version string 則是 0.7.0。

Omnibox sandbox 足以讓 agents 無人值守地執行嗎？

對於涵蓋的範圍，它提供的隔離能力很強，也清楚說明未涵蓋的部分。在 Linux 上，它使用 bubblewrap 加上 seccomp，因此由 kernel 強制套用檔案與網路限制，agent 無法選擇停用這些限制。文件說明它適用於 sys_os_* tool calls 和 terminals，但不涵蓋 MCP servers 或 Omnigent supervisor process。因此，MCP server 會以你的正常權限執行；這也是無人值守工作仍以每個 agent 使用一台可拋棄式 virtual machine 作為更強隔離方式的原因。

VPS 上的 Omnigent server 需要多少記憶體？

專案的 deploy notes 指出，server 的工作集約為 512 MB 至 1 GB，而其 Fly.io 設定固定使用 1 GB。這只涵蓋 supervisor 及僅監聽 port 6767 的 web interface。每個 sub-agent 都是獨立 process，具有自己的 working copy 和 model client；Polly 類型的執行也會使用平行 git worktrees。因此，應依預計同時執行的 agents 數量，而不是依 server 本身，來規劃 RAM 和磁碟空間。