ワンクリックで
omni-setup
// Get Omni running from scratch — install, connect WhatsApp, plug your agent, verify. Zero to messaging in 4 steps.
// Get Omni running from scratch — install, connect WhatsApp, plug your agent, verify. Zero to messaging in 4 steps.
Always-on Omni router for messaging across WhatsApp, Telegram, Discord, Slack. Routes to omni-agent (verbs/replies), omni-setup (install/connect), or omni-ops (admin).
Agent communication toolkit — verb commands for WhatsApp, Telegram, Discord, Slack. Say, speak, imagine, react, listen, see, history, done.
Platform operations — instances, routes, providers, config, events, automations, webhooks, prompts, contacts, batch processing.
| name | omni-setup |
| description | Get Omni running from scratch — install, connect WhatsApp, plug your agent, verify. Zero to messaging in 4 steps. |
| allowed-tools | Bash(omni *), Bash(genie *), Bash(pm2 *) |
End-to-end guide for getting Omni installed, a channel connected, an agent plugged in, and messages flowing. Follow the steps in order — each builds on the previous one.
Check if Omni is already running:
omni auth status
If this returns a valid connection, skip to Step 2.
If Omni is not installed or not running, run the interactive setup wizard:
omni install
The wizard handles everything: system checks, NATS download, process manager selection (PM2 recommended), port configuration, API key generation, and service startup. It writes config to ~/.omni/config.json automatically.
For scripted/CI installs, use non-interactive mode:
omni install --non-interactive
After install, verify the server is healthy:
omni status
List existing channel instances:
omni instances list
If you already have an instance with status connected, skip to Step 3.
If no instances exist, start the WhatsApp connection flow:
omni start
This starts the Omni server and displays a QR code in the terminal. Scan the QR code with your WhatsApp mobile app (Settings > Linked Devices > Link a Device).
After scanning, verify the instance appeared and is connected:
omni instances list
You should see your instance with status connected. Note the instance ID — you will need it for the next step.
For other channels (Telegram, Discord, Slack), refer to the specific channel documentation and use omni instances create with the appropriate provider.
Connect your Omni instance to a Genie agent with a single command:
omni connect <instance-id> <agent-name>
This command does four things automatically:
genie dir ls <agent-name>)nats-genie)Flags:
| Flag | Default | Behavior |
|---|---|---|
--mode <mode> | turn-based | turn-based (round-trip; agent ends each turn with omni done) or fire-and-forget (Omni publishes and does not wait) |
--reply-filter <filter> | all | all reply to every inbound message; filtered apply agentReplyFilter.conditions (DM, mention, reply enabled by default; name-match disabled) |
--nats-url <url> | localhost:4222 | NATS server URL used by the provider for publish/subscribe |
⚠️ Reply filter default —
allmeans "reply to everything." On WhatsApp this includes every group and broadcast the account is in. If the instance will join groups, pass--reply-filter filteredat connect time, or tighten later with:omni instances update <id> --reply-filter-mode filtered --reply-on-dmA null/missing
agentReplyFilteralso allows every message through (behavior change introduced in automagik-dev/omni#371 — previously null silently dropped every message). The API logs a one-time warning per instance when a null filter is detected.
The agent must be registered in the Genie directory first. If it is not, register it:
genie dir add <agent-name> --dir /path/to/agent
Start the Genie server. The NATS ↔ agent bridge (OmniBridge) is instantiated inside genie serve start automatically — there is no genie omni start command.
genie serve start
When a message arrives on the connected instance, the bridge:
omni.message.<instance-id>.<chat-id>)OMNI_INSTANCE, OMNI_CHAT, OMNI_MESSAGE, OMNI_AGENT)omni say, omni speak, etc.), publishing on omni.reply.<instance-id>.<chat-id>turn-based mode the agent signals completion with omni doneVerify the bridge is live:
genie serve status
For long-running deployments, keep genie serve under a process manager:
pm2 start "genie serve start" --name genie-serve
pm2 save
The nats-genie provider and the genie OmniBridge communicate over plain NATS subjects. Understanding the contract makes debugging straightforward — you can subscribe to any subject with nats sub '<pattern>'.
| Direction | Subject | Purpose |
|---|---|---|
| Omni → Genie | omni.message.<instance-id>.<chat-id> | Inbound user message payload (content, sender, files, env) |
| Genie → Omni | omni.reply.<instance-id>.<chat-id> | Agent-generated reply delivered back to the channel |
| Omni → Genie | omni.session.reset.<instance-id>.<chat-id> | { action: 'kill' } — drop the agent's in-memory session for this chat |
| Omni → Genie (turn lifecycle) | omni.turn.{open,done,nudge,stalled,timeout}.<instance-id>.<chat-id> | Real-time turn signals for turn-based mode |
Important: Omni subscribes to omni.reply.<instance-id>.> (recursive wildcard). WhatsApp chat IDs contain dots (e.g. 5511999999999@s.whatsapp.net), which the single-token wildcard * does not match. See docs/migration/nats-genie-sidecar-decommission.md.
After completing all four steps, verify the full pipeline is working.
Check your active instance and chat context:
omni where
Verify the agent is assigned to the instance (agentId should not be null):
omni instances get <instance-id>
Verify the agent appears in Genie after receiving its first message:
genie ls --source omni
Set your working context and send a test message:
omni use <instance-id>
omni open <chat-jid>
omni say "test"
If the agent is running, you should see a reply appear in the chat.
Symptom: Bridge fails to start or logs connection refused errors.
pm2 list # Check if omni-nats process exists and is online
pm2 restart omni-nats # Restart NATS server
pm2 logs omni-nats # Check NATS logs for errors
If NATS was never started, the omni install wizard may not have completed fully. Start it manually:
~/.omni/nats-server -js -sd ~/.omni/data/nats
Symptom: API returns 500 errors or the bridge starts in degraded mode.
pm2 restart omni-api # Restart the Omni API server
pm2 logs omni-api # Check API server logs
omni status # Verify API health endpoint
Check that the database URL in ~/.omni/server-config.json is correct and the PostgreSQL server is running.
Symptom: omni connect fails with "Failed to discover agent" error.
genie dir ls # List all registered agents
genie dir add <name> --dir /path/to/agent # Register the agent
The agent directory path must contain the agent's configuration files (CLAUDE.md, AGENTS.md, or equivalent).
Symptom: Messages arrive but the agent never responds.
genie events list --since 5m # Check recent events for errors
genie ls # Check if the agent process is running
pm2 logs omni-bridge # Check bridge logs for delivery errors
Common causes:
genie serve start (verify with genie serve status)genie events errorsomni done at the end of each turnfiltered but no filter conditions match (e.g. onDm: true in a group chat) — inspect with omni instances get <id> --json | jq .agentReplyFilterSymptom: omni instances get <id> shows agentId as null even after running omni connect.
This can happen if the API update call failed silently. Set the agent ID manually:
omni instances update <instance-id> --agent-fk-id <agent-uuid>
To find the agent UUID:
omni agents list # Find the agent record created by connect
Then update the instance with the correct ID. If the agent record is also missing, re-run omni connect or create the agent manually via the API.
Symptom: WhatsApp QR code disappears or phone cannot scan it.
omni instances qr <instance-id> # Regenerate QR code
Make sure your phone has a stable internet connection and WhatsApp is up to date. The QR code expires after approximately 60 seconds — scan it promptly after it appears.