Providers

Provider Commands

The omni providers command group manages AI and agent provider connections. Providers define how Omni routes messages to AI backends — each provider has a schema type, connection config, and optional agent resources.

Provider Schemas

Schema	Description
`agno`	Agno platform — agents, teams, workflows
`webhook`	Generic webhook — POST events to any URL
`openclaw`	OpenClaw gateway via WebSocket
`ag-ui`	AG-UI protocol
`claude-code`	Claude Code CLI as agent backend
`a2a`	Agent-to-agent protocol
`genie`	Genie team inbox integration (alias)
`nats-genie`	Genie via NATS — canonical name; required for new providers using the NATS transport

`omni providers list`

List all providers.

1omni providers list [options]

Option	Description
`--active`	Show only active providers

12omni providers list
omni providers list --active

`omni providers get`

Get full details of a provider.

1omni providers get <id>

`omni providers create`

Create a new provider.

1omni providers create [options]

Common Options

Option	Description
`--name <name>`	Provider name (unique)
`--schema <schema>`	Provider schema (see table above)
`--base-url <url>`	API base URL (`ws://` or `wss://` for OpenClaw)
`--api-key <key>`	API key
`--description <desc>`	Provider description
`--timeout <seconds>`	Default timeout in seconds (default: 60)
`--stream`	Enable streaming by default

Claude Code Options

Option	Description
`--project-path <path>`	Project directory path (required)
`--max-turns <number>`	Max conversation turns
`--permission-mode <mode>`	`default`, `acceptEdits`, `bypassPermissions`, `plan`
`--model <model>`	Model override
`--system-prompt <prompt>`	System prompt prepended to agent

Genie Options

Option	Description
`--agent-name <name>`	Agent identity / "from" field (required)
`--target-agent <name>`	Target agent inbox to deliver to (required)
`--team-name <template>`	Team name template — supports `{chat_id}`, `{thread_id}`, `{sender_id}` (default: `omni-{chat_id}`)

OpenClaw Options

Option	Description
`--default-agent-id <id>`	Default agent ID (required)

Examples

1234567891011121314151617181920212223242526272829# Create a webhook provider
omni providers create \
  --name "my-webhook" \
  --schema webhook \
  --base-url https://example.com/api/hook

# Create a Claude Code provider
omni providers create \
  --name "code-agent" \
  --schema claude-code \
  --project-path /home/user/my-project \
  --permission-mode acceptEdits \
  --model sonnet

# Create a Genie provider
omni providers create \
  --name "genie-sofia" \
  --schema genie \
  --agent-name sofia \
  --target-agent team-lead \
  --team-name "omni-{chat_id}"

# Create an Agno provider
omni providers create \
  --name "agno-prod" \
  --schema agno \
  --base-url https://api.agno.com \
  --api-key <key> \
  --stream

`omni providers update`

Update a provider's configuration.

1omni providers update <id> [options]

Option	Description
`--name <name>`	New name
`--base-url <url>`	New base URL
`--api-key <key>`	New API key
`--description <desc>`	New description
`--timeout <seconds>`	New timeout
`--stream` / `--no-stream`	Enable or disable streaming
`--active` / `--no-active`	Activate or deactivate
`--schema-config <json>`	Raw schemaConfig as JSON (overrides individual flags)

Schema-specific options (--project-path, --agent-name, --target-agent, etc.) are also available on update.

12345678# Deactivate a provider
omni providers update <id> --no-active

# Change model for Claude Code provider
omni providers update <id> --model opus

# Update raw schema config
omni providers update <id> --schema-config '{"maxTurns": 20}'

`omni providers delete`

Delete a provider.

1omni providers delete <id> [options]

Option	Description
`--force`	Skip confirmation

`omni providers test`

Test a provider's health and connectivity.

1omni providers test <id>

12omni providers test <id>
# Output: ✓ Provider "my-webhook" is healthy

`omni providers setup`

Interactive setup wizards that guide you through creating a provider with all required configuration.

`omni providers setup openclaw`

Set up an OpenClaw provider — generates keypairs, pairs the device, and creates the provider.

1omni providers setup openclaw [options]

Option	Description
`--gateway-url <url>`	Gateway WebSocket URL
`--gateway-token <token>`	Gateway authentication token
`--agent-id <id>`	Default agent ID
`--name <name>`	Provider name (default: `openclaw-<agent-id>`)
`--instance-id <uuid>`	Omni instance UUID for the channel account
`--account-name <name>`	Account name in openclaw.json
`--plugin-path <path>`	Path to omni.ts plugin entry (auto-detected)
`--skip-openclaw-config`	Skip openclaw.json updates
`--non-interactive`	Error on missing flags instead of prompting

`omni providers setup genie`

Set up a Genie provider — configures Claude Code team inbox integration.

1omni providers setup genie [options]

Option	Description
`--agent-name <name>`	Agent identity / "from" field
`--target-agent <name>`	Target agent inbox
`--team-name <template>`	Team name template
`--agent-role <role>`	Registered genie dir agent name (default: `team-lead`)
`--name <name>`	Provider name (default: `genie-<agent-name>`)
`--base-url <url>`	Base URL
`--instance-id <uuid>`	Omni instance UUID to auto-assign
`--non-interactive`	Error on missing flags instead of prompting

Agno Resource Listing

For Agno providers, you can list remote resources:

12345678# List agents registered with an Agno provider
omni providers agents <id>

# List teams
omni providers teams <id>

# List workflows
omni providers workflows <id>

Handoff payload (Gupshup)

When a Gupshup provider triggers a human handoff via POST /v2/messages/handoff, the request body now uses structured fields. The legacy extra_info is still accepted but new integrations should send dadosLead and motivoHandoff.

Field	Type	Required	Description
`instanceId`	uuid	yes	Gupshup instance ID
`chatId`	string	yes	Chat ID to pause the agent on
`to`	string	yes	Recipient phone number
`text`	string	yes	Message text shown to the end user
`dadosLead`	string	no	Free-text lead-data summary for the human attendant
`motivoHandoff`	string	no	Handoff trigger and notes (e.g. `"Gatilho: sinalizou close \|\|\| Obs: ..."`)
`extraInfo`	string	no	Legacy — prefer `dadosLead`. Still accepted as a fallback.
`handoffFields`	object	no	Structured fields for Gupshup flow variables (e.g. `nome`, `cidade`, `temperatura_lead`)

123456789101112curl -X POST https://omni.example.com/v2/messages/handoff \
  -H "Authorization: Bearer $OMNI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "0c6f8...",
    "chatId": "5511...",
    "to": "+5511999999999",
    "text": "Um atendente humano vai continuar de onde a IA parou.",
    "dadosLead": "Cliente perguntou sobre desconto em planos enterprise",
    "motivoHandoff": "Gatilho: pediu humano ||| Obs: lead quente",
    "handoffFields": { "nome": "Maria", "cidade": "Curitiba", "temperatura_lead": "quente" }
  }'

If both dadosLead and extraInfo are sent, dadosLead wins; the legacy field is silently ignored. motivoHandoff is appended to the Gupshup notification only when present.

The handoffFields object maps directly onto Gupshup template variables. Keys you don't define in your Gupshup flow are dropped server-side.

Ask AI about this page