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 / pip | uv tool install omnigent | 已有 Python 工具链的人 |
| Homebrew | brew install omnigent-ai/tap/omnigent | macOS 上习惯用 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 的运行 |
| pnpm | Web 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 claude | Claude Code | |
| omnigent codex | Codex | |
| omnigent cursor | Cursor | |
| omnigent agy | Antigravity | 需要 agy 1.1.13+ |
| omnigent opencode | OpenCode | |
| omnigent hermes | Hermes | |
| omnigent pi | Pi | |
| omnigent copilot | Copilot |
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 框架来说,这个特性比功能列表更关键。