Omnigent 安装:先认识这个工具

Omnigent 是一个开源的 AI Agent 元框架(meta-harness),Apache-2.0 协议、Python 3.12+,GitHub star 约 1 万(2026-09 查询为 10,361),在 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 等编码代理之上加一层公共编排层。典型的安装动机有三个:想让多个编码 CLI 进同一个会话、想给 Agent 加审批和云沙箱、想让会话在终端、浏览器、手机之间接力。这篇是安装与上手工具书,从依赖清单到升级卸载一次讲完;能力的完整介绍见(Omnigent 是什么)。

三种安装方式:按你的工具链选

结论先给:首次安装推荐一键脚本;macOS 用户可以走 Homebrew;已经在用 uv 或 pip 管理工具链的用手动安装。三种方式装出来的是同一个 Omnigent。

方式一,一键脚本(首次安装推荐):

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

方式二,uv 或 pip 手动安装:

uv tool install omnigent
# 或者用 pip
pip install "omnigent"
# 带 extras 安装:同时启用 Databricks 模型接入与 Modal 沙箱
uv tool install "omnigent[databricks,modal]"

方式三,Homebrew(macOS):

brew install omnigent-ai/tap/omnigent

三种方式放在一起看:

方式命令要点适合谁
一键脚本install_oss.sh 一条命令跑完首次安装、想最省事的人
uv / pipuv tool install omnigent已有 Python 工具链的人
Homebrewbrew install omnigent-ai/tap/omnigentmacOS 上习惯用 brew 管软件的人

一个前提要交代:Omnigent 本身要求 Python 3.12+(官方 README),而 uv 是官方指定的运行基础,这正是 uv 被列进必需依赖的原因。选定一种安装方式后尽量固定用下去——omni upgrade 升级时会检测安装方式(下文详述),方式混着换只会给自己找麻烦。

内网或私有镜像环境有专门的口子:源码安装支持镜像覆盖,通过 HOMEBREW_PIP_INDEX_URL 与 HOMEBREW_CARGO_INDEX_URL 指向自己的镜像源即可。这个设计后面还会再出现一次——更新检查同样尊重包索引配置,私有镜像环境开箱即用(以上均出自官方 README)。

extras 体系:四类可选依赖按需加装

结论先给:extras 是可选依赖分组,安装时用 —extra 语法点名,比如 —extra modal,e2b 就同时启用 Modal 和 E2B 两个沙箱后端。官方 README 把 extras 分成四类:

类别extras 取值用途
模型供应商类databricks、bedrock、vertex企业级模型托管平台接入
沙箱类modal、daytona、blaxel、boxlite、microsandbox、cwsandbox、e2b、openshell、kubernetes把会话放进对应云沙箱
SDK harness 类antigravity、copilot、cursor、agents-sdk接入对应 SDK 型 harness
存储记忆类s3、hindsight会话存储与记忆后端

按需加装就好:只跑本地会话,一个 extras 都不用装;要用某家云沙箱,就加对应的沙箱类 extras,治理与沙箱的完整玩法见(Omnigent 的治理与沙箱)。

依赖清单:装之前先对一遍

结论先给:uv 和 git 是硬依赖,其余按你用到的功能装。官方 README 给出的依赖如下:

依赖要求用途
uv必需Python 工具链管理,安装与运行的基础
git必需版本库操作
Node.js 22 LTS+ 与 npm编码 harness CLI 需要支撑各编码代理 CLI 的运行
pnpmWeb UI 需要本地 Web 界面
tmux原生终端包装器必需终端会话承载
bubblewrap(bwrap)仅 Linux给代理终端包 OS 沙箱
Devin CLI、Kiro CLI可选用到对应代理时再装

唯一要划重点的是 bubblewrap:它只在 Linux 上需要,是本地 OS 沙箱的底座,Linux 用户建议提前装好;macOS 与 Windows 不涉及。

首次运行:敲下 omnigent 之后发生什么

结论先给:安装后 omnigent 与 omni 两个命令等价,直接运行 omnigent 会带你选模型并打开本地 Web UI,地址是 http://localhost:6767。

首次运行有个省心的细节:Omnigent 会自动识别环境里已有的 ANTHROPIC_API_KEY、OPENAI_API_KEY,或者已经登录过的 claude、codex CLI,并提议把它们设为默认。也就是说,你本来就订阅着 Claude 或 ChatGPT 的话,装完不用重新配任何凭据,选个模型就能开工。

具名启动:八条一键命令与两种两步走

结论先给:主流 harness 都有专属启动命令,格式就是 omnigent 加 harness 名。

命令启动的 harness备注
omnigent claudeClaude Code
omnigent codexCodex
omnigent cursorCursor
omnigent agyAntigravity需要 agy 1.1.13+
omnigent opencodeOpenCode
omnigent hermesHermes
omnigent piPi
omnigent copilotCopilot

Grok Build 与 Devin 没有专属启动器,走两步:先用厂商自己的 CLI 登录,再让 Omnigent 以对应 harness 拉起会话:

# Grok Build:先登录,再拉起
grok login --device-auth
omnigent run --harness grok    # grok-build 亦可

# Devin:先登录,再拉起
devin auth login
omnigent run --harness devin

这两家的会话走 Agent Client Protocol(ACP)over stdio,Omnigent 不存储任何凭据。有一个容易踩的细节要划出来:对这两类 harness,—model 参数会被拒绝而非被静默忽略——会话跑的是账户默认模型;想钉住某个模型,需要配置 acp: 代理,由它传厂商自己的模型 flag。Grok Build 的来龙去脉可以看(Grok Bot 是什么)。

顺带一提,混用多家 harness 的多代理玩法(让一个代理评审另一个、按特长拆任务)在(Omnigent 多代理协作实战)里展开。

升级与卸载:排空机制与备份提醒

结论先给:升级用 omni upgrade,卸载用 omnigent uninstall,两者都带防误伤设计。

omni upgrade          # 检测安装方式并升级
omni upgrade --check  # 只查版本,不执行升级

omni upgrade 的流程值得拆开讲:它先检测你的安装方式,然后排空并停掉本地服务器——默认等待在途会话结束再动手,着急可以用 —force 立即停。源码检出的用户走 git pull 升级。不想参与更新检查的话,设置 OMNIGENT_NO_UPDATE_CHECK=1;更新检查走你配置的包索引(UV_INDEX_URL、PIP_INDEX_URL、uv.toml、pip.conf,可用 OMNIGENT_INDEX_URL 覆盖),所以私有镜像环境不需要为此改任何东西。

卸载分三档,建议按从轻到重的顺序来:

omnigent uninstall           # 先预览将删除的内容
omnigent uninstall --yes     # 确认执行
omnigent uninstall --purge   # 连 ~/.omnigent 一起清除

—purge 会清掉 /.omnigent,官方 README 明确提醒:删除前先把需要的东西备份到目标之外。默认情况下 workspace 目录(/omnigent)会保留,除非你显式加 —purge-workspace。数据无价,这两条提醒都值得记住。

常见问题

Q:Omnigent 安装需要哪些前置依赖?

直接答:必需的只有 uv 和 git 两项;用编码 harness 要装 Node.js 22 LTS+ 与 npm,Web UI 需要 pnpm,原生终端包装器需要 tmux,Linux 本地沙箱需要 bubblewrap。

展开说:这份清单出自官方 README。最省事的路径是先装 uv,再用一键脚本装 Omnigent;Linux 用户额外装一个 bubblewrap,为本地 OS 沙箱做准备。

Q:omnigent 教程里反复出现的 extras 是什么?

直接答:extras 是可选依赖分组,安装时用 —extra 点名启用,官方分四类——模型供应商、沙箱、SDK harness、存储记忆,用到哪类装哪类。

展开说:比如 uv tool install “omnigent[databricks,modal]” 就一次装上 Databricks 模型接入与 Modal 沙箱支持。不装 extras 也能正常跑本地会话,extras 只在接对应后端时才需要。

Q:agent 框架部署在内网或私有镜像环境可行吗?

直接答:可行。源码安装支持 HOMEBREW_PIP_INDEX_URL、HOMEBREW_CARGO_INDEX_URL 镜像覆盖,更新检查也尊重 UV_INDEX_URL、PIP_INDEX_URL 等包索引配置,还可用 OMNIGENT_INDEX_URL 覆盖。

展开说:这意味着安装与升级链路可以整体指向私有镜像,不必访问公网包源。对企业内网部署 agent 框架来说,这个特性比功能列表更关键。