正在加载插件详情…
用一套 API 在多个聊天平台收发并路由消息
数据截至 2026/11/18 · 周下载取自 npm 全网(含 CI / 镜像),非本站安装数;综合分由星标、活跃度与兼容性检查合成。
dsh plugin --profile web add automagik-si/omni通用事件驱动全渠道平台,让 AI 智能体跨任意消息平台通信
通用的事件驱动全渠道消息平台一套 API,在 WhatsApp、Discord、Slack、Telegram 等渠道上收发消息、路由、自动化。命令行优先。事件驱动。为 AI 智能体而生。
安装 • 快速开始 • AI 智能体 • 命令行 • API • SDK • 开发
把 Omni 想成一只深海章鱼。每条渠道都是一根触手,伸进不同的消息生态。事件是神经冲动,在 NATS JetStream 中流动。核心是大脑:身份解析、事件路由,还有一套统一 API,让你把每条渠道当成同一个系统来用。
为什么选 Omni?
| 🔌 一套 API,覆盖所有渠道 | 用同一个接口发送 WhatsApp、Discord、Slack、Telegram 等渠道的消息 |
| ⚡ 事件驱动 | 每个动作都会产生事件。订阅、回放、自动化 |
| 🧬 身份图谱 | 跨渠道、跨实例识别同一个人 |
| 🤖 AI 原生 | 服务商绑定、响应门控、会话策略、自动化、智能体调度 |
| 🔧 插件架构 | 用 Channel SDK 构建渠道和集成 |
| 📦 SDK | TypeScript SDK,另有为 API 调用方生成的 Python/Go 客户端 |
渠道
| 渠道 | 状态 | 亮点 |
| WhatsApp(Baileys) | ✅ 稳定 | 二维码/手机号配对、媒体、表情回应、群组、联系人、在线状态 |
| WhatsApp Cloud API(Meta) | ✅ 可用 | 嵌入式注册 OAuth、模板 HSM、webhook(HMAC-SHA256)、媒体、位置、表情回应 |
| Discord | ✅ 稳定 | 机器人、嵌入消息、投票、按钮、子区、斜杠命令、语音频道 |
| Slack | ✅ 可用 | Socket Mode 或 HTTP、机器人及用户(xoxp)token 模式、子区、定时消息、永久链接、置顶、消息搜索 |
| Telegram | ✅ 可用 | Bot API、内联键盘、群组、频道、子区、投票 |
| A2A | ✅ 可用 | 智能体到智能体的渠道集成 |
| Gupshup | ✅ 可用 | 支持自定义集成 webhook |
| H3rmes(Mutant) | ✅ 可用 | 巴西 WhatsApp 网关 —— 支持 JWT 认证、媒体、模板、交互消息,webhook 结构兼容 Pix |
| ASC Brazil | ✅ 可用 | 巴西 WhatsApp BSP —— 镜像 Cloud API,webhook 采用 Meta 格式,支持输入状态提示、模板、交互消息 |
| ASC Flow | ✅ 可用 | 通过 ASC 平台 Flow 接入的巴西 BSP —— REST 回调、URA 按钮/列表、Genesys 转接 |
| Twilio WhatsApp | ✅ 可用 | 支持 Twilio 发送方、webhook 与签名校验 |
另外还内置 Harness(--channel harness):这是一个端到端智能体测试通道,会原样捕获发出的消息,让你能在测试中驱动智能体对话并对其断言;此外还有一个内部通道,用于智能体之间的路由。
安装
全局命令行包
bun add -g @automagik/omni
omni install # bootstrap the local server/runtime with PM2
从 @omni/cli 迁移? 先运行 bun remove -g @omni/cli。
通过安装脚本
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash
从源码安装完整服务端
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash -s -- --server
脚本支持的安装模式:仅命令行(--cli)和完整服务端(--server)。
非交互式与手动安装
CLI only
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash -s -- --cli
Full server
curl -fsSL https://raw.githubusercontent.com/automagik-dev/omni/main/install.sh | bash -s -- --server
Connect the CLI to a remote server after install
omni auth login --api-url https://your-omni-server.example.com --api-key <your-api-key>
手动安装:
git clone https://github.com/automagik-dev/omni.git && cd omni
make setup # install deps, create .env, start services
API 运行在 http://localhost:8882 · Swagger 文档在 /api/v2/docs · API key 会打印在启动横幅里。
快速开始
Authenticate
omni auth login --api-key <your-api-key>
WhatsApp — scan QR omni instances create --name "my-whatsapp" --channel whatsapp-baileys omni instances qr <id> --watch
Discord — connect bot omni instances create --name "my-discord" --channel discord --discord-token <discord-bot-token> omni instances connect <id>
Telegram — connect bot omni instances create --name "my-telegram" --channel telegram --telegram-token <telegram-bot-token> omni instances connect <id>
Send messages
omni send --to "+15555550100" --text "Hello from the deep 🐙"
Browse conversations
omni chats list --unread --sort unread
AI 智能体
接入智能体服务商后,你的实例就能回复消息、响应事件,并跨通道路由会话。
Message received → NATS event → Agent Dispatcher → Provider → Response gate → Channel reply
Create a provider
omni providers create \
--name "my-agent" \
--schema webhook \
--base-url "https://agent.example.com/webhook" \
--api-key <provider-api-key>
Bind it to an instance
omni instances update <id> --agent-provider <provider-id>
服务商 schema:agno · webhook · ag-ui · claude-code · a2a · nats-genie
| 触发方式 | 触发时机 | 适用场景 |
| DM | 私信 | 总是回复 |
| Mention | 群里 @bot | 响应提及 |
| Reply | 回复 bot 的消息 | 延续话题 |
| Reaction | 给消息加 emoji | 审批、优先级、轻量工作流 |
内置能力: 消息防抖 · 按用户限流 · 访问控制 · 响应闸门 · 智能分块 · 输入中状态 · 跨渠道身份 · 自聊检测
自动化与事件驱动工作流
Auto-reply
omni automations create --name "welcome" \
--trigger "message.received" \
--action send_message --action-config '{"text":"Got it! 🐙"}'
Webhook on connection
omni automations create --name "notify" \
--trigger "instance.connected" \
--action webhook --action-config '{"url":"https://your-app.example.com/hook"}'
Route important senders to a dedicated agent
omni automations create --name "priority-route" \
--trigger "message.received" \
--condition '{"field":"payload.from","op":"in","value":["+15555550100"]}' \
--action call_agent --agent-id "priority-handler" --provider-id <provider-id>
事件主干
每次状态变更都会写入 PostgreSQL 日志,按全序排列,并通过 NATS 发布。日志是唯一事实来源——你可以过滤它、追踪它、等待它,也可以持久消费它:
omni events list --type "message." --since 2h # trailing- glob type filters
omni events types --since 7d # what's flowing: volume, schema status, subscribers
omni events stream --pretty --exclude "custom.chat." # live tail, one line per event, minus the noise
omni events trace <event-id> # causation chain, rendered as a tree
omni events wait --type "custom.github." --timeout 60 # block until a matching event arrives
Durable named consumers — resumable cursors over the journal omni events consumers create deploy-watcher --type "custom.github." omni events follow --consumer deploy-watcher # at-least-once, acks as it goes
Webhook 源只靠配置就能把外部系统变成事件发送方,无需写代码:原始请求体签名校验(HMAC-SHA256/SHA1 或 token 比对)、按源配置幂等键模板、事件类型映射到 custom..<event>、可选的严格 schema 校验,以及基于心跳的连接器存活检测(system.connector.stalled / recovered)。可直接照抄的配方:GitHub 和 ClickUp。
事件 schema 只需注册一次(omni events schema register),之后在 webhook 入口和自动化 emit_event 处强制校验——payload 不合法会进入死信队列,不会写进 journal。
智能体 manifest 声明每个智能体消费和发布什么(omni agents manifest apply、omni agents graph):publishes 列表在发送时强制校验,accepts 会编译成托管的 routing 自动化。自动化还可以先缓冲自己发出的事件,等整轮运行成功后再按顺序 flush(--transactional-emissions)。
深入阅读:事件系统 · 持久化消费者 · 智能体发布治理
架构
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ WhatsApp │ │ Discord │ │ Slack │ │ Telegram │ Tentacles
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
└────────────────┴────────────────┴────────────────┘
┌─────────▼─────────┐
│ NATS JetStream │ Nerve system
└─────────┬─────────┘
┌─────────▼─────────┐
│ Omni Core │ Brain
└─────────┬─────────┘
┌────────────────────┼────────────────────┐
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ REST API │ │ CLI │ │ Desktop │ Interfaces
└───────────┘ └───────────┘ └───────────┘
项目结构
packages/
├── core/ # Events, identity, schemas
├── db/ # Drizzle ORM + PostgreSQL
├── api/ # Hono + REST + OpenAPI
├── channel-sdk/ # Plugin SDK
├── channel-whatsapp/ # WhatsApp Baileys
├── channel-whatsapp-business/ # WhatsApp Cloud API (Meta)
├── channel-discord/ # Discord
├── channel-slack/ # Slack
├── channel-telegram/ # Telegram
├── channel-gupshup/ # Gupshup
├── channel-hermes/ # H3rmes (Brazilian WhatsApp gateway)
├── channel-twilio-whatsapp/ # Twilio WhatsApp
├── channel-a2a/ # A2A channel
├── channel-asc/ # ASC Brazil (ASCWhats GW, Cloud API mirror)
├── channel-asc-flow/ # ASC platform Flow (Brazilian BSP)
├── channel-harness/ # E2E agent-testing channel
├── channel-internal/ # In-process agent-to-agent routing
├── cli/ # omni command
├── media-processing/ # Media sync and extraction
├── voice-client/ # Voice transport/codec library (Discord voice)
├── sdk/ # TypeScript SDK
├── sdk-go/ # Go SDK
└── sdk-python/ # Python SDK
命令行参考
核心命令 — send、chats、messages、instances、persons
send — 发送消息
omni send --to "+15555550100" --text "Hello!"
omni send --to "+15555550100" --media ./photo.jpg --caption "Check this out"
omni send --to "+15555550100" --reaction "👍" --message <message-id>
omni send --to "+15555550100" --sticker ./sticker.webp
omni send --to "+15555550100" --contact --name "Example User" --phone "+15555550101"
omni send --to "+15555550100" --location --lat 37.7749 --lng -122.4194 --address "San Francisco"
omni send --to "discord-channel-id" --poll "Favorite color?" --options "Red,Blue,Green"
omni send --to "discord-channel-id" --embed --title "Alert" --description "Server rebooting" --color "#ff0000"
omni send --to "+15555550100" --presence typing
chats — 管理会话
omni chats list --unread --sort unread
omni chats messages <chat-id> --limit 20 --rich
omni chats archive <chat-id>
omni chats participants <chat-id> --add "+15555550100"
messages — 搜索与管理
omni messages search "meeting tomorrow" --instance <id> --limit 10
omni messages read --chat <chat-id> --instance <id>
instances — 渠道连接
omni instances list
omni instances create --name "work-whatsapp" --channel whatsapp-baileys
omni instances qr <id> --watch
omni instances create --name "ops-slack" --channel slack --slack-bot-token <bot-token> --slack-app-token <app-token>
omni instances connect <id>
omni instances sync <id> --type all --depth 30
omni instances contacts <id> --limit 50
omni instances groups <id>
运行 omni instances --help 查看各渠道的完整命令列表。
persons — 联系人目录
omni persons search "Example User"
omni persons get <id>
omni persons presence <id>
管理 — keys、providers、automations、access、webhooks、schedule、tenants
keys — API 密钥管理
omni keys create --name "agent-key" --scopes "messages:,instances:read"
omni keys list --status active
omni keys revoke <id> --reason "Compromised"
providers — AI/智能体服务商
omni providers create --name "webhook-agent" --schema webhook --base-url "https://agent.example.com" --api-key <provider-api-key>
omni providers list
omni providers test <id>
Schema:agno · webhook · ag-ui · claude-code · a2a · nats-genie
automations — 事件驱动工作流
omni automations create --name "Auto-reply" --trigger "message.received" \
--action send_message --action-config '{"text":"Got it!"}'
omni automations list --enabled
omni automations test <id> --event <event-id> # dry-run against a real journaled event: condition verdicts, no side effects
动作:webhook · send_message · emit_event · log · call_agent
access — 访问控制
bash
omni access create --type deny --instance <id> --phone "+15555550100" --action block
omni access list --instance <id>
omni access check --instance <id> --user "+15555550100"
模式:disabled · blocklist · allowlist
webhooks — 外部事件源 bash
omni webhooks create --name "github-events" \
--signature-algorithm hmac-sha256 --signature-header "X-Hub-Signature-256" --signature-prefix "sha256=" \
--signature-secret-env GITHUB_WEBHOOK_SECRET \
--event-type-mapping '{"source":"header","header":"X-GitHub-Event"}' \
--idempotency-key-template "github:{headers.x-github-delivery}"
omni webhooks heartbeat github-events # connector liveness check-in
omni webhooks trigger --type "custom.event" --payload '{"key":"value"}'
事件源从公开端点 POST /api/v2/webhooks/ingress/:source 接收事件(必须带签名)。参考 GitHub 和 ClickUp 的配置示例。
schedule — 定时消息 bash omni schedule send <instance> <chat-id> "Stand-up in 10" --at 2h # ISO timestamp or 30m/2h/3d omni schedule list <instance> omni schedule cancel <id>
渠道原生支持定时投递时就用原生能力(Slack,仅文本);其他渠道由本地清扫器在预定时间发送。
tenants — 平台租户控制面 bash omni tenants create --slug acme --name "Acme" --max-key-ttl 7776000 --max-key-rate 100 --max-key-budget 1000 --reason "onboarding"
omni tenants keys issue-root <tenant-id> --principal <uuid> --membership <uuid> --role tenant-owner \
--name root --scopes "tenant:" --expires 2026-12-01 --rate-limit 100 --budget 1000 --reason "bootstrap"
omni multitenancy status
需要 PLATFORM 类凭据,并设置 OMNI_MULTITENANCY_ENABLED=true;每条命令都要带 --reason,并记入审计。Omni 默认单租户运行——见平台凭据引导。
System — 更新、状态、诊断、认证、配置、事件、日志 bash omni update -y # update CLI; restart only services that were already online omni update -y --no-restart # update CLI only; skip restarts and API-port health check omni status # verify runtime health omni doctor # diagnose embedded runtime issues omni doctor --fix # repair safe runtime drift in-place omni auth login --api-key <your-api-key> # authenticate omni config set defaultInstance <id> # CLI settings omni events list --type "message." --since 2h # event history (trailing-* globs) omni events types # observed event types: volume, schema, subscribers omni events stream --pretty # live tail, one colored line per event omni events trace <event-id> # 因果链 omni events wait --type "custom.x." --timeout 60 # 阻塞,直到出现匹配的事件 omni events schema register <type> --file s.json # 注册 payload schema omni events schema validate <type> --file p.json # 试运行 payload,不发出事件 omni events consumers create <name> --type "custom.x." # 持久游标 omni events follow --consumer <name> # 持久 tail omni events replay --start --since 2024-01-01 # 重放事件 omni journey show <correlation-id> # 逐条消息的延迟时间线 omni batch create --instance <id> --type targeted_chat_sync --chat <chat-id> omni resync --instance <id> # 回填历史 omni logs list --level error --limit 50 # 服务端日志 omni dead-letters list --limit 20 # 失败的事件
omni update 只在执行 restart 时才会在安装后以非零状态退出(此时服务已在线):这条路径下,它会检查配置的 API 端口上的 API 健康状态,一旦 restart 或健康检查出错就报错退出。
omni doctor --fix 绝不删除数据库数据。它只修复安全的运行时漂移,例如 PM2 状态、已存储的环境变量和 CLI 配置;破坏性清理仍需手动执行。
REST API
| Base URL | http://localhost:8882/api/v2 |
| Docs | /api/v2/docs(Swagger UI) |
| OpenAPI | /api/v2/openapi.json |
| Auth | x-api-key 请求头 |
主要 API 分组包括:/auth、/instances、/messages、/chats、/events(外加 /events/schemas、/events/consumers,以及每个事件的 /trace)、/persons、/access、/settings、/providers、/automations、/webhooks、/scheduled-messages、/keys、/logs、/batch-jobs、/dead-letters、/media、/metrics、/event-ops、/payloads、/agents、/agent-state、/agent-tasks、/conversations、/context、/turns、/trust、/voice、/follow-up、/handoffs、/journeys、/instances/:id/whatsapp-templates 和 /platform(多租户控制平面,由开关控制)。
SDK
TypeScript
typescript
import { createOmniClient } from '@omni/sdk';
const omni = createOmniClient({
baseUrl: 'http://localhost:8882',
apiKey: '<your-api-key>',
});
await omni.messages.send({
instanceId: '<instance-id>',
to: '+15555550100',
text: 'Hello from SDK!',
});
Python 和 Go
生成的 Python 和 Go 客户端位于 packages/sdk-python 和 packages/sdk-go。它们对 API 调用方有用,但本版本主要维护的 SDK 是 TypeScript SDK。
API 变更后重新生成 SDK: bash
make sdk-generate
桌面应用
Omni 的界面是 Automagik 桌面应用(omni desktop 会带着预加载的 Omni 打开它):它可以在你的机器上运行 Omni,也可以连接远程的 Omni。API 自身不提供任何网页。
🔐 API 密钥与安全 API key 在首次启动时生成,只在启动横幅里显示一次。
bash
omni keys create --name "admin" --scopes ""
omni keys create --name "reader" --scopes "messages:read,chats:read"
omni keys create --name "channel-only" --scopes "messages:" --instances "uuid1,uuid2"
作用域用 namespace:action 模式:messages:、instances:read、 表示完全访问。
命名空间包括:messages、chats、instances、persons、events、access、settings、providers、automations、webhooks、keys、logs 和 batch。
⚙️ 配置与环境
| 变量 | 默认值 | 说明 |
| API_PORT | 8882 | API 服务器端口 |
| DATABASE_URL | postgresql://...localhost:8432/omni | PostgreSQL |
| NATS_URL | nats://localhost:4222 | 客户端连接 NATS 的地址 |
| NATS_HOST | 127.0.0.1 | 源码检出方式的 PM2 NATS 监听地址(安装器:omni config set server.natsHost) |
| OMNI_API_KEY | (自动) | 覆盖主 key |
外部服务请设置 _MANAGED=false。完整列表见 .env.example。
只有 omni-nats 被 omni start、omni install 或之后的 omni update 重新创建后,托管 NATS 才只监听回环地址(omni restart 沿用之前的参数,参数不同时会给出警告)。升级已有安装后,执行一次 omni stop && omni start。只有其他主机必须连接时,才把 NATS_HOST / server.natsHost 设为 0.0.0.0,并做好防护(NATS 认证/TLS 或私有网络)。执行 omni stop && omni start 生效。见 docs/guides/install.md。
| 服务 | PM2 名称(安装器 / 源码检出) | 端口 |
| API | omni-api / omni-v2-api | 8882 |
| NATS | omni-nats / omni-v2-nats | 4222 |
| PostgreSQL | autopg-server(规范 pgserve,由 omni install 管理) | 8432 |
开发 bash
make dev # Start all services + API
make test # Run test suite
make typecheck # TypeScript checks
make lint # Biome lint
make sdk-generate # Regenerate SDKs from OpenAPI
配置与环境
| 变量 | 默认值 | 说明 |
| API_PORT | 8882 | API 服务器端口 |
| DATABASE_URL | postgresql://user:password@localhost:8432/omni | PostgreSQL 连接 |
| NATS_URL | nats://localhost:4222 | 客户端连接 NATS 的地址 |
| NATS_HOST | 127.0.0.1 | 源码检出方式的 PM2 NATS 监听地址(安装器:omni config set server.natsHost) |
| OMNI_API_KEY | 自动生成 | 覆盖主 API key |
外部服务请设置 _MANAGED=false。完整列表见 .env.example。
托管 NATS 只监听回环地址,前提是 omni-nats 已由 omni start、omni install 或后续的 omni update 重新创建(omni restart 沿用上一次的参数,参数不一致时会给出警告)。升级已有安装后,执行一次 omni stop && omni start。只有其他主机必须连接时,才把 NATS_HOST / server.natsHost 设为 0.0.0.0,并做好防护(NATS 认证/TLS 或私有网络)。用 omni stop && omni start 生效。参见 docs/guides/install.md。
| 服务 | PM2 名称(安装器 / 源码检出) | 端口 |
| API | omni-api / omni-v2-api | 8882 |
| NATS | omni-nats / omni-v2-nats | 4222 |
| PostgreSQL | autopg-server(标准 pgserve,由 omni install 管理) | 8432 |
渠道 SDK typescript
import { BaseChannelPlugin } from '@omni/channel-sdk';
import type { InstanceConfig, OutgoingMessage } from '@omni/channel-sdk';
export class MyPlugin extends BaseChannelPlugin {
readonly id = 'my-channel';
readonly name = 'My Channel';
readonly version = '1.0.0';
readonly capabilities = { /* ... / };
async connect(instanceId: string, config: InstanceConfig) { / ... / }
async disconnect(instanceId: string) { / ... / }
async sendMessage(instanceId: string, message: OutgoingMessage) { / ... */ }
}
技术栈
| 运行时 | Bun |
| HTTP | Hono |
| API | Hono REST + OpenAPI |
| 数据库 | PostgreSQL + Drizzle |
| 事件 | NATS JetStream |
| 校验 | Zod |
| Monorepo | Turborepo |
| Linter | Biome |
Apache-2.0 — 想怎么用就怎么用,只是别怪章鱼。🐙用一套 API 在多个聊天平台收发并路由消息
本站实装验证(真实安装 L4 覆盖全站;L5 为运行时冒烟或实机截图,覆盖范围小于 L4) · 验证所用 dsh 版本 · 静态安装检查 · 风险分级 · 仓库维护状态。 下方各区块是它的证据明细。
@deepseek-ai/dsh-plugin-market-index