项目快照：omnigent-ai/omnigent，约 10,092 个 Star，1,597 个 Fork；最新推送时间 2026-09-19T05:54:15Z。本文基于仓库公开资料撰写。
项目地址：https://github.com/omnigent-ai/omnigent · https://omnigent.ai
项目速览（TL;DR）
omnigent 是一个开源人工智能代理编排框架，同时也是一个元框架（meta-harness）。它在 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 以及自定义代理之上提供统一的编排层，目标是让用户在不重写业务流程的前提下更换或组合不同代理运行时。
根据所给 GitHub 仓库元信息，项目默认分支为 main，主要语言为 Python，许可证为 Apache-2.0，仓库拥有 10092 个 Star 和 1597 个 Fork。README 将项目标记为 Alpha 状态；PyPI 项目版本徽章出现在 README 中，但所给资料没有提供当前发布版本号，源码构建配置中的版本是 0.15.0.dev0。
- 项目定位：面向多代理运行时的统一会话、策略、沙箱和协作层。
- 主要入口：终端、浏览器、手机以及原生桌面应用。
- 运行基础：Python 3.12 及以上版本。
- 核心治理：策略（policies）、审批、消费上限、工具访问限制和沙箱执行。
- 许可证：Apache License 2.0，具体再分发条件以仓库中的
LICENSE为准。
“The open-source meta-harness for all your AI agents.”
来源：README
定位与目标用户
Omnigent 解决的不是单个模型调用问题，而是多种代理工具并存时的会话管理、工具治理和运行环境切换问题。用户可以把不同代理放入同一会话，让一个代理审查另一个代理的工作，也可以把任务拆分给擅长不同工作的代理。
根据 README，项目面向需要跨设备继续工作、需要集中管理代理行为、或需要在本机与云沙箱之间切换的开发团队。对于只调用单一模型接口、没有终端操作需求、也不需要多代理协作的项目，元编排层可能带来额外的部署与治理复杂度；这一判断属于根据本文作者的经验判断，仓库没有发布定量评估。
目标问题
- 代理运行时不同，用户不希望为每个代理重写整套交互流程。
- 任务需要在终端、浏览器、手机和桌面端之间连续进行。
- 多个代理需要共享会话上下文，并互相审查或拆分任务。
- 高风险工具调用需要人工批准、成本限制或访问控制。
- 代理需要在一次性云沙箱、Kubernetes 或本机环境中执行。
核心功能
核心能力可以分为代理编排、跨设备会话、协作、沙箱和治理五个层面。它们共同组成 README 所称的“common orchestration layer”，但不同能力的可用性还取决于相应代理、模型提供商、沙箱提供商和可选依赖是否完成配置。
多代理编排
Omnigent 将 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 以及 YAML 定义的自定义代理放入统一会话中。输入可以是用户消息、文件、终端操作或代理产生的中间结果；输出则可以继续进入当前会话、交给另一个代理审查，或作为拆分任务的结果返回。
README 明确提到，用户可以让一个代理审查另一个代理的工作，也可以把任务拆分给各自擅长不同工作的代理。所给资料没有提供完整的 YAML schema、调度算法、并发模型或代理间消息协议，因此这些接口不能根据本文自行推断。
跨设备会话同步
README 描述的会话模型会同步消息、子代理、终端和文件状态。用户可以从终端开始，在浏览器中继续，再使用手机接续；这说明项目关注的是会话状态的持续管理，而不仅是对某一次模型请求的封装。
资料没有给出服务端端口、认证配置、同步协议、数据库初始化方式或移动端客户端的具体安装步骤。部署这些部分时，应以最新 README 和官网文档为准，不应根据“浏览器、手机、桌面端”这些产品描述自行推导网络接口。
模型与代理运行时接入
README 表示，项目支持第一方 API Key、Claude 或 ChatGPT 订阅，以及兼容的网关。源码依赖中包含 claude-agent-sdk 和 openai-agents，并将它们作为基础安装依赖，而不是仅放在可选 extras 中。
这意味着基础安装路径至少为两个代理 SDK 预留了运行时集成，但不能据此断言所有模型提供商都开箱即用。README 列出的模型提供商 extras 包括 databricks、bedrock 和 vertex；相应凭据字段、选择命令和认证流程在所给片段中未提供。
实时协作
协作功能支持共享会话、让队友实时查看代理工作、在本机共同驱动代理，或派生对话后独立继续。其输入来自共享会话中的成员操作，输出是实时可见的消息、终端活动和文件变化。
资料没有说明成员角色、邀请方式、权限模型、审计格式或离线冲突解决策略。涉及团队协作时，应先确认这些边界，再决定是否用于包含敏感代码、客户数据或生产凭据的会话。
云沙箱与托管主机
README 列出了 Modal、Daytona、Blaxel、Islo、E2B、Gensee、CoreWeave、Kubernetes、OpenShell、Boxlite、microsandbox 和 Databricks 等沙箱或托管环境。触发方式可以是命令行启动，也可以由服务端为每个会话配置托管主机；资料明确描述了“每会话一次性沙箱”的使用方向。
沙箱集成依赖对应 extras，例如 modal、daytona、e2b、openshell 和 kubernetes。仓库资料未给出镜像、网络、资源配额、生命周期回收或持久卷配置，因此不能把这些云平台列举解释为统一的默认运行方案。
策略与审批
策略用于在代理执行危险操作前暂停并等待批准，也可设置消费上限和限制代理能够访问的工具。README 指出，策略可以作用于整个服务器、单个代理或单个聊天，说明治理范围至少包含服务器级、代理级和会话级三个层次。
pyproject.toml 将 cel-python 列为运行依赖，并注明它用于内联策略求值；该依赖基于通用表达式语言（Common Expression Language，CEL），并强调表达式非图灵完备、无副作用且保证终止。资料没有提供具体策略字段、表达式示例或审批 API，因此不应在生产环境照搬未验证的规则格式。
系统架构与关键模块
从仓库描述和 Python 依赖可以确认，Omnigent 是由客户端、服务端、代理适配、策略执行、终端、持久化和可选集成组成的框架。资料没有提供完整目录树，下面仅区分能够从文件和依赖中核实的模块职责，不把推断出的目录当作官方结构。
编排层与代理适配层
元编排层负责向上提供统一会话，并把请求交给不同代理运行时。README 中列出的 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 和自定义代理属于被编排对象；claude-agent-sdk 与 openai-agents 则是源码配置中明确列出的基础 SDK。
自定义代理采用 YAML 定义这一事实来自 README，但 YAML 文件的字段、加载位置、生命周期和错误处理方式未在资料中给出。需要扩展代理时，应以源码和最新文档中的 schema 为准，而不是把任意 YAML 文件直接提交到运行环境。
服务端、客户端与用户界面
pyproject.toml 中出现了 fastapi、starlette 和 uvicorn[standard]，表明 Python 依赖集合包含服务端和 ASGI（异步服务器网关接口）运行组件。omnigent-client 与 omnigent-ui-sdk 也被列入项目依赖，说明主包会与客户端和界面 SDK 一起发布或解析依赖。
README 同时描述终端、浏览器、手机和原生桌面应用。资料没有提供服务端端口、反向代理配置、静态资源路径或桌面应用支持的操作系统范围，部署时应避免把这些缺失信息写入固定运维脚本。
终端与主机生命周期
依赖中包含 pexpect 和 pyte，并通过平台标记排除 Windows；源码注释说明它们用于 POSIX 的 tmux/PTY 终端栈。psutil 则用于主机守护进程生命周期中的进程存活检查，并具备僵尸进程感知能力。
因此，终端能力与操作系统相关，不能将 POSIX 终端行为直接等同于 Windows 环境。所给资料没有说明 Windows 上可用的替代终端实现，也没有提供 tmux、PTY 或进程清理的配置项。
数据层与秘密存储
项目依赖 sqlalchemy、alembic、zstandard 和文件锁组件。源码注释说明，压缩用于把会话中的 JSON 或文本列以统一方式存储到 SQLite、PostgreSQL 和 MySQL，而不是依赖具体数据库引擎的存储压缩实现；Alembic 则属于数据库迁移依赖。
keyring 用于保存模型提供商 API Key；当没有可用的密钥环后端时，资料说明会回退到权限为 0600 的文件。这个回退行为不等同于硬件密钥保护，生产部署仍需核对主机访问权限、备份策略和密钥轮换要求。
依赖与运行环境
官方源码构建配置要求 Python 3.12 或更高版本，项目分类器明确列出 Python 3.12 和 Python 3.13。安装方式包括安装脚本、uv、pip 和 Homebrew；不同方式都应与实际操作系统及可选集成保持一致。
核心依赖范围
- Web 与服务端：
fastapi、starlette、uvicorn[standard]。 - 代理与协议：
claude-agent-sdk、openai-agents、mcp。 - 数据与迁移：
sqlalchemy、alembic、zstandard。 - 策略与认证：
cel-python、PyJWT[crypto]、argon2-cffi。 - 交互与终端：
click、prompt_toolkit、POSIX 平台上的pexpect和pyte。 - 模型和数据处理：
httpx、tiktoken、ftfy。
可选 extras
安装脚本支持用 --extra 添加可选集成。README 明确列出的类别包括模型提供商、沙箱提供商、SDK 代理、存储和记忆服务；extra 名称是安装输入的一部分，不能使用资料中没有列出的别名。
| 类别 | 资料中列出的 extras | 作用范围 |
|---|---|---|
| 模型提供商 | databricks、bedrock、vertex |
连接相应模型服务 |
| 沙箱提供商 | modal、daytona、blaxel、boxlite、microsandbox、cwsandbox、e2b、openshell、kubernetes |
为代理提供隔离执行环境 |
| SDK 代理 | antigravity、copilot、cursor、agents-sdk |
增加代理运行时集成 |
| 存储与记忆 | s3、hindsight |
增加对应存储或记忆能力 |
快速开始
最短安装路径是使用仓库提供的安装脚本；手动安装则要求 Python 3.12 及以上版本。由于所给 README 片段在安装说明处截断，后续完整的服务启动与会话创建命令没有出现在资料中，以下示例只使用已明确给出的安装命令，并对缺失步骤做出标注。
安装
curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh该脚本来自 README 的快速开始章节。脚本会安装 Omnigent 及其所需内容；在执行远程脚本前，应先审查脚本内容，并在测试主机或隔离环境运行。
手动安装
uv tool install omnigent
# 或
pip install "omnigent"如果需要额外集成，可以使用资料中明确给出的 extras 语法：
uv tool install "omnigent[databricks,modal]"上述命令中的 databricks 和 modal 只是示例 extras，不包含任何凭据。模型服务所需的 API Key、订阅认证或网关地址没有在所给资料中规定，不能填入真实密钥到源码、脚本或公开日志。
运行与验证边界
仓库资料明确了安装命令，也在源码注释中出现了 omni upgrade 更新命令；但给定 README 片段没有提供首次启动服务、创建会话或检查安装状态的完整命令。因此，下面不虚构 omni serve、端口或 API 调用。
# 安装完成后，按最新 README 中的运行说明启动服务或会话
# 当前所给资料未提供对应启动命令和验证命令，请以最新 README 为准这意味着“安装 → 运行 → 验证”的完整闭环不能仅依据当前资料安全复现。官方仓库未提供该信息，建议以最新 README 为准；尤其不要通过猜测命令名或默认端口把未经验证的启动方式用于生产环境。
配置说明
所给资料没有提供独立的 .env.example、配置样例或完整运行时字段表。下表因此只列出能够从 pyproject.toml 或 package.json 直接核实的项目配置字段，并明确区分“默认值”与“未提供”，不把依赖版本误写成用户运行时配置。
| 字段名 | 类型 | 默认值 | 作用 |
|---|---|---|---|
project.name |
字符串 | omnigent |
Python 项目包名。 |
project.version |
字符串 | 0.15.0.dev0 |
源码构建配置中的开发版本；发布版本需以实际发行物为准。 |
project.requires-python |
版本约束 | >=3.12 |
规定 Python 运行环境最低版本。 |
build-system.build-backend |
字符串 | setuptools.build_meta |
指定 Python 构建后端。 |
build-system.requires |
数组 | ["setuptools>=68.0"] |
构建阶段所需的 setuptools 版本约束。 |
packageManager |
字符串 | pnpm@11.15.1 |
package.json 中声明的 JavaScript 包管理器及版本。 |
project.license |
项目元数据 | 未提供为单独字段 | 许可证信息由仓库元信息、分类器和 LICENSE 文件确认。 |
API Key 的存储行为可以从源码注释确认：项目使用 keyring 保存模型提供商密钥；没有可用密钥环后端时回退到权限为 0600 的文件。密钥文件具体路径、环境变量名、数据库连接字段和服务端监听地址，官方仓库未提供该信息，建议以最新 README 为准。
进阶用法
进阶使用的重点不是增加更多代理名称，而是把代理选择、执行环境、策略范围和协作方式组合起来。README 已经给出这些组合方向，但没有给出完整配置样例，因此以下内容描述可核实的使用模型，不伪造具体命令。
在同一会话中组合代理
当任务包含实现、审查和验证等不同阶段时，可以让不同代理承担不同角色。输入是同一会话中的任务上下文和前序结果，输出是后续代理可消费的审查意见、文件修改或终端操作；具体哪些代理能够参与，取决于对应集成是否安装并完成认证。
README 明确支持让一个代理审查另一个代理的工作，但没有提供“审查代理”的固定名称或调度语法。实施时应记录每次代理调用的身份、权限、输入文件和输出变更，便于在发生错误时回溯。
使用 YAML 定义自定义代理
自定义代理通过 YAML 定义这一机制适合把代理的声明信息从 Python 代码中分离出来。它可以成为团队共享代理配置的载体，但资料没有给出字段名、环境变量插值规则、工具声明格式或校验命令。
在 schema 未核实前，不应把外部提交的 YAML 直接加载到拥有主机写权限的会话中。更稳妥的流程是先在无敏感数据的测试目录中验证配置，再用策略限制工具和文件范围。
选择本地或云沙箱
本地终端适合需要直接访问开发工作区的交互式任务；云沙箱适合将会话放入一次性或托管执行环境。README 提到沙箱可从 CLI 启动，也可由服务端按会话配置托管主机，但没有给出两种路径的具体参数。
在场景 A 需要本地文件和终端连续性时，可优先核对本地主机能力；在场景 B 需要隔离执行、且对应平台已经配置凭据时，可核对 README 列出的沙箱 extras。两者的资源配额、网络策略和成本边界均未在资料中给出。
可观测性与运维
资料能够确认项目包含服务端、持久化终端、数据库迁移和 OpenTelemetry API 依赖，但没有提供日志字段、指标名称、追踪导出器、健康检查路径或运维面板。运维设计应先以源码和最新文档核实可观测接口，再制定告警规则。
可核实的运维组件
opentelemetry-api：源码注释说明，即使关闭追踪，服务端性能指标也使用其无操作 API。psutil：用于主机守护进程生命周期中的进程存活检查。alembic：数据库迁移依赖。sqlalchemy：数据库访问依赖，资料列出 SQLite、PostgreSQL 和 MySQL 的压缩存储兼容说明。websockets：版本上限为小于 15；源码注释说明这是为了规避 macOS 上异步客户端握手前挂起的问题。
部署检查清单
- 确认主机 Python 版本满足
>=3.12。 - 确认使用的代理 SDK、模型提供商和沙箱 extras 与实际任务一致。
- 确认模型 API Key 使用系统密钥环或受限文件保存，不写入版本库。
- 确认数据库迁移流程来自当前版本文档，不自行修改迁移顺序。
- 确认 POSIX 终端依赖与目标操作系统匹配；Windows 上的 PTY 行为不能按 POSIX 方式假设。
- 确认会话中的终端、文件和子代理信息是否被纳入备份、日志和数据保留范围。
端口、进程管理器、容器编排文件、日志轮转策略和 SLA 均未在所给资料中提供。官方仓库未提供该信息，建议以最新 README、源码和部署文档为准。
安全与合规边界
Omnigent 能够编排会操作终端、文件和工具的代理，因此安全边界取决于代理权限、主机隔离、策略规则和模型凭据管理。以下内容仅讨论在已获授权的本机、测试环境或组织控制的云资源中使用，不提供针对未授权目标的攻击教程、绕过检测方法或凭据获取技巧。
授权与数据范围
- 只允许代理访问操作者有权访问的代码、文件、数据库和云资源。
- 共享会话前确认消息、文件、终端输出和子代理结果是否包含个人数据、客户数据或商业秘密。
- 云沙箱和托管主机需要单独核对供应商的数据驻留、网络出口、销毁和审计条款。
- 不要把真实 API Key、长期云凭据或生产数据库口令写入 YAML、脚本和聊天消息。
- 对会修改文件、执行命令、产生费用或访问外部服务的工具配置人工审批或最小权限策略。
策略、隔离与密钥
README 明确支持在危险操作前暂停审批、限制工具访问和设置消费上限。策略可以作用于服务器、代理或单个聊天；但具体表达式和默认拒绝规则没有提供，因此不能把“支持策略”理解为已经自动满足组织合规要求。
keyring 的密钥环优先策略以及无后端时的 0600 文件回退，都需要结合主机账户权限审查。Apache-2.0 许可证只解决软件版权和专利许可范围，不替代模型提供商、云沙箱供应商或组织内部的数据处理协议。
许可证与商用条款
仓库许可证为 Apache License 2.0。LICENSE 文件授予在许可证条件下复制、修改、公开展示、公开执行、再许可和分发源代码或目标代码的权利，并包含版权许可和专利许可条款。
从许可证类型看，Apache-2.0 允许商业使用，但再分发时仍须遵守 LICENSE 中的条件。包括保留适用的版权、专利、商标和归属声明，保留许可证文本，并遵守关于修改说明、免责声明和专利诉讼终止的条款；具体适用范围以仓库 LICENSE 为准。
许可证不等于服务承诺，也不代表模型、云沙箱、第三方 SDK 或用户数据具有相同许可。第三方依赖和外部服务需要分别核对其许可证、计费、数据处理和使用限制。资料没有提供 Omnigent 的商业版条款、SLA、官方技术支持承诺或赔偿条款。
局限性与已知限制
项目当前在 README 中标记为 Alpha，源码分类器也使用 Development Status :: 3 - Alpha。这意味着生产采用前需要自行验证升级、回滚、数据迁移、权限边界和第三方集成行为；这里不对稳定性作超出资料范围的判断。
- 所给 README 片段没有提供完整启动命令、会话创建命令、端口和服务端配置。
- 没有提供自定义 YAML 代理的完整 schema、示例文件和校验流程。
- 没有提供多代理调度策略、并发限制、重试语义和失败转移规则。
- 没有提供性能基准、吞吐量、延迟、资源消耗或可支持会话规模。
- 沙箱集成虽然列出了多个供应商，但没有给出统一的网络、存储、配额和生命周期配置。
- POSIX 终端依赖在 Windows 上被排除，资料未说明 Windows 的完整替代方案。
- 没有提供默认策略、默认工具白名单、审计日志格式或合规认证信息。
package.json标记为私有包，版本为0.0.0；这不能被解释为 JavaScript 生态中的正式发布版本。
这些限制不是对项目实现质量的推断，而是当前所给资料中缺少的可核查信息。对任何未列明字段，官方仓库未提供该信息，建议以最新 README 为准。
适合谁
以下信号表明组织可以进一步评估 Omnigent，而不是直接假定其适合所有代理场景。最终选择仍应通过受控试点验证。
- 多代理需求明确：团队需要在同一任务中组合 Claude Code、Codex、Cursor 或自定义代理，并希望避免为每种代理重复实现会话层。
- 跨设备工作：工程师需要从终端开始任务，再在浏览器、手机或桌面端继续，并且确实需要同步消息、终端和文件状态。
- 需要治理：组织需要在危险工具调用前审批、限制工具访问或控制代理消费上限。
- 已有沙箱资源：团队已经使用 README 列出的 Modal、Daytona、E2B、Kubernetes 等环境，并愿意维护相应 extras 与凭据。
- 接受 Alpha 阶段：团队有能力自行验证升级、回滚、权限、数据保留和第三方服务条款。
不适合谁
以下信号说明直接使用 Omnigent 可能不符合当前项目约束，或者需要先完成额外的安全和运维评估。
- 单一模型、单一脚本：任务只需要一次模型调用或简单 SDK 封装，不需要会话同步、代理切换和工具治理。
- 严格禁止外部会话服务：组织不能接受消息、终端输出或文件状态进入统一服务端或跨设备同步链路。
- 不允许 Alpha 软件：项目要求已有稳定版本、明确 SLA、正式支持周期或完整性能基准，而当前资料未提供这些承诺。
- 运行环境不是 Python 3.12 及以上：源码构建配置明确要求
requires-python = ">=3.12"。 - 需要完整 Windows PTY 能力：资料明确说明 POSIX 终端依赖在 Windows 上被禁用，但没有提供等价替代实现。
常见问题与排查（FAQ / Troubleshooting）
排查应先确认安装方式、Python 版本、extras 和认证范围，再查看当前版本 README。对于资料中没有给出的端口、配置字段和命令，不建议通过猜测解决。
安装时报 Python 版本错误怎么办
检查 Python 是否满足 3.12 及以上。该约束来自 pyproject.toml 的 requires-python，不是本文额外设定；如果环境版本不满足，应先更换或升级运行环境。
为什么安装后缺少某个沙箱集成
沙箱提供商属于可选 extras，基础安装不会自动代表所有平台集成均已安装。根据 README，应通过安装脚本的 --extra 或手动安装的 extras 语法添加，例如 modal、e2b 或 kubernetes。
为什么找不到启动端口
所给资料没有提供默认端口或监听地址。不要使用未核实的 localhost 端口替代官方配置；应查看当前仓库 README 和服务端启动文档。
模型凭据应放在哪里
源码注释说明项目使用操作系统密钥环保存模型提供商 API Key，在没有可用密钥环时回退到权限为 0600 的文件。具体密钥名称、文件路径和环境变量名未提供，官方仓库未提供该信息，建议以最新 README 为准。
macOS 上 WebSocket 行为异常如何处理
pyproject.toml 将 websockets 的范围限制为 >=10.4,<15，源码注释说明原因是 macOS 上异步客户端在握手前可能挂起。应先确认实际解析到的依赖版本是否符合该范围，再检查是否存在本地环境覆盖；不要自行删除上限而忽略项目注释。
Windows 能否使用终端功能
资料说明 pexpect 和 pyte 通过平台条件排除 Windows，因为项目的 POSIX tmux/PTY 终端栈在 Windows 上不可用。Windows 上的完整替代方案没有在资料中提供，应以最新文档和源码支持矩阵为准。
策略表达式如何编写
项目依赖 cel-python，并用 CEL 进行内联策略求值；但所给资料没有给出策略字段和表达式样例。不要根据 CEL 的一般语法自行推导 Omnigent 的策略 schema，应先查阅当前仓库的策略文档或源码测试。
项目地址与资源
以下链接均来自项目元信息或 README 中出现的官方地址。第三方模型和沙箱服务的具体条款，应在实际启用对应集成前单独核查。
