Omnigent AI 智能体元框架详细部署教程

Omnigent 是一个开源的 AI 智能体元框架（meta-harness），它提供了一个统一的编排层，让您可以混合使用 Claude Code、Codex、Cursor、Pi 等多种 AI 编程助手，以及自定义智能体。它支持实时协作、跨设备访问和统一的策略管控，是团队或高级用户管理多个 AI 工具的利器。本教程将指导您完成部署。

📋 目录

  1. Omnigent 是什么
  2. 安装前准备
  3. 快速安装
  4. 首次启动与配置
  5. 核心功能与使用
  6. 团队协作与服务器部署
  7. 自定义智能体
  8. 更新与卸载
  9. 常见问题排查

Omnigent 是什么

Omnigent 是一个“元工具”，它不取代您的 AI 助手，而是将它们统一管理起来。

核心价值：

  • 统一界面与体验：通过一个终端命令或网页界面，启动和管理不同的 AI 编程助手。
  • 跨设备协作：会话状态同步，您可以在电脑上开始工作，在手机上继续。
  • 混合多智能体：在同一会话中让 Claude Code 和 Codex 协作，或让一个智能体审查另一个的工作。
  • 策略管控：为智能体设置成本上限、操作审批策略、沙箱隔离，实现治理。
  • 云沙箱运行：可将会话运行在 Modal、E2B、Kubernetes 等云端沙箱中，解放本地电脑。

安装前准备

系统要求

  • 操作系统：macOS、Linux (Ubuntu/Debian 推荐) 或 Windows (功能受限，建议使用 WSL2)。
  • Python 版本：3.12 或更新版本。
  • 包管理器：uv (推荐) 或 pip。
  • 依赖工具（部分为必需）：
    • git (必需)
    • Node.js 22 LTS 或更新 及 npm (用于运行编码助手 CLI)
    • tmux (必需，用于终端包装器)
    • bubblewrap (bwrap)：Linux 必需，用于沙箱隔离 (sudo apt install bubblewrap)
    • pnpm：可选，用于构建 Web UI

推荐使用一键安装脚本

官方提供了自动安装脚本，会检查并引导安装大部分依赖。执行以下命令：

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

如需安装额外集成（如 Databricks, Modal 沙箱），可以加上 --extra 参数：

1
2
# 安装 Databricks 和 Modal 支持
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra databricks,modal

对于 Windows 原生环境：无法使用上述脚本，请使用 uv 直接安装：

1
uv tool install --python 3.12 omnigent

快速安装

通过 uv 安装（推荐）

1
uv tool install omnigent        # 若需 extras: uv tool install "omnigent[databricks,modal]"

安装后，omnigent (和简称 omni) 命令即添加到 PATH。

通过 pip 安装

1
pip install "omnigent"          # 若需 extras: pip install "omnigent[databricks]"

通过 Homebrew 安装 (macOS)

1
brew install omnigent-ai/tap/omnigent

从源码安装（开发版）

1
uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

首次启动与配置

1. 启动第一个会话

安装后，在终端中输入：

1
omnigent

或启动特定智能体：

1
2
3
omnigent claude        # 启动 Claude Code
omnigent codex         # 启动 Codex
omnigent cursor        # 启动 Cursor

首次运行会检测您环境中的 API 密钥（如 ANTHROPIC_API_KEY, OPENAI_API_KEY），并引导您设置默认模型。

2. 配置模型与凭证

您可以使用 omnigent setup 命令管理凭证：

1
omnigent setup

该命令支持四种凭证类型：

  • API Key：直接输入 Anthropic/OpenAI 等厂商的密钥。
  • 订阅 (Subscription)：通过官方 claude 或 codex CLI 登录。
  • 网关 (Gateway)：配置 OpenRouter、Ollama 等兼容网关的 base_url 和密钥。
  • Databricks：如果安装了对应 extras，可配置 Databricks 工作区。

3. 在浏览器中使用

启动本地服务器：

1
omnigent start

然后打开浏览器访问 http://localhost:6767，您将看到一个与终端同步的 Web 界面，方便远程访问。

核心功能与使用

运行示例智能体

Omnigent 自带几个示例，可快速体验：

1
2
3
omnigent run examples/polly/           # 多智能体编码编排器
omnigent run examples/debby/           # 双头头脑风暴助手 (Claude + GPT)
omnigent run examples/deep-research/   # 带引用的深度研究智能体

切换模型

在终端会话中，输入 /model 命令可切换当前智能体使用的模型。或在启动时指定：

1
omnigent claude --model claude-3-5-sonnet-20241022

查看与管理会话

  • 列出当前所有会话：omnigent session list
  • 重新附着到一个会话：omnigent attach <session_id>
  • 停止一个会话：omnigent stop <session_id>

团队协作与服务器部署

部署一个团队服务器

您可以在一台有公网 IP 的服务器上部署 Omnigent，团队成员即可远程访问。

使用 Docker Compose 快速部署（推荐）：
项目根目录下的 deploy/ 文件夹包含 Docker 配置。在服务器上执行：

1
2
3
git clone https://github.com/omnigent-ai/omnigent.git
cd omnigent/deploy
docker compose up -d

服务启动后，访问 http://<your-server-ip>:6767。

其他部署目标：Omnigent 支持一键部署到 Render、Railway、Fly.io、Hugging Face Spaces 等平台，详细配置请参考 deploy/README.md。

用户管理与邀请

  • 设置环境变量启用认证：OMNIGENT_AUTH_ENABLED=1
  • 首次访问时，使用默认 admin 账号登录（密码在启动时打印）。
  • 在 Web 界面的 Admin → Members → Invite 中创建邀请链接，分发给团队成员。

实时协作

  • 共享会话：在 Web 界面点击会话的 Share 按钮，生成链接分享给队友，他们可以观看和与智能体聊天。
  • Co-drive (共驾)：队友可以使用 omnigent attach <session_id> 命令直接附着到您正在运行的会话上，共同操作。
  • Fork (复刻)：队友可用 omnigent run --fork <session_id> 在自己的机器上从某个会话点创建一个独立的分支继续工作。

自定义智能体

您可以通过编写简单的 YAML 文件来定义自己的智能体。

一个最小示例 (my_agent.yaml)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
name: my_analyst
prompt: You are a data analyst. Answer questions based on provided data.

executor:
  harness: claude-sdk          # 可以是 claude-native, codex, cursor 等

tools:
  # 使用本地 Python 函数作为工具
  calculate_mean:
    type: function
    callable: mymodule.stats.calculate_mean

  # 使用 MCP 服务器作为工具
  web_search:
    type: mcp
    url: https://example.com/mcp-search

运行您的智能体：

1
omnigent run path/to/my_agent.yaml

更复杂的智能体可以参考 examples/polly/ 中的示例，它包含了子智能体和审查者的定义。您也可以在 Omnigent 聊天中直接用自然语言描述想要的智能体，让它帮助生成 YAML 文件。

更新与卸载

更新 Omnigent

1
2
omni upgrade            # 自动检测安装方式并更新
omni upgrade --check    # 仅检查是否有新版本

卸载 Omnigent

1
2
3
omnigent uninstall               # 预览将删除的内容
omnigent uninstall --yes         # 执行清理（保留数据）
omnigent uninstall --purge --yes # 彻底删除所有状态和数据

如果 omnigent 命令不可用，可以使用独立脚本：

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

常见问题排查

问题：Linux 下启动智能体失败，提示 bwrap 未找到。

  • 解决：bubblewrap 是 Linux 下沙箱隔离的必需组件。执行 sudo apt install bubblewrap (Debian/Ubuntu) 或 sudo yum install bubblewrap (RHEL/Fedora) 安装。

问题：tmux 相关错误。

  • 解决：Omnigent 依赖 tmux 来管理终端会话。执行 brew install tmux (macOS) 或 sudo apt install tmux (Linux) 安装。

问题：uv 命令未找到。

  • 解决：uv 是推荐的 Python 包安装工具。请访问 Astral 官网 安装。

问题：在 Windows 上某些功能不可用。

  • 解决：Windows 原生环境不支持 tmux 包装器和 bwrap 沙箱。建议在 WSL2 (Windows Subsystem for Linux) 中运行 Omnigent 以获得完整功能。

通过以上步骤，您应已成功部署并开始使用 Omnigent。它是一个强大的智能体编排平台，尤其适合需要管理多个 AI 工具或进行团队协作的场景。如需深入了解高级配置（如策略编写、云沙箱集成等），建议仔细阅读项目中的 deploy/README.md 和 docs/ 目录下的详细文档。