OmniClaw (Alpha) 🐾

中文说明

OmniClaw is an "active" intelligent application gateway supporting multi-channel access. It acts as a bridge between various Instant Messaging (IM) platforms and powerful AI execution engines.

The core philosophy of OmniClaw is "Configure once, run anywhere"—letting AI return to its essence as a tool while providing a unified gateway for interaction.

Inspired by paperclipai/paperclip, opencode, and openclaw.

---

📖 Table of Contents

• 🏗️ Architecture
• 🌟 Core Features
• 🚀 Quick Start
• 🛠️ Advanced Features
• 📂 Directory Structure
• 🛡️ Security & Privacy
• 🎯 Roadmap

---

🏗️ Architecture

graph LR
    %% Main Flow
    subgraph IM ["Gateways (IM Platforms)"]
        direction TB
        FS[Feishu / Lark]
        WC[WeChat]
        TG[Telegram]
        TM[Terminal]
    end

    subgraph Core ["OmniClaw Core (Orchestrator)"]
        direction TB
        Brain{{"Brain (Context Manager)"}}
        HB([Heartbeat Engine])
        Logic[("Identity & Memory<br/>SOUL.md / MEMORY.md")]
    end

    subgraph AI ["Executors (Pluggable AI)"]
        direction TB
        OC[Opencode]
        CC[Claude Code]
        EXT["Custom Adapters"]
    end

    subgraph Target ["World (Execution)"]
        direction TB
        SysFS[[File System]]
        Shell[[CLI / Shell]]
        Web[[External APIs]]
    end

    %% Connections
    IM <--> Brain
    HB -.-> Brain
    Brain <--> Logic
    Brain <--> AI
    AI <--> Target

    %% Styling
    style Brain fill:#f9f,stroke:#333,stroke-width:2px
    style Logic fill:#e1f5fe,stroke:#01579b
    style HB fill:#fff9c4,stroke:#fbc02d

Loading

---

🔄 Workflows

Message Processing Flow: User Message ➔ IM Gateway ➔ OmniClaw Brain ➔ AI Executor ➔ Target Environment

1. Input: User sends a request (via Feishu/WeChat/TG/Terminal).
2. Orchestration: Brain loads context, SOUL, and AGENTS rules.
3. Execution: AI Executor (Opencode/Claude) performs CLI tasks.
4. Feedback: Results are logged in MEMORY and sent back to the User.

---

🌟 Core Features

1. Multi-Channel Gateway (IM Integration)

OmniClaw decouples interaction from logic. Connect your AI to any platform with a single configuration:

• 🏢 Feishu/Lark: Enterprise-grade bot integration. Supports interactive cards (Card Schema 2.0), rich text rendering, smart image compression, and "thinking" indicators.
• 💬 WeChat: Personal/Group chat integration using Wechaty.
• 📮 Telegram: Full bot integration via Long Polling (no public HTTPS or webhook setup required). Supports text, images, files, Markdown→HTML auto-conversion, message chunking, and "⏳ processing" indicators.
• 💻 Terminal: Direct CLI interaction for local development.

2. Pluggable AI Core (Interchangeable Executors)

OmniClaw is designed to be AI framework agnostic. The underlying "Brain" can be swapped with different executors by setting a single environment variable:

Executor	Mechanism	Best For
opencode	Spawns opencode serve as a local REST server; sessions are persistent	Complex CLI automation, long-running tasks
claude	Runs claude --print … --output-format stream-json; sessions maintained via --resume	High-reasoning development, quick Q&A

Custom Adapters: Implement the BaseExecutor abstract class in src/executor/ to bridge any other AI framework.

3. Active Heartbeat Engine

Unlike traditional "passive-response" bots, OmniClaw features a built-in heartbeat system. It "wakes up" autonomously to monitor builds, crawl data, or generate reports, proactively notifying you on your preferred IM channel.

4. Identity & Soul (Unified Persona)

Maintain a consistent AI persona across all platforms:

• SOUL.md: Your AI's character, values, and communicative style.
• AGENTS.md: Task-specific rules and tool usage protocols.
• MEMORY.md: Shared long-term memory across sessions and platforms.
• Search & Deduplication: Built-in fingerprinting to prevent message redelivery; automated Daily Logs for easy session auditing.

---

🚀 Quick Start

Prerequisites

• Node.js (v18+ recommended)
• At least one AI executor installed:
  • opencode (default): Install from opencode.ai, verify with opencode --version
  • Claude Code: Install from claude.ai/code, verify with claude --version

1. Configuration

Copy .env.example and fill in your API keys:

cp .env.example .env

Key configurations:

Variable	Description	Default
EXECUTOR	AI backend: opencode or claude	opencode
FEISHU_APP_ID	Feishu bot App ID	—
FEISHU_APP_SECRET	Feishu bot App Secret	—
TELEGRAM_BOT_TOKEN	Telegram bot token (from @BotFather)	—
TRIGGER_PORT	Port for the Trigger HTTP API	3099

Setting Up a Telegram Bot

1. Open Telegram and chat with @BotFather.
2. Send /newbot and follow the prompts (choose a name and username).
3. Copy the token (format: 7xxxxxxxxxx:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx) into your .env:

   TELEGRAM_BOT_TOKEN=7xxxxxxxxxx:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. OmniClaw uses Long Polling — no public HTTPS endpoint or webhook registration is needed. Just run and it works.

Scheduled task receivers for Telegram: use "type": "chat_id" with the numeric chat/group ID (e.g. "id": "123456789"). You can get your chat ID by messaging @userinfobot.

Switching AI Executors

Set EXECUTOR in your .env to choose the AI backend:

# Use opencode (default, requires opencode installed)
EXECUTOR=opencode

# Use Claude Code CLI (requires claude installed and authenticated)
EXECUTOR=claude

# Use Claude Code at a custom binary path
EXECUTOR=claude:/usr/local/bin/claude

2. Installation & Running

1. Install Dependencies:

   npm install

2. Development Mode: Start directly with ts-node (built-in TerminalGateway):

   npm run dev

3. Production Mode:

   npm run build
   npm start

---

🛠️ Advanced Features

System Optimizations

• Persistent Sessions: Both executors maintain session context across messages — opencode via headless REST sessions, claude via --resume <session-id>.
• Trigger API: POST endpoints to immediately trigger AI tasks from external webhooks.

Automated Tasks (Schedules)

Place .json config files in the schedules/ directory. OmniClaw supports Hot-Reloading, meaning changes take effect immediately without restarting.

Config Template (schedules/daily_report.json):

Feishu:

{
  "id": "daily_report",
  "cron": "0 9 * * *",
  "gateway": "feishu",
  "receiver": {
    "type": "chat_id",
    "id": "oc_xxxxxxxxxxxxxxxx"
  },
  "prompt": "Please summarize yesterday's project progress and list today's to-do items."
}

Telegram:

{
  "id": "daily_report",
  "cron": "0 9 * * *",
  "gateway": "telegram",
  "receiver": {
    "type": "chat_id",
    "id": "123456789"
  },
  "prompt": "Please summarize yesterday's project progress and list today's to-do items."
}

• Supports Cron expressions.
• Specify target Gateways (feishu, telegram, terminal) and receivers (chat_id / user_id).

Slash Commands

Built-in management commands to control the system bypass the AI:

• /cmd <command>: Run arbitrary shell command on the server and return output.
• /build: Trigger project build (npm run build).
• /restart: Rebuild and then self-respawn the OmniClaw process.
• /log [lines]: Tail the last N lines (default 100) of the execution log.
• /help: Display the list of available commands and usage guide.

---

📂 Directory Structure

omniclaw/
├── src/
│   ├── gateway/     # IM Adapters (Feishu, WeChat, TG, etc.)
│   ├── executor/    # Opencode/CLI child process management
│   ├── engine/      # Core logic (Brain, Heartbeat, Memory)
│   └── index.ts     # Entry point
├── schedules/       # Cron task configurations (JSON)
├── memory/          # Daily conversation and task logs
├── SOUL.md          # Soul/Personality definition
├── AGENTS.md        # Behavioral guidelines/Tool specs
└── package.json     # Dependencies & scripts

---

🛡️ Security & Privacy

• Credential Isolation: All sensitive keys should be stored in the .env file or secrets/ directory. The project includes a .gitignore to prevent these files from being committed.
• Local Logs: logs/ and memory/ directories are stored locally only, used to maintain persistent AI memory and for debugging.
• Open Source Tip: If you plan to clone and redistribute this project, ensure you remove sensitive information from the .git history if it was ever accidentally committed.

---

🎯 Roadmap

• Memory Enhancement: Implement vector-based long-term memory and RAG (Retrieval-Augmented Generation) for deeper project context.
• OpenClaw Gateway Support: Full compatibility with the OpenClaw protocol to enable cross-agent communication (A2A).
• Plugin Ecosystem: Support for third-party tools and custom IM adapters.

---

📄 License

ISC License. Built for autonomous productivity.