omnigent-ai--omnigent/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Omnigent

面向所有 AI 智能体的开源元 harness（meta-harness）。

Omnigent 是一款开源 元 harness（meta-harness），为 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 以及你自写的智能体提供统一的编排层：无需重写即可切换或组合 harness，执行策略与沙箱隔离，并从任意设备——终端、浏览器、手机或原生桌面应用——实时协作。

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

---

为什么选择 Omnigent？

Omnigent 让你能够：

• 📱 在任意设备上使用智能体，包括手机。 会话 随你而行：在终端开始，在浏览器继续，在手机上接着做。消息、子智能体、终端和文件保持同步。

• 🤖 监管多个智能体。 在同一会话中混合使用 Claude Code、Codex、Cursor、OpenCode、 Hermes、Pi 以及自定义智能体（在 YAML 中定义）。让一个智能体审查另一个的工作，或将任务拆分给各有所长的多个智能体。

• 🔌 使用任意模型。 第一方 API 密钥、Claude/ChatGPT 订阅 或任意兼容网关，均为一等公民。

• 🤝 协作。 共享会话，让队友与你的智能体 聊天、实时观看其工作、在你的机器上共同驾驶，或分叉对话后在各自环境中继续。

• ☁️ 在云沙箱中运行智能体。 无需笔记本电脑：在一次性 Modal, Daytona, Islo, E2B, CoreWeave, Kubernetes, OpenShell, Boxlite, 或 Databricks 沙箱中运行会话，可通过 CLI 启动，或由服务器按会话配置（托管主机 managed hosts）。

• 🛡️ 治理你的智能体。 创建 策略，在危险操作执行前暂停等待你批准、 限制支出，或限制智能体可使用的工具。 策略可作用于整个服务器、单个智能体或单条聊天。

---

快速入门

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        # or: 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，用于通过 npm 安装的 coding harness（Claude、Codex、OpenCode、Pi）。omnigent run 会安装你选择的 harness CLI。 https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
• Kiro CLI（可选），用于 omnigent kiro：使用 curl -fsSL https://cli.kiro.dev/install | bash 安装，然后用 Kiro 登录。 Kiro 工具审批可在嵌入式 Terminal 中响应；支持的一次性审批也会以 Chat 卡片形式出现。详见 docs/kiro-native-elicitation.md。
• tmux，原生 omnigent <harness> 终端包装器 （claude、codex、cursor、hermes、kiro、pi） 所需（brew install tmux / apt install tmux；安装程序可 为你安装）。
• bubblewrap（bwrap），仅限 Linux。原生 omnigent <harness> 终端包装器与 pi harness 将每个智能体 终端包裹在 bwrap 操作系统沙箱中；在 Linux 上该隔离为强制要求，因此缺少 bwrap 二进制文件会导致这些终端无法启动 （apt install bubblewrap；安装程序可为你安装）。macOS 使用内置的 seatbelt 沙箱，无需额外组件。
• Databricks（可选）。若要将 Databricks 工作区用作模型 提供方，请安装带 databricks extra 的 Omnigent： uv tool install "omnigent[databricks]" —— 或在引导 安装程序中传入 ... | sh -s -- --extra databricks。登录 工作区还需使用 Databricks CLI.

Windows（原生）

Omnigent 可在 Windows 上以降级模式原生运行。install_oss.sh 引导程序仅支持 POSIX，因此请直接用 uv 安装：

uv tool install --python 3.12 omnigent
# or from the repo:
uv tool install --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

Windows 上可用：omnigent server、Web UI，以及基于 SDK 的 harness（omnigent run <agent.yaml> 配合 claude-sdk / cursor / codex harness）。智能体在 Windows Job Object 下运行，以 containment 进程树。

Windows 上不可用（这些功能请使用 Linux/macOS 或 WSL）：

• 原生 omnigent claude / omnigent codex / omnigent cursor tmux/PTY 终端包装器（请改用 SDK harness 或 Web UI）；
• bwrap/seatbelt 文件系统与网络沙箱隔离及 L7 出口代理 —— Job Object 后端可 containment 进程树并强制执行资源限制，但不会隔离文件系统或网络。

更新到新版本

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

omni upgrade            # detects how you installed, drains & stops the local
                        # server, then runs the matching upgrade command
omni upgrade --check    # just report whether a newer release is available

omni upgrade 会在停止本地服务器前等待进行中的智能体会话结束（传入 --force 可立即停止）；下一次执行 omni 命令 即可在新版本上重启服务器。源码检出请改用 git pull 更新。使用 OMNIGENT_NO_UPDATE_CHECK=1 可关闭该提示。

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

2. 启动你的第一个智能体

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 运行时：

omnigent claude                      # Claude Code, in a session your team can join
omnigent codex                       # Codex
omnigent cursor                      # Cursor
omnigent opencode                    # OpenCode
omnigent hermes                      # Hermes Agent (Nous Research)
omnigent pi                          # Pi

🐙 Polly 与 🟠🔵 Debby

仓库自带两个示例 agent，非常适合作为首次体验：

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

# ...or on a different harness (sub-agents keep their own):
omnigent run examples/polly/ --harness <harness>
omnigent run examples/debby/ --harness <harness>

🐙 Polly 是一位多 agent 编程编排者，她自己不写代码。她担任技术负责人：负责规划，将工作委派给并行 git worktree 中的编程子 agent（Claude Code、Codex 或 Pi），然后把每个 diff 交给与编写者不同厂商的审查者审核。由你来合并。

🟠🔵 Debby 是一位拥有两个「脑袋」的头脑风暴伙伴，一个是 Claude，一个是 GPT。你提出的每个问题都会同时发给两个脑袋，她会将两个答案并排展示。输入 /debate，两个脑袋会先互相评判几轮，再达成一致。（她需要 Claude 和 OpenAI 两种凭据；参见第 3 步。）

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

omnigent server start   # start the local server and web UI in the background
omnigent host           # (separate terminal) register this machine as a host

在 Web UI 中点击 New Chat，选择你的机器，即可开始。使用 omnigent server status 查看状态；使用 omnigent stop 停止所有服务。

3. 选择与切换模型

omnigent setup

按 agent 分组添加凭据、设置默认项或移除凭据。Omnigent 支持四种类型的凭据：

	类型	说明
🔑	API key	Anthropic、OpenAI 等官方厂商提供的 API 密钥
🎟️	Subscription（订阅）	Claude Pro/Max 或 ChatGPT 套餐，通过官方 claude / codex CLI
🌐	Gateway（网关）	任何 OpenAI 或 Anthropic 兼容的 base_url 和密钥（OpenRouter、LiteLLM、Ollama、vLLM、Azure）
🧱	Databricks	Databricks 工作区配置文件（需要 databricks extra）

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

Gateway 基础 URL（OpenRouter、Ollama）

添加 Gateway 凭据时，omnigent setup 会要求输入基础 URL 和密钥。基础 URL 取决于你将其指向哪个 agent：

提供商	适用于	基础 URL	密钥
OpenRouter	Claude Code	https://openrouter.ai/api	你的 OpenRouter 密钥（sk-or-…）
OpenRouter	Codex / OpenAI agents	https://openrouter.ai/api/v1	你的 OpenRouter 密钥（sk-or-…）
Ollama（本地）	Codex / OpenAI agents	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 和 Railway 支持一键部署；Fly.io、Hugging Face Spaces、Modal、Cloudflare（serverless，缩容至零）以及 Databricks Apps（由 Lakebase Postgres 和 Unity Catalog Volumes 支持）也有涵盖——Cloudflare quick tunnel（公开）或 Tailscale（私有）可让你在不部署的情况下，从自己的笔记本电脑访问正在运行的服务器。服务器还可以为每个会话配置云端沙箱（managed hosts），因此无需笔记本电脑保持在线。完整的目标列表、数据库选项和沙箱配置请参阅 deploy/README.md.

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

omnigent login https://your-host    # sign in once; run / attach / host reuse the token
omnigent host  https://your-host    # new sessions can now run on this machine

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 工作并与之聊天。

• 共同操作（Co-drive）。 队友会协同接入你正在运行的会话；他们的消息在你的机器上执行。非常适合结对编程，或在调查中途将键盘交给领域专家。

  omnigent attach <session_id>
  

• 分叉（Fork）。 将对话克隆到你自己的机器上，从分叉点独立继续。

  omnigent run --fork <session_id>
  

Tip

希望团队使用已有的登录方式（Google、GitHub、Okta、Microsoft）登录？在已部署的服务器上设置 OMNIGENT_OIDC_ISSUER 以及 client ID 和 secret，然后重启。完整操作指南、域名白名单以及仅限代理的 header 认证模式请参阅 deploy/README.md#auth.

6. 使用策略管控 agent

策略（Policies） 决定 agent 可以执行哪些操作：运行 shell 命令、编辑文件、消耗 token。策略会检查每一项操作，并选择允许、阻止，或暂停并先征求你的同意。

• 在 Web UI 中：打开会话的信息面板，浏览可用策略并开启或关闭。
• 在聊天中：直接提问。「添加一项策略，在运行 shell 命令前先征求我的同意。」 agent 会为你配置。

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

policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # ask before shell / file writes
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # cap how many tools one session can call
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # hard spend cap...
      ask_thresholds_usd: [3.00]   # ...with a soft warning on the way

策略分三层叠加：全服级（admin）、按 Agent（developer）与按会话（you），更严格的会话规则会优先校验。支出上限与访问限制以内置能力（builtins）提供。

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

---

编写你自己的 Agent

Agent 是一个简短的 YAML 文件：包含你的提示词（prompt）与工具——本地 Python 函数、MCP 服务器，以及 supervisor 可委派任务的子 Agent（sub-agents）。你不必亲手编写：Agent 可以构建 Agent，因此在任意 Omnigent 对话中描述你想要的 Agent，它就会为你生成该文件。

name: my_agent
prompt: You are a helpful data analyst.

executor:
  harness: claude-sdk          # or: claude-native, codex, codex-native, cursor,
                               # cursor-native, hermes, hermes-native, opencode,
                               # pi, pi-native, openai-agents

tools:
  # A local Python function (schema auto-generated from the signature)
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  # Tools from an MCP server (a local command, or a remote URL)
  docs:
    type: mcp
    url: https://example.com/mcp

  # A sub-agent the supervisor can delegate to
  researcher:
    type: agent
    prompt: Search for relevant information and summarize it.
    tools:
      word_count: inherit

运行方式：

omnigent run path/to/my_agent.yaml

同一文件还可声明子 Agent 与 reviewer。更完整的示例请参阅 Polly：examples/polly/,，以及Agent YAML 规范)了解完整 schema。

---

参与贡献

欢迎贡献。环境搭建、运行检查与提交 Pull Request 的方式请参阅 CONTRIBUTING.md。

要新增或修改对 harness（Claude、Codex、Cursor、OpenCode、Hermes、Pi 等）的支持？请运行 harness test bench，对照实际行为检查其能力矩阵（capability matrix）。

贡献者

感谢所有出色的贡献者！