omniagent

module

v0.8.0 Latest Latest Go to latest Published: May 3, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/plexusone/omniagent

Links

Open Source Insights

README ¶

OmniAgent

Your AI representative across communication channels.

OmniAgent is a personal AI assistant that routes messages across multiple communication platforms, processes them via an AI agent, and responds on your behalf.

Features

💬 Multi-Channel Support - Telegram, Discord, Slack, WhatsApp, and more
🤖 AI-Powered Responses - Powered by omnillm (Claude, GPT, Gemini, etc.)
🎤 Voice Notes - Transcribe incoming voice, respond with synthesized speech via OmniVoice
🧩 Skills System - Markdown skills (OpenClaw compatible) and compiled Go skills
💾 Persistent Sessions - Conversation history with SQLite storage via omnistorage-core
⏰ Scheduled Jobs - Cron expressions, intervals, and one-time job scheduling
🔒 Secure Sandboxing - WASM and Docker isolation for tool execution
🌐 Browser Automation - Built-in browser control via Rod
🔌 WebSocket Gateway - Real-time control plane for device connections
📊 Observability - Integrated tracing via omniobserve

Installation

go install github.com/plexusone/omniagent/cmd/omniagent@latest

Quick Start

WhatsApp + OpenAI

The fastest way to get started is with WhatsApp and OpenAI:

# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."

# Run with WhatsApp enabled
OMNIAGENT_AGENT_PROVIDER=openai \
OMNIAGENT_AGENT_MODEL=gpt-4o \
WHATSAPP_ENABLED=true \
omniagent gateway run

A QR code will appear in your terminal. Scan it with WhatsApp (Settings -> Linked Devices -> Link a Device) to connect.

Configuration File

For more control, create a configuration file:

# omniagent.yaml
gateway:
  address: "127.0.0.1:18789"

agent:
  provider: openai          # or: anthropic, gemini
  model: gpt-4o             # or: claude-sonnet-4-20250514, gemini-2.0-flash
  api_key: ${OPENAI_API_KEY}
  system_prompt: "You are OmniAgent, responding on behalf of the user."

channels:
  whatsapp:
    enabled: true
    db_path: "whatsapp.db"  # Session storage

  telegram:
    enabled: false
    token: ${TELEGRAM_BOT_TOKEN}

  discord:
    enabled: false
    token: ${DISCORD_BOT_TOKEN}

  twilio_sms:
    enabled: false
    account_sid: ${TWILIO_ACCOUNT_SID}
    auth_token: ${TWILIO_AUTH_TOKEN}
    phone_number: ${TWILIO_PHONE_NUMBER}
    webhook_path: /webhook/twilio/sms

voice:
  enabled: true
  response_mode: auto        # auto, always, never
  stt:
    provider: deepgram
    model: nova-2
  tts:
    provider: deepgram
    model: aura-asteria-en
    voice_id: aura-asteria-en

skills:
  enabled: true
  paths:                     # Additional skill directories
    - ~/.omniagent/skills
  max_injected: 20           # Max skills to inject into prompt

Run with the config file:

omniagent gateway run --config omniagent.yaml

Skills

OmniAgent supports skills compatible with the OpenClaw SKILL.md format. Skills extend the agent's capabilities by injecting domain-specific instructions into the system prompt.

Managing Skills

# List all discovered skills
omniagent skills list

# Show details for a specific skill
omniagent skills info sonoscli

# Check requirements for all skills
omniagent skills check

Skill Format

Skills are defined in SKILL.md files with YAML frontmatter:

---
name: weather
description: Get weather forecasts
metadata:
  emoji: "🌤️"
  requires:
    bins: ["curl"]
  install:
    - name: curl
      brew: curl
      apt: curl
---

# Weather Skill

You can check the weather using the `curl` command...

Skill Discovery

Skills are discovered from:

Built-in skills directory
~/.omniagent/skills/
Custom paths via skills.paths config

Skills with missing requirements (binaries, env vars) are automatically skipped.

Compiled Skills

For better performance and type safety, register Go functions as LLM tools:

import (
    "github.com/plexusone/omniagent/agent"
    "github.com/plexusone/omniagent/skills/compiled"
)

// Create a skill with tools
type WeatherSkill struct{}

func (s *WeatherSkill) Name() string        { return "weather" }
func (s *WeatherSkill) Description() string { return "Weather forecasts" }
func (s *WeatherSkill) Tools() []compiled.Tool {
    return []compiled.Tool{{
        Name:        "get_weather",
        Description: "Get weather for a location",
        Parameters: map[string]compiled.Parameter{
            "location": {Type: "string", Required: true},
        },
        Handler: func(ctx context.Context, params map[string]any) (any, error) {
            return fetchWeather(params["location"].(string))
        },
    }}
}
func (s *WeatherSkill) Init(ctx context.Context) error { return nil }
func (s *WeatherSkill) Close() error                   { return nil }

// Register with agent
agent.New(config, agent.WithCompiledSkill(&WeatherSkill{}))

Remote Skills

Remote skills connect to external services and expose their capabilities as agent tools.

MCP Skills - Spawn external MCP servers and expose their tools:

import "github.com/plexusone/omniagent/skills/remote/mcp"

agent, err := agent.New(config,
    agent.WithMCPSkill(mcp.Config{
        Name:    "github",
        Command: []string{"npx", "-y", "@modelcontextprotocol/server-github"},
        Env: map[string]string{
            "GITHUB_TOKEN": os.Getenv("GITHUB_TOKEN"),
        },
    }),
)

OpenAPI Skills - Parse OpenAPI 3.x specs and expose operations as tools:

import openapi "github.com/plexusone/omniagent/skills/remote/openapi"

agent, err := agent.New(config,
    agent.WithOpenAPISkill(openapi.Config{
        Name:    "petstore",
        SpecURL: "https://petstore3.swagger.io/api/v3/openapi.json",
        Auth: openapi.AuthConfig{
            Type:   openapi.AuthBearer,
            Token:  os.Getenv("API_TOKEN"),
        },
    }),
)

See the Skills Guide for configuration options.

Sessions

OmniAgent supports persistent conversation sessions:

import (
    "github.com/plexusone/omniagent/agent"
    "github.com/plexusone/omnistorage-core/kvs/backend/sqlite"
)

// Create storage backend
backend, _ := sqlite.New(sqlite.Config{Path: "omniagent.db"})

// Create agent with sessions
a, _ := agent.New(config,
    agent.WithSessionsFromStorage(backend),
)

// Process with conversation history
response1, _ := a.ProcessWithSession(ctx, "user-123", "My name is Alice")
response2, _ := a.ProcessWithSession(ctx, "user-123", "What's my name?")
// Agent remembers: "Your name is Alice"

See Sessions Guide for details.

Scheduled Jobs

OmniAgent supports scheduled job execution via the cron package:

import (
    "github.com/plexusone/omniagent/agent"
    "github.com/plexusone/omnistorage-core/kvs/backend/sqlite"
)

// Create agent with cron support
backend, _ := sqlite.New(sqlite.Config{Path: "omniagent.db"})
a, _ := agent.New(config,
    agent.WithSessionsFromStorage(backend),
    agent.WithCronScheduler(),
)

The LLM can then create scheduled jobs via tool calls:

Tool	Description
`cron_create`	Create a new scheduled job
`cron_list`	List all jobs (filterable by status)
`cron_get`	Get job details
`cron_delete`	Delete a job
`cron_enable`	Enable a disabled job
`cron_disable`	Disable without deleting
`cron_trigger`	Run job immediately

Schedule types:

Cron expressions: 0 0 9 * * * (9am daily, with seconds)
Intervals: 1h, 30m, 24h
One-time: RFC3339 timestamp for single execution

Action types:

send_message - Send a message to a session
call_webhook - Make an HTTP request
call_tool - Invoke a registered tool

See Cron Guide for details.

Sandboxing

OmniAgent provides layered security for tool execution:

App-Level Permissions

Capability-based permissions control what tools can do:

fs_read - Read files from allowed paths
fs_write - Write files to allowed paths
net_http - Make HTTP requests to allowed hosts
exec_run - Execute allowed commands

Docker Isolation

For OS-level isolation, tools can run inside Docker containers:

sandbox, _ := sandbox.NewDockerSandbox(ctx, sandbox.DockerConfig{
    Image:       "alpine:latest",
    NetworkMode: "none",           // No network access
    CapDrop:     []string{"ALL"},  // Drop all capabilities
    Mounts: []sandbox.DockerMount{
        {HostPath: "/tmp/data", ContainerPath: "/data", ReadOnly: true},
    },
}, &appConfig)

result, _ := sandbox.Run(ctx, "cat", []string{"/data/file.txt"})

WASM Runtime

For lightweight isolation, tools can run in a WASM sandbox (wazero):

runtime, _ := sandbox.NewRuntime(ctx, sandbox.Config{
    Capabilities:  []sandbox.Capability{sandbox.CapFSRead},
    MemoryLimitMB: 16,
    Timeout:       30 * time.Second,
    AllowedPaths:  []string{"/tmp/data"},
})

Environment Variables

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`GEMINI_API_KEY`	Google Gemini API key
`OMNIAGENT_AGENT_PROVIDER`	LLM provider: `openai`, `anthropic`, `gemini`
`OMNIAGENT_AGENT_MODEL`	Model name (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
`WHATSAPP_ENABLED`	Set to `true` to enable WhatsApp
`WHATSAPP_DB_PATH`	WhatsApp session storage path
`TELEGRAM_BOT_TOKEN`	Telegram bot token (auto-enables Telegram)
`DISCORD_BOT_TOKEN`	Discord bot token (auto-enables Discord)
`TWILIO_ACCOUNT_SID`	Twilio Account SID (auto-enables SMS)
`TWILIO_AUTH_TOKEN`	Twilio Auth Token
`TWILIO_PHONE_NUMBER`	Twilio phone number in E.164 format
`TWILIO_WEBHOOK_PATH`	SMS webhook path (default: `/webhook/twilio/sms`)
`SERPER_API_KEY`	Serper API key for web search
`SERPAPI_API_KEY`	SerpAPI key for web search (alternative)
`DEEPGRAM_API_KEY`	Deepgram API key for voice STT/TTS
`OMNIAGENT_VOICE_ENABLED`	Set to `true` to enable voice processing
`OMNIAGENT_VOICE_RESPONSE_MODE`	Voice response mode: `auto`, `always`, `never`

CLI Commands

# Gateway
omniagent gateway run      # Start the gateway server

# Skills
omniagent skills list      # List all discovered skills
omniagent skills info NAME # Show skill details
omniagent skills check     # Validate skill requirements

# Channels
omniagent channels list    # List registered channels
omniagent channels status  # Show channel connection status

# Config
omniagent config show      # Display current configuration

# Version
omniagent version          # Show version information

Architecture

+-------------------------------------------------------------+
|                     Messaging Channels                      |
|     Telegram  |  Discord  |  Slack  |  WhatsApp  |  ...     |
+---------------------------+---------------------------------+
                            |
+---------------------------v---------------------------------+
|              Gateway (WebSocket Control Plane)              |
|              ws://127.0.0.1:18789                           |
+---------------------------+---------------------------------+
                            |
+---------------------------v---------------------------------+
|                      Agent Runtime                          |
|  +------------------+  +------------------+                 |
|  |    Skills        |  |    Sandbox       |                 |
|  |  (SKILL.md)      |  |  (WASM/Docker)   |                 |
|  +------------------+  +------------------+                 |
|  - omnillm (LLM providers)                                  |
|  - omnivoice (STT/TTS)                                      |
|  - omniobserve (tracing)                                    |
|  - Tools (browser, shell, http)                             |
+-------------------------------------------------------------+

Configuration Reference

Gateway

Field	Type	Default	Description
`gateway.address`	string	`127.0.0.1:18789`	WebSocket server address
`gateway.read_timeout`	duration	`30s`	Read timeout
`gateway.write_timeout`	duration	`30s`	Write timeout
`gateway.ping_interval`	duration	`30s`	WebSocket ping interval

Agent

Field	Type	Default	Description
`agent.provider`	string	`anthropic`	LLM provider
`agent.model`	string	`claude-sonnet-4-20250514`	Model name
`agent.api_key`	string	-	API key (or use env var)
`agent.temperature`	float	`0.7`	Sampling temperature
`agent.max_tokens`	int	`4096`	Max response tokens
`agent.system_prompt`	string	-	Custom system prompt

Skills

Field	Type	Default	Description
`skills.enabled`	bool	`true`	Enable skill loading
`skills.paths`	[]string	`[]`	Additional skill directories
`skills.disabled`	[]string	`[]`	Skills to skip
`skills.max_injected`	int	`20`	Max skills in prompt

Voice

Field	Type	Default	Description
`voice.enabled`	bool	`false`	Enable voice processing
`voice.response_mode`	string	`auto`	`auto`, `always`, `never`
`voice.stt.provider`	string	-	STT provider (e.g., `deepgram`)
`voice.tts.provider`	string	-	TTS provider (e.g., `deepgram`)

Omni* Library Ecosystem

OmniAgent is built on a modular ecosystem of omni* libraries:

                              OmniAgent
                          (Agent Runtime)
    ┌────────┬────────┬────────┬────────┬────────┬────────┐
    ▼        ▼        ▼        ▼        ▼        ▼        ▼
omnichat  omnillm  omnivoice omniobserve omniserp omnistorage ...
    │         │         │                           │
    │    ┌────┴────┐ ┌──┴──┐              ┌─────────┴────────┐
    │    │         │ │     │              │                  │
    ▼    ▼         ▼ ▼     ▼              ▼                  ▼
      omnillm-core   omnivoice-core    omnistorage-core
                                       ├── /object (files)
                                       └── /kvs (sessions)
    │         │         │                           │
    └─────────┴─────────┴───────────────────────────┘
                        │
              Provider Modules
    ┌───────────────────┼───────────────────┐
    ▼                   ▼                   ▼
omni-aws           omni-google         omni-github
├── /omnillm       ├── /omnillm        └── /omnistorage
├── /omnistorage   └── /omnistorage
└── /omnivoice

See Architecture Overview for detailed documentation.

Dependencies

Omni* Libraries

Package	Purpose
omnichat	Unified messaging (WhatsApp, Telegram, Discord)
omnillm	Multi-provider LLM abstraction
omnivoice	Voice STT/TTS interfaces
omniobserve	LLM observability
omniserp	Web search via Serper/SerpAPI
omnistorage-core	Object and key-value storage

Infrastructure

Package	Purpose
wazero	WASM runtime for sandboxing
moby	Docker SDK for container isolation
Rod	Browser automation
gorilla/websocket	WebSocket server

omnichat - Unified messaging provider interface
omnillm - Multi-provider LLM abstraction
omnivoice - Voice interactions
OpenClaw - Compatible skill format

License

MIT License - see LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
agent Package agent provides the AI agent runtime for omniagent.	Package agent provides the AI agent runtime for omniagent.
cmd
omniagent command Package main is the entry point for the omniagent CLI.	Package main is the entry point for the omniagent CLI.
omniagent/commands Package commands implements the omniagent CLI commands.	Package commands implements the omniagent CLI commands.
config Package config provides configuration types and loading for omniagent.	Package config provides configuration types and loading for omniagent.
context Package context provides context management for conversations.	Package context provides context management for conversations.
cron Package cron provides scheduled job execution for omniagent.	Package cron provides scheduled job execution for omniagent.
examples
basic command Package main demonstrates basic omniagent usage.	Package main demonstrates basic omniagent usage.
gateway Package gateway provides the WebSocket control plane for omniagent.	Package gateway provides the WebSocket control plane for omniagent.
hooks Package hooks provides event-driven extensibility for omniagent.	Package hooks provides event-driven extensibility for omniagent.
internal
version Package version provides build and version information for omniagent.	Package version provides build and version information for omniagent.
platform Package platform provides runtime platform abstractions for omniagent.	Package platform provides runtime platform abstractions for omniagent.
standalone Package standalone provides a standalone HTTP server platform for omniagent.	Package standalone provides a standalone HTTP server platform for omniagent.
sandbox Package sandbox provides a WASM-based sandbox for secure code execution.	Package sandbox provides a WASM-based sandbox for secure code execution.
sessions Package sessions provides persistent session management for the agent.	Package sessions provides persistent session management for the agent.
skills Package skills provides OpenClaw/ClawHub skill loading and management.	Package skills provides OpenClaw/ClawHub skill loading and management.
compiled Package compiled provides interfaces for compiled Go skills.	Package compiled provides interfaces for compiled Go skills.
remote/mcp Package mcp provides a compiled.Skill implementation that wraps an MCP server.	Package mcp provides a compiled.Skill implementation that wraps an MCP server.
remote/openapi Package openapi provides a compiled.Skill implementation that wraps an OpenAPI spec.	Package openapi provides a compiled.Skill implementation that wraps an OpenAPI spec.
tools
browser Package browser provides browser automation tools for omniagent.	Package browser provides browser automation tools for omniagent.
shell Package shell provides shell execution tools for omniagent.	Package shell provides shell execution tools for omniagent.
voice Package voice provides voice processing capabilities for omniagent.	Package voice provides voice processing capabilities for omniagent.

README ¶

OmniAgent

Features

Installation

Quick Start

WhatsApp + OpenAI

Configuration File

Skills

Managing Skills

Skill Format

Skill Discovery

Compiled Skills

Remote Skills

Sessions

Scheduled Jobs

Sandboxing

App-Level Permissions

Docker Isolation

WASM Runtime

Environment Variables

CLI Commands

Architecture

Configuration Reference

Gateway

Agent

Skills

Voice

Omni* Library Ecosystem

Dependencies

Omni* Libraries

Infrastructure

Related Projects

License

Directories ¶