omnigent-ai/omnigent · 上手攻略
- 仓库：omnigent-ai/omnigent
- 链接：https://github.com/omnigent-ai/omnigent
- 分类：ai
- 作者：Jay
- 更新：2026-07-12
是什么
Omnigent 是一个开源的 AI Agent 元编排框架（meta-harness）：在它之上，你可以同时运行和编排 Claude Code、Codex、Cursor、OpenCode、Pi 以及自己写的自定义 Agent，无需重写任何 Agent 代码。它不是一个新 Agent，而是一个通用的 Agent 管理层——像一层胶水，把各种主流 Agent 产品统一纳入管控。
核心功能： - 多 Agent 混合编排：同一会话中同时运行多个不同 Agent，让它们互相 Review、分工协作 - 跨设备实时同步：终端、浏览器、手机都能接入同一会话，文件、消息、子 Agent 状态全同步 - 策略治理：按需暂停危险操作、限制预算、控制 Agent 可访问的工具范围 - 云沙箱：无需本地算力，可在 Modal、Daytona、E2B、Daytona、Kubernetes 等云环境运行 Agent - 实时协作：把会话分享给队友，对方可以围观或共同操控
解决什么问题
当你想用多个 Agent 协同完成复杂任务时，通常的做法是分别在不同的终端里跑不同 Agent，靠人工整合结果——既繁琐又难以统一管理。
Omnigent 提供的核心价值： 1. 一个界面管理所有 Agent：不关掉 Claude Code 也能跑 Codex，两者并行、互相 Review 2. 策略管控：在团队/共享环境中用 Policy 控制 Agent 行为，避免删库跑路 3. 无需换设备也能跑大模型：云沙箱模式让你在普通笔记本上调用云端 Agent，不耗本地资源 4. 会话持久化：Agent 跑了一半换个设备继续，不用重开
快速安装
前置要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| Python | 3.12+ | 最低要求，必须精确版本 |
| uv | 最新版 | 推荐包管理器 |
| git | 任意版本 | 源码安装时需要 |
| Node.js + npm | 22 LTS+ | 用于 Claude/Codex/OpenCode/Pi 等 npm 安装的 Agent CLI |
| tmux | 任意版本 | 终端多路复用，macOS/ Linux 均需安装 |
| bubblewrap（Linux） | — | Linux 下 Agent 沙箱隔离必需（apt install bubblewrap）；macOS 用内置 seatbelt，无需额外安装 |
Windows 原生支持（部分功能受限，见坑与注意）。
推荐安装（一键脚本）
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh
脚本自动检测并安装：uv、git、Node.js 22 LTS、tmux、bubblewrap（Linux）。
手动安装
# 用 uv（推荐）：
uv tool install omnigent
# 或 pip：
pip install omnigent
# 或从源码：
uv tool install --python 3.12 git+https://github.com/omnigent-ai/omnigent.git
# 或 macOS Homebrew：
brew install omnigent-ai/tap/omnigent
Windows 原生安装（不支持部分功能）：
uv tool install --python 3.12 omnigent
# 或
pip install omnigent
验证安装
omni --version # 或
omnigent --version
更新：
omni upgrade # 检查并升级到最新版本（等当前会话结束）
omni upgrade --check # 仅检查，不升级
💡 安装后 CLI 有两个名字
omnigent和短别名omni，完全等价。
核心用法
启动会话
omni
# 或
omnigent
首次启动时自动检测环境中的凭证（ANTHROPIC_API_KEY、OPENAI_API_KEY，或已登录的 claude/codex CLI），引导选择模型，随即进入会话。
同时本地会启动 Web UI：http://localhost:6767，在浏览器或手机浏览器打开同样的会话界面。
运行单个 Agent（YAML 定义）
omni run agent.yaml
agent.yaml 示例：
name: my-agent
harness: claude # 可选：claude / codex / cursor / pi / hermes
model: claude-sonnet-4
system: "你是一个代码审查员..."
tools:
allowed: [Read, Edit, Bash]
blocked: [Delete, Write]
多 Agent 协作
在同一 Omni 会话里，通过对话指令让多个 Agent 同时存在：
> 叫 codex agent 来审查一下这个 PR
> 让 claude 继续做前端的重构
支持的 Agent 类型（通过 npm 安装各自的 CLI）：
- claude — Anthropic Claude Code
- codex — OpenAI Codex CLI
- cursor — Cursor Agent
- pi — Pi Agent
- hermes — 自定义 Hermes Agent
- 自定义 YAML — 用 omnigent run agent.yaml
策略（Policy）管控
创建策略文件控制 Agent 行为，例如 policy.yaml：
- name: no-destructive
rules:
- action: block
tool: Delete
- action: pause # 危险操作前先暂停等你确认
command: rm -rf
- action: cap
spend: 10 # 预算上限 $10
策略可作用于：全局、单个 Agent、单次对话。
云沙箱模式
不耗本地资源，将 Agent 跑在云端：
omni run --sandbox modal agent.yaml # Modal
omni run --sandbox e2b agent.yaml # E2B
omni run --sandbox daytona agent.yaml # Daytona
omni run --sandbox kubernetes agent.yaml
首次运行自动拉取对应云平台的沙箱镜像，无需手动配置。
Web UI / 桌面应用
Web UI：http://localhost:6767（随 omni 自动启动）。
macOS 桌面应用（含通知、Dock badge）：
# 下载：https://omnigent.ai/download/mac
# 自动打开与 Web UI 相同的界面
典型适用场景
| 场景 | 为什么用 Omnigent |
|---|---|
| 团队共享 Agent | 策略控制 + 实时协作，团队成员围观同一个 Agent 跑任务 |
| 复杂任务多 Agent 协作 | 让 Claude 做推理、Codex 写测试、Cursor 做界面，同时在一个会话里 |
| 本地算力不足 | 用 --sandbox modal/e2b 把 Agent 跑在云端 |
| 跨设备继续任务 | 手机上继续笔记本里跑了 30 分钟的 Agent 会话 |
| 企业 Agent 治理 | Policy 控制 Agent 可访问的工具和预算，防止误操作 |
坑与注意
- Python 3.12 强制要求：其他版本不兼容，必须精确版本。系统自带 Python 可能低于此版本。
- Windows 功能缺失：原生 Windows 支持部分功能不可用（tmux 终端包装、bwrap 沙箱），建议使用 WSL2 或 Linux/macOS。
- Node.js 22 LTS 必需：Claude/Codex/OpenCode/Pi 这些 Agent 的 CLI 均通过 npm 安装，Node 版本低了装不上。
- bubblewrap 仅 Linux：
apt install bubblewrap后 omnigent 的沙箱终端才正常工作；macOS 用 seatbelt 无需额外操作。 - tmux 必需：所有原生终端包装依赖 tmux，macOS 上
brew install tmux。 - 国内网络：npm 安装 Claude/Codex CLI 可能遇到网络问题，建议配置 npm 镜像。
- API Key 需提前配置：首次运行会检测
ANTHROPIC_API_KEY等环境变量，没有的话需要在支持的平台上登录各自的 CLI（claude登录 Anthropic 等）。
与同类对比
| 框架 | 定位 | 多 Agent | 策略治理 | 云沙箱 | 协作 |
|---|---|---|---|---|---|
| Omnigent | Agent 元编排层 | ✅ 混合编排 | ✅ 完善 | ✅ 多平台 | ✅ 实时 |
| LangChain Agents | LLM 工具调用框架 | 有限 | ❌ | ❌ | ❌ |
| AutoGPT | 单体 Agent | ❌ | 基础 | ❌ | ❌ |
| CrewAI | 多 Agent 协作 | ✅ | 有限 | ❌ | ❌ |
| LangGraph | DAG 流程编排 | 有限 | ❌ | ❌ | ❌ |
| Claude Code | 单体 Agent | ❌ | ❌ | ❌ | ❌ |
Omnigent 的核心差异：不是一个新 Agent，是一个 Agent 管理层——不替代 Claude Code 或 Codex，而是在它们之上加了一层编排、治理、协作层，适合管理多 Agent 协同和团队共享场景。
一句话推荐结论
如果你已经同时在用多个 AI 编程 Agent（Claude Code + Cursor + Codex），装 Omnigent 就是给它们装上统一的"指挥中心"——策略管控、多 Agent 协同、跨设备继续、云端跑大任务，一个工具全搞定。
周增 +343 | Stars 7067 | 语言 Python | 许可 Apache-2.0 | 成熟度 production