Install and bootstrap Omni server + CLI from scratch. Use when omni is not running, not installed, or the user needs a full fresh setup.
From omninpx claudepluginhub automagik-dev/omni --plugin omniThis skill is limited to using the following tools:
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Use this when omni status fails, server is not running, or user needs a full fresh install.
which omni 2>/dev/null && omni --version || echo "CLI not installed"
pm2 list 2>/dev/null | grep omni || echo "no omni processes"
curl -s http://localhost:8882/api/v2/health | jq .status || echo "server not reachable"
Decide which steps to skip based on what's already present.
# Bun (if missing)
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"
bun --version # must show 1.x
# PM2 (if missing)
bun add -g pm2
pm2 --version
bun add -g @automagik/omni
omni --version
# expected: 2.260223.x or later
If CLI was already installed but outdated:
bun add -g @automagik/omni@latest
omni install --non-interactive
This bootstraps everything with sane defaults:
Expected output:
✓ bun available
✓ port 8882 is free
✓ NATS binary found at ~/.omni/nats-server
✔ omni-api started
✔ omni-nats started
✔ Server is healthy
✓ Config written to ~/.omni/config.json
✓ Omni v2.260223.x is running!
API: http://localhost:8882
Key: omni_sk_<hex> ← SAVE THIS
Custom port:
omni install --non-interactive --port 9000
# All three must pass:
omni status --json
curl -s http://localhost:8882/api/v2/health | jq '{status, version}'
omni auth status --json
Expected: omni-api online, omni-nats online, status: healthy, status: authenticated.
omni providers setup openclaw \
--gateway-url ws://127.0.0.1:18789 \
--gateway-token <GATEWAY_TOKEN> \
--agent-id <AGENT_ID>
GATEWAY_TOKEN → from openclaw gateway status or gateway configAGENT_ID → the agent name in OpenClaw (e.g. omni, eva, khal)Save the Provider ID from the output.
omni instances create \
--channel telegram \
--name "my-telegram" \
--telegram-token "<BOT_TOKEN>" \
--agent-provider <PROVIDER_ID> \
--agent <AGENT_ID>
Get bot token from @BotFather.
omni instances create \
--channel discord \
--name "my-discord" \
--discord-token "<BOT_TOKEN>" \
--agent-provider <PROVIDER_ID> \
--agent <AGENT_ID>
omni instances create \
--channel slack \
--name "my-slack" \
--slack-app-token "<APP_TOKEN>" \
--slack-bot-token "<BOT_TOKEN>" \
--agent-provider <PROVIDER_ID> \
--agent <AGENT_ID>
omni instances create \
--channel whatsapp-baileys \
--name "my-whatsapp" \
--agent-provider <PROVIDER_ID> \
--agent <AGENT_ID>
# Then scan QR:
omni instances qr <INSTANCE_ID>
# Or pair by phone:
omni instances pair <INSTANCE_ID> --phone "+5511999999999"
| Symptom | Fix |
|---|---|
| "Server bundle not found" | bun remove -g @automagik/omni && bun add -g @automagik/omni@latest |
| Health check fails after install | pm2 logs omni-api --lines 20 --nostream — check for port conflict or pgserve crash |
| Port conflict | omni install --port 9000 |
| pgserve crash | rm -rf ~/.omni/data/pgserve && omni restart |
keyValid: no | pm2 env omni-api | grep OMNI_API_KEY → omni config set apiKey <correct_key> |
missing scope: operator.write | Re-run omni providers setup openclaw ... |
Stale omni-v2-pgserve process | pm2 delete omni-v2-pgserve && omni restart |
| NATS no JetStream (API shows "JetStreamManager not initialized") | pm2 delete omni-nats && pm2 start ~/.omni/nats-server --name omni-nats -- -js -sd ~/.omni/data/nats && pm2 restart omni-api |
omni start # Start API + NATS
omni stop # Stop all
omni restart # Restart all
omni logs # PM2 logs (--process api|nats)
curl -fsSL https://bun.sh/install | bash \
&& export PATH="$HOME/.bun/bin:$PATH" \
&& bun add -g pm2 @automagik/omni \
&& omni install --non-interactive
Then: Step 5 (provider) → Step 6 (instance) → verify end-to-end.