> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/omnigent-ai/omnigent) · [上游 README](https://github.com/omnigent-ai/omnigent/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# Omnigent ### 面向所有 AI 智能体的开源元 harness（meta-harness）。 Omnigent 是一款开源 **元 harness（meta-harness）**，为 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 以及你自写的智能体提供统一的编排层：无需重写即可切换或组合 harness，执行策略与沙箱隔离，并从任意设备——终端、浏览器、手机或原生桌面应用——实时协作。 [![PyPI version](https://img.shields.io/pypi/v/omnigent.svg)](https://pypi.org/project/omnigent/) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/omnigent-ai/omnigent/blob/main/LICENSE) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/omnigent) ![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg) [omnigent.ai](https://omnigent.ai) · **[⬇️ 下载 macOS 桌面应用](https://omnigent.ai/download/mac)**

Omnigent 桌面应用：新建会话，侧边栏中显示已固定和按项目分组的会话

--- ## 为什么选择 Omnigent？ Omnigent 让你能够： - **📱 在任意设备上使用智能体，包括手机。** 会话 随你而行：在终端开始，在浏览器继续，在手机上接着做。消息、子智能体、终端和文件保持同步。 - **🤖 监管多个智能体。** 在同一会话中混合使用 Claude Code、Codex、Cursor、OpenCode、 Hermes、Pi 以及自定义智能体（在 YAML 中定义）。让一个智能体审查另一个的工作，或将任务拆分给各有所长的多个智能体。 - **🔌 使用任意模型。** 第一方 API 密钥、Claude/ChatGPT 订阅 或任意兼容网关，均为一等公民。 - **🤝 协作。** 共享会话，让队友与你的智能体 聊天、实时观看其工作、在你的机器上共同驾驶，或分叉对话后在各自环境中继续。 - **☁️ 在云沙箱中运行智能体。** 无需笔记本电脑：在一次性 [Modal](https://modal.com), [Daytona](https://www.daytona.io), [Islo](https://islo.dev), [E2B](https://e2b.dev), [CoreWeave](https://docs.coreweave.com/products/sandboxes), [Kubernetes](https://kubernetes.io), [OpenShell](https://github.com/NVIDIA/OpenShell), [Boxlite](https://github.com/boxlite-ai/boxlite), 或 [Databricks](https://www.databricks.com) 沙箱中运行会话，可通过 CLI 启动，或由服务器按会话配置（*托管主机 managed hosts*）。 - **🛡️ 治理你的智能体。** 创建 [策略](#6-govern-your-agents-with-policies)，在危险操作执行前暂停等待你批准、 限制支出，或限制智能体可使用的工具。 策略可作用于整个服务器、单个智能体或单条聊天。 --- ## 快速入门 ### 1. 安装 一条命令即可安装 Omnigent 及其所需的一切： ```bash curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh ```
想手动安装？ Omnigent 需要 **Python 3.12+**。安装 `omnigent` 包： ```bash uv tool install omnigent # or: pip install "omnigent" ``` 或使用 [Homebrew](https://github.com/omnigent-ai/homebrew-tap): ```bash brew install omnigent-ai/tap/omnigent ``` 或直接从仓库安装： ```bash 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 ` 终端包装器 （`claude`、`codex`、`cursor`、`hermes`、`kiro`、`pi`） 所需（`brew install tmux` / `apt install tmux`；安装程序可 为你安装）。 - **`bubblewrap`**（`bwrap`），**仅限 Linux**。原生 `omnigent ` 终端包装器与 `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](https://docs.databricks.com/aws/en/dev-tools/cli/install).
Windows（原生） Omnigent 可在 Windows 上以降级模式原生运行。`install_oss.sh` 引导程序仅支持 POSIX，因此请直接用 `uv` 安装： ```powershell 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 ` 配合 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 会显示一行提示（每个版本一次）并指向此处。更新方法： ```bash 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）。 [桌面应用](https://omnigent.ai/docs/interact/desktop) 将同一 UI 封装在原生窗口中，并提供操作系统通知（可配置提示音）和 Dock 角标 —— [下载 macOS 版](https://omnigent.ai/download/mac). > [!NOTE] > 安装后 PATH 上会有同一 CLI 的两个名称：`omnigent` 和 > 更短的 `omni`。二者可互换使用。 > [!TIP] > 首次运行时，Omnigent 会读取你环境中已有的模型凭据（已登录的 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`，或 `claude` / `codex` CLI），并提供一个作为默认选项。 ```bash omnigent ``` 或启动特定的 agent 运行时： ```bash 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，非常适合作为首次体验： ```bash omnigent run examples/polly/ omnigent run examples/debby/ # ...or on a different harness (sub-agents keep their own): omnigent run examples/polly/ --harness omnigent run examples/debby/ --harness ``` **🐙 Polly** 是一位多 agent 编程编排者，她自己不写代码。她担任技术负责人：负责规划，将工作委派给并行 git worktree 中的编程子 agent（Claude Code、Codex 或 Pi），然后把每个 diff 交给与编写者不同厂商的审查者审核。由你来合并。 **🟠🔵 Debby** 是一位拥有两个「脑袋」的头脑风暴伙伴，一个是 Claude，一个是 GPT。你提出的每个问题都会同时发给两个脑袋，她会将两个答案并排展示。输入 `/debate`，两个脑袋会先互相评判几轮，再达成一致。（她需要 Claude 和 OpenAI 两种凭据；参见第 3 步。） **更喜欢用浏览器？** 启动服务器并将你的机器注册为主机： ```bash 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. 选择与切换模型 ```bash 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`](https://github.com/omnigent-ai/omnigent/blob/main/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`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md). 服务器启动后，登录并将你的笔记本电脑注册为主机： ```bash 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 支持**多用户账户**，通过一个环境变量控制： ```bash OMNIGENT_AUTH_ENABLED=1 omnigent server start ``` **[第 4 步](#4-deploy-a-server-and-use-it-from-your-phone)中的 Docker 部署会为你启用该功能**（其中 `OMNIGENT_AUTH_ENABLED` 默认为 `1`）。 #### 邀请队友 打开 Web UI（本地使用 `http://localhost:6767`，或使用主机的 URL），以 `admin` 身份登录；首次运行会打印密码并保存在本地。然后打开 **Admin → Members → Invite** 创建一次性邀请链接，无需邮件服务器。将链接发送出去；队友打开链接、设置密码后即可加入。注册仅限邀请。 > [!NOTE] > 队友需要能够访问服务器。本地服务器仅在你的网络内可访问；对于网络外的用户，请部署一个常驻主机（参见[第 4 步](#4-deploy-a-server-and-use-it-from-your-phone)）。 #### 共同编程 - **共享实时会话。** 在 Web UI 中点击 **Share** 并发送链接；队友可以实时观看你的 agent 工作并与之聊天。 - **共同操作（Co-drive）。** 队友会协同接入你正在运行的会话；他们的消息在**你的**机器上执行。非常适合结对编程，或在调查中途将键盘交给领域专家。 ```bash omnigent attach ``` - **分叉（Fork）。** 将对话克隆到你自己的机器上，从分叉点独立继续。 ```bash omnigent run --fork ``` > [!TIP] > 希望团队使用已有的登录方式（**Google、GitHub、Okta、Microsoft**）登录？在已部署的服务器上设置 `OMNIGENT_OIDC_ISSUER` 以及 client ID 和 secret，然后重启。完整操作指南、域名白名单以及仅限代理的 `header` 认证模式请参阅 [`deploy/README.md#auth`](https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md#auth). ### 6. 使用策略管控 agent **策略（Policies）** 决定 agent 可以执行哪些操作：运行 shell 命令、编辑文件、消耗 token。策略会检查每一项操作，并选择允许、阻止，或暂停并先征求你的同意。 - **在 Web UI 中**：打开会话的信息面板，浏览可用策略并开启或关闭。 - **在聊天中**：直接提问。*「添加一项策略，在运行 shell 命令前先征求我的同意。」* agent 会为你配置。 想要适用于所有人或特定 agent 的默认策略？在服务器配置或 agent 的 YAML 中定义： ```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）提供。 完整目录与信任模型请参阅[策略指南](https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md)。 --- ## 编写你自己的 Agent Agent 是一个简短的 YAML 文件：包含你的提示词（prompt）与工具——本地 Python 函数、MCP 服务器，以及 supervisor 可委派任务的子 Agent（sub-agents）。你不必亲手编写：Agent 可以构建 Agent，因此在任意 Omnigent 对话中描述你想要的 Agent，它就会为你生成该文件。 ```yaml 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 ``` 运行方式： ```bash omnigent run path/to/my_agent.yaml ``` 同一文件还可声明子 Agent 与 reviewer。更完整的示例请参阅 Polly：[`examples/polly/`](https://github.com/omnigent-ai/omnigent/tree/main/examples/polly/),，以及[Agent YAML 规范](https://github.com/omnigent-ai/omnigent/blob/main/docs/AGENT_YAML_SPEC.md))了解完整 schema。 --- ## 参与贡献 欢迎贡献。环境搭建、运行检查与提交 Pull Request 的方式请参阅 [CONTRIBUTING.md](https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md)。 要新增或修改对 harness（Claude、Codex、Cursor、OpenCode、Hermes、Pi 等）的支持？请运行 [harness test bench](https://github.com/omnigent-ai/omnigent/tree/main/tests/harness_bench)，对照实际行为检查其能力矩阵（capability matrix）。 ### 贡献者 感谢所有出色的贡献者！