omnigent-ai/omnigent

二〇二六年八月二十六日·★ 3,638·⑂ 408·Python·Apache-2.0 · GitHub 原仓库

摘要

Omnigent 是一个开源AI agent框架与元编排工具，为Claude Code、Codex、Cursor、Pi及自定义agent提供统一编排层。它支持从手机等任何设备使用agent、在单一会话中监督多个agent、使用任意模型（API密钥或订阅）、实时协作、在Modal等云沙箱中运行agent，以及通过策略实施治理（如限制shell命令或花费上限）。安装需Python 3.12+，支持macOS桌面应用和Docker部署。

Omnigent

面向所有 AI agent 的开源 AI agent 框架与元编排工具。

Omnigent 是一个开源的 AI agent 框架与元编排工具，为 Claude Code、Codex、Cursor、Pi 以及你自己编写的 agent 提供统一的编排层：无需重写即可切换或组合 harness，实施策略与沙箱隔离，并支持从任何设备实时协作。

omnigent.ai · ⬇️ 下载 macOS 桌面应用

为什么选择 Omnigent？

Omnigent 让你能够：

📱 从任何设备（包括手机）使用 agent。 会话跟随你：在终端开始，在浏览器继续，在手机上接续。消息、子 agent、终端和文件保持同步。
🤖 监督多个 agent。 在同一个会话中同时使用 Claude Code、Codex、Pi 和自定义 agent（以 YAML 定义）。让一个 agent 审查另一个的工作，或将任务拆分给各自擅长的不同 agent。
🔌 使用任何模型。 第一方 API 密钥、Claude/ChatGPT 订阅，或任何兼容的网关。全部作为一等公民支持。
🤝 协作。 共享一个会话，让队友可以与你的 agent 聊天并实时观看其工作，在你的机器上共同驾驶，或 fork 对话以自行继续。
☁️ 在云沙箱中运行 agent。 无需笔记本电脑：在可丢弃的 Modal、Daytona 或 Islo 沙箱中运行会话，从 CLI 启动或由服务器按会话预配（托管主机）。
🛡️ 治理你的 agent。 创建策略，在风险操作前暂停等待你的批准，限制花费，或限制 agent 可使用的工具。它们可应用于整个服务器、单个 agent 或单个聊天。

快速开始

1. 安装

一条命令即可安装 Omnigent 及其所有依赖：

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

Omnigent 需要 Python 3.12+。安装 omnigent 包：

uv tool install omnigent        # 或：pip install "omnigent"

或通过 Homebrew：

brew install omnigent-ai/tap/omnigent

或直接从仓库安装：

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

uv（必需）。https://docs.astral.sh/uv/getting-started/installation/ 安装程序会为你设置它。
git（必需）。
Node.js 22 LTS 或更新版本，附带 npm，用于 Claude、Codex 和 Pi 编码 harness。omnigent run 会安装你选择的 harness CLI。 https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
tmux，原生 omnigent claude / omnigent codex 包装器所需（brew install tmux / apt install tmux；安装程序会为你安装它）。
bubblewrap（bwrap），仅限 Linux。原生 omnigent claude / omnigent codex 和 pi harness 会将每个 agent 终端包装在 bwrap 操作系统沙箱中；在 Linux 上这种隔离是强制性的，因此缺少 bwrap 二进制文件会导致这些终端无法启动（apt install bubblewrap；安装程序会为你安装它）。macOS 使用内置的 seatbelt 沙箱，无需额外操作。
Databricks（可选）。要使用 Databricks 工作区作为模型提供者，请安装带有 databricks 扩展的 Omnigent：uv tool install "omnigent[databricks]" — 或通过 ... | sh -s -- --extra databricks 传递给引导安装程序。登录工作区还需要 Databricks CLI。

当 PyPI 上有新版本时，Omnigent 会显示一行提示（每个版本一次），指向此处。要更新：

omni upgrade            # 检测你的安装方式，排空并停止本地服务器，然后运行匹配的升级命令
omni upgrade --check    # 仅报告是否有新版本可用

omni upgrade 会等待进行中的 agent 会话完成后再停止本地服务器（传递 --force 可立即停止它们）；下一个 omni 命令会以新版本重新启动服务器。源码检出通过 git pull 更新。通过 OMNIGENT_NO_UPDATE_CHECK=1 静默提示。

检查会查询你配置的包索引 — 遵循 UV_INDEX_URL / PIP_INDEX_URL 以及你的 uv.toml / pip.conf（默认 PyPI），因此私有镜像开箱即用；如有需要，可通过 OMNIGENT_INDEX_URL 覆盖。

2. 启动你的第一个 agent

omnigent 会与你一起选择一个模型，并在你的终端中启动一个会话。它还会在 http://localhost:6767 启动一个本地 Web UI，在浏览器或你网络上的手机（步骤 4）中显示相同的会话。桌面应用将相同的 UI 包装在原生窗口中，并添加操作系统通知和 dock 徽章 — 在 macOS 上下载。

[!NOTE] 安装会在你的 PATH 上放置两个指向同一 CLI 的名称：omnigent 和更短的 omni。它们可以互换使用。

[!TIP] 首次运行时，Omnigent 会检测你环境中已有的模型凭据（ANTHROPIC_API_KEY / OPENAI_API_KEY，或你已登录的 claude / codex CLI），并提供一个作为默认值。

omnigent

或启动特定的 agent 运行时，或你自己的 agent：

omnigent claude                      # Claude Code，在你的团队可以加入的会话中
omnigent codex                       # Codex
omnigent run path/to/agent.yaml      # 你自己的 agent（参见“编写你自己的 agent”）

🐙 Polly 和 🟠🔵 Debby

仓库中附带两个示例 agent，它们很适合作为首次会话：

omnigent run examples/polly/
omnigent run examples/debby/

# 在不同的 harness 上运行编排器（子 agent 保留自己的）：
omnigent run examples/polly/ --harness pi
omnigent run examples/debby/ --harness openai-agents
omnigent run examples/polly/ --harness cursor  # Cursor CLI（需要 cursor-agent + CURSOR_API_KEY）

🐙 Polly 是一个多 agent 编码编排器，她自己不写代码。她是技术负责人：她制定计划，将工作委托给并行 git worktree 中的编码子 agent（Claude Code、Codex 或 Pi），然后将每个 diff 路由给与编写者不同供应商的审查者。你来合并。

🟠🔵 Debby 是一个双头头脑风暴伙伴，一头是 Claude，一头是 GPT。你提出的每个问题都会发送给两个头，她会将两个答案并排展示。输入 /debate，两个头会互相批评几轮，然后收敛。（她需要同时拥有 Claude 和 OpenAI 凭据；参见步骤 3。）

更喜欢浏览器？ 启动一个服务器并将你的机器注册为主机：

omnigent server start   # 在后台启动本地服务器和 Web UI
omnigent host           # （单独的终端）将此机器注册为主机

在 Web UI 中，点击 New Chat，选择你的机器，然后开始。使用 omnigent server status 检查状态；使用 omnigent stop 停止所有内容。

3. 选择与切换模型

omnigent setup

添加凭据、设置默认值或删除一个，按 agent 分组。Omnigent 支持四种凭据：

	类型	说明
🔑	API 密钥	Anthropic、OpenAI 及类似提供者的第一方供应商密钥
🎟️	订阅	通过官方 `claude` / `codex` CLI 的 Claude Pro/Max 或 ChatGPT 计划
🌐	网关	任何兼容 OpenAI 或 Anthropic 的 `base_url` 和密钥（OpenRouter、LiteLLM、Ollama、vLLM、Azure）
🧱	Databricks	一个 Databricks 工作区配置文件（需要 `databricks` 扩展）

默认值是按 agent 设置的，因此 Claude 默认值和 Codex 默认值可以共存。你也可以在会话中途使用 /model 命令切换模型。

当你添加 Gateway 凭据时，omnigent setup 会询问 base URL 和密钥。base URL 取决于你将其指向哪个 agent：

提供者	用于	Base URL	密钥
OpenRouter	Claude Code	`https://openrouter.ai/api`	你的 OpenRouter 密钥（`sk-or-…`）
OpenRouter	Codex / OpenAI agent	`https://openrouter.ai/api/v1`	你的 OpenRouter 密钥（`sk-or-…`）
Ollama（本地）	Codex / OpenAI agent	`http://localhost:11434/v1`	任意值（Ollama 忽略它）

对于 Claude Code，指向 OpenRouter 的 Anthropic 兼容端点（…/api，不是 …/api/v1）。对于 Codex 和 OpenAI-agents harness，使用 OpenAI 兼容的 …/api/v1。

4. 部署服务器（并从你的手机📱使用）

在具有稳定 URL 的服务器上运行 Omnigent（deploy/README.md 是完整指南），你的会话就可以从任何地方访问，包括你的手机。Web UI 专为移动端设计，因此你可以获得相同的聊天、子 agent、终端和文件，并与你的笔记本电脑同步。

一个 docker compose up 即可在你拥有的任何主机（VPS、家庭服务器）上运行服务器；Render 一键部署；Fly.io、Railway、Hugging Face Spaces 和 Modal 也支持。服务器还可以按会话预配云沙箱（托管主机），因此无需笔记本电脑保持在线。完整的目标列表、数据库选项和沙箱设置位于 deploy/README.md。

服务器启动后，登录并将你的笔记本电脑注册为主机：

omnigent login https://your-host    # 登录一次；run / attach / host 重用令牌
omnigent host  https://your-host    # 新会话现在可以在此机器上运行

[!TIP] 在你自己的网络上，你不需要部署。在手机上打开你机器的局域网地址（例如 http://192.168.x.x:6767）。

5. 与你的团队协作

Omnigent 支持多用户账户，由一个环境变量控制：

OMNIGENT_AUTH_ENABLED=1 omnigent server start

步骤 4 中的 Docker 部署会为你启用它（OMNIGENT_AUTH_ENABLED 在那里默认为 1）。

邀请你的队友

打开 Web UI（本地为 http://localhost:6767，或你的主机 URL），以 admin 身份登录；首次运行会打印密码并将其保存在本地。然后打开 Admin → Members → Invite 创建一个一次性邀请链接，无需邮件服务器。发送链接；你的队友打开它，设置密码，然后他们就加入了。注册仅限邀请。

[!NOTE] 队友需要能够访问服务器。本地服务器只能在你自己的网络上访问；对于网络外的任何人，请部署一个始终在线的主机（参见步骤 4）。

一起编码

共享实时会话。 在 Web UI 中点击 Share 并发送链接；队友可以实时观看你的 agent 工作并与之聊天。
共同驾驶。 一个队友附加到你正在运行的会话；他们的消息在你的机器上执行。非常适合结对编程或在调查过程中将键盘交给领域专家。
```
omnigent attach <session_id>
```
Fork。 将对话克隆到你自己的机器上，并从 fork 点独立继续。
```
omnigent run --fork <session_id>
```

[!TIP] 希望你的团队使用他们已有的登录方式（Google、GitHub、Okta、Microsoft）登录？在部署的服务器上设置 OMNIGENT_OIDC_ISSUER 以及客户端 ID 和密钥，然后重启。完整指南、域名白名单和仅代理的 header 认证模式在 deploy/README.md#auth 中有介绍。

6. 使用策略治理你的 agent

策略决定 agent 可以做什么：运行 shell 命令、编辑文件、花费 token。它们检查每个操作，并允许、阻止或暂停以先询问你。

在 Web UI 中：打开会话的信息面板，浏览可用策略并切换其开关。
在聊天中：直接询问。"添加一个策略，在运行 shell 命令之前询问我。" agent 会为你设置。

想要适用于所有人或特定 agent 的默认值？在你的服务器配置或 agent 的 YAML 中定义它们：

policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # 在 shell / 文件写入前询问
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # 限制一个会话可以调用的工具数量
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # 硬性花费上限...
      ask_thresholds_usd: [3.00]   # ...以及途中的软性警告

策略在三个层级上叠加：服务器范围（管理员）、按 agent（开发者）和按会话（你），更严格的会话规则优先检查。花费上限和访问限制作为内置策略提供。

请参阅策略指南了解完整目录和信任模型。

编写你自己的 agent

一个 agent 是一个简短的 YAML 文件：你的 prompt、你的工具，以及监督者可以委托的可选辅助子 agent。你不必手动编写：agent 可以构建 agent，因此在任何 Omnigent 聊天中描述你想要的 agent，它就会为你生成文件。

name: my_agent
prompt: 你是一个乐于助人的数据分析师。

executor:
  harness: claude-sdk          # 或：codex, codex-native, claude-native, cursor, openai-agents, pi, antigravity

tools:
  # 一个本地 Python 函数（schema 从签名自动生成）
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  # 监督者可以委托的子 agent
  researcher:
    type: agent
    prompt: 搜索相关信息并总结。
    tools:
      word_count: inherit

使用以下命令运行它：

omnigent run path/to/my_agent.yaml

同一个文件可以声明子 agent 和审查者。更完整的示例，请参见 examples/polly/ 中的 Polly，以及 Agent YAML 规范了解完整 schema。

贡献

欢迎贡献。请参阅 CONTRIBUTING.md 了解如何设置环境、运行检查以及提交 pull request。

同时见于 gh-search:ai-agent、OSSInsight 全局趋势

译自 GitHub · 项目涌现 · 录于二〇二六年八月二十六日