feat: integrate ii-claw-runtime into II-Agent System

[namtranii]

Demo ii-claw-runtime:
https://drive.google.com/file/d/1d2pb-1_GBGoJV69ZfFcEFgF2osKjgRYi/view

Integrating OpenClaw-like Capabilities into II-Agent System

OpenClaw has demonstrated the power of a personal assistant machine — an always-running AI that can reason, plan, execute tasks, and interact with a user's environment autonomously. It transforms AI from a simple chat interface into a persistent, task-oriented assistant capable of real-world automation.

Question: How do we integrate OpenClaw with II-Agent?

II-Agent already has the core AI capabilities: an agent loop, task execution in sandboxes, and multiple agent modes (research agent, media agent, website agent, etc.). The question is how to bring OpenClaw's always-on, channel-connected assistant pattern into the II-Agent architecture.

One Approach: Clone OpenClaw and run it inside a sandbox

In this setup:

• Clone and initialize OpenClaw directly inside a sandbox environment
• Each sandbox acts as a personal machine for the user
• OpenClaw runs inside the sandbox as a personal assistant, controlling the environment — executing tasks, managing files, running commands, as if the sandbox were its own machine
• Users interact with OpenClaw through its built-in channel adapters (Telegram, Discord, etc.)

Advantages

• Full OpenClaw capability out of the box — no need to rebuild its features
• Strong isolation per user — each sandbox is a self-contained environment
• Users get the original OpenClaw experience and can leverage its existing workflows and extensions
• Flexible — users can customize their OpenClaw instance however they want

Limitations

However, this approach introduces significant challenges for a multi-user platform:

• Primarily suitable for premium users or those who specifically need the full original OpenClaw experience
• Requires always-running sandbox instances — OpenClaw must stay alive to maintain connections to channel adapters, which means sandboxes cannot be spun down between interactions
• The sandbox must maintain persistent connections to channel adapters (Telegram bot polling, Discord gateway, etc.), adding complexity to sandbox lifecycle management
• High infrastructure cost — supporting many users means many always-running sandboxes simultaneously, which is very expensive in terms of compute and memory
• Difficult to scale horizontally — each user requires a dedicated sandbox, making it hard to serve a large user base efficiently
• Increased operational complexity — managing sandbox lifecycle, monitoring health, handling crashes and recovery across many instances
• Slower cold start — spinning up a full OpenClaw environment in a sandbox takes time compared to a purpose-built service

My Approach: Extract OpenClaw patterns and build ii-claw-runtime

Instead of running full OpenClaw instances per user, we extract the key architectural patterns from OpenClaw — channel connectivity, message routing, scheduling — and build ii-claw-runtime, a dedicated Backend Runtime that integrates these capabilities directly into II-Agent.

We built ii-claw-runtime using Rust that serves as:

• Channel relay — connecting to messaging platforms and bridging messages to/from II-Agent
• Scheduler — per-user cron jobs for scheduled autonomous tasks
• Message router — stamping user_id, agent_id, instance_name onto each message so II-Agent knows who sent what and which agent should handle it
• Multi-user channel config — users configure their own channel adapters (Telegram bots, Discord bots, etc.) via REST API, stored in PostgreSQL

How it works:

When users send messages via channel adapters (Telegram, Discord, Slack, WhatsApp, etc.):

1. Message is received by ii-claw-runtime
2. ii-claw-runtime looks up the channel config in PostgreSQL, stamps user context (user_id, agent_id), and forwards to II-Agent via HMAC-signed webhook
3. II-Agent receives the payload, routes to the correct agent mode (research, media, website, etc.), and executes with sandbox as needed
4. II-Agent sends the result back by calling ii-claw-runtime's send API, which delivers the response to the user on their messaging channel

For scheduled tasks, ii-claw-runtime's cron scheduler can trigger II-Agent actions on a schedule — for example, sending a daily research report or running periodic monitoring tasks.

Supported Use Cases

This architecture enables:

• Persistent personal assistants — users can chat with their AI agents on any messaging platform, anytime
• Multi-agent routing — different channels route to different II-Agent agent modes (research agent on Telegram, media agent on Discord, etc.)
• Scheduled autonomous tasks — cron jobs trigger II-Agent tasks automatically (daily reports, periodic research, automated monitoring)
• Cross-channel interactions — the same user can interact with II-Agent across multiple platforms
• Background automation — scheduled tasks run without user intervention

Why This Approach Is More Efficient

• No always-running sandbox per user — ii-claw-runtime is a single shared service; II-Agent only spins up sandboxes when it needs to execute tasks, then releases them
• Better resource efficiency — one Rust process (ii-claw-runtime) handles channel connections for all users, rather than one sandbox per user
• Scalable multi-user architecture — adding users means adding rows in PostgreSQL, not additional running processes
• Centralized channel management — one place to manage all channel connections, routing, and scheduling
• Faster response — no cold start overhead; ii-claw-runtime is always ready to receive and forward messages
• Lower operational complexity — a single service is easier to monitor, deploy, and recover than hundreds of sandbox instances

Future Potential

ii-claw-runtime currently serves as a channel relay and scheduler — it receives messages, forwards them, and runs cron jobs. With this foundation in place, there is significant room to evolve it into a more capable orchestration layer:

• Workflow engine — extend ii-claw-runtime with workflow state management so it can coordinate multi-step tasks: dispatch step 1 to II-Agent, wait for the result, then dispatch step 2, and so on. Currently it only does fire-and-forget; adding state tracking would enable complex pipelines.
• Multi-agent pipelines — building on the workflow engine, chain II-Agent agents together (research → analyze → generate report → send to user) where ii-claw-runtime orchestrates the sequence and passes context between steps.
• Event-driven automation — extend beyond time-based cron schedules to support event triggers: react to external webhooks, channel events, or conditions (e.g., "when a new message mentions keyword X, trigger research agent").
• Long-running autonomous agents — ii-claw-runtime could manage agent sessions that persist over days or weeks, periodically triggering II-Agent to continue work and reporting progress to users on their channels.
• User-defined workflows — expose a workflow definition API so users can compose their own automation: combine scheduling, channel routing, conditional logic, and multi-agent coordination without writing code.

The key insight is that ii-claw-runtime's current architecture — multi-user channel management, cron scheduling, message routing via PostgreSQL — already provides the building blocks for these capabilities. The evolution path is from relay → scheduler → orchestrator.

Beyond the Baseline: OpenClaw-Inspired Patterns for II-Agent

Building on this baseline, there are several richer patterns from OpenClaw that we can adapt and integrate into the II-Agent system. These go beyond simple channel relay and scheduling, and move toward a fully autonomous, multi-agent ecosystem:

• Sandboxed agents speaking A2A — instead of (or in addition to) running II-Agent's built-in modes, we can spin up OpenClaw-style personal assistant agents inside isolated sandboxes and connect them to II-Agent through the A2A (Agent-to-Agent) protocol. Each sandboxed agent becomes a first-class participant that II-Agent can discover, delegate to, and collaborate with — while ii-claw-runtime handles the messaging and lifecycle plumbing.

• Agent Teams and Orchestration — model groups of specialized agents (researcher, coder, reviewer, planner, executor) as Agent Teams coordinated by an orchestrator agent. ii-claw-runtime can act as the team's "switchboard," routing tasks between teammates, managing shared state, and handling handoffs. This unlocks autonomous workflows where a user request triggers a team of agents that collaboratively plan, execute, critique, and deliver the result.

• Autonomous workflow execution — combine the workflow engine, Agent Teams, and event-driven triggers to support fully autonomous workflows: long-horizon goals that the system decomposes, schedules, monitors, and completes on its own — checking back in with the user only when input is needed or when the goal is achieved.

• Shared memory and knowledge layer — extend the PostgreSQL backbone with a per-user long-term memory store (vector + structured) that all of a user's agents can read from and write to. This gives agent teams persistent context across conversations, channels, and sessions, so the assistant truly "knows" the user over time.

• Human-in-the-loop checkpoints — for sensitive or high-stakes steps in a workflow (sending money, publishing content, deleting data), ii-claw-runtime can pause the workflow and reach out to the user on their preferred channel (Telegram, Discord, etc.) for confirmation, then resume execution once approved. This blends autonomy with safety.

• Cross-user agent collaboration — because ii-claw-runtime already understands user_id and agent_id, it can mediate inter-user agent communication: my research agent can ask your data agent for a dataset (with permission), enabling teams of humans and their agents to collaborate on shared projects.

• Self-improving agents via feedback loops — capture user reactions, corrections, and channel signals (thumbs up/down, replies) through ii-claw-runtime, feed them back into the agents' memory and prompts, and let agents iteratively refine their behavior per user over time.

• Marketplace of agent templates — package proven agent configurations (e.g., "Daily News Briefing Agent," "GitHub Triage Agent," "Trading Signal Agent") as reusable templates that any user can install into their account with one click; ii-claw-runtime provisions the channel bindings, cron schedules, tools, and prompts automatically.

Together, these directions turn the II-Agent + ii-claw-runtime stack into much more than a chat interface: a multi-tenant, multi-agent operating system for personal AI — combining OpenClaw's always-on assistant philosophy with II-Agent's strong agentic core and sandbox execution.

This approach provides a scalable, OpenClaw-inspired architecture while maintaining efficiency and flexibility for the II-Agent multi-user platform.

---

Installation

Prerequisites

Make sure II-Agent is running:

• Backend at http://localhost:8000
• Frontend at http://localhost:1420

Install ii-claw-runtime

Pull the Docker image from DockerHub:

docker pull namtranii/ii-claw-runtime

Note: The Rust source code for ii-claw-runtime will be open-sourced in the future.

Run ii-claw-runtime

docker run -d \
  -p 4200:4200 \
  --add-host=host.docker.internal:host-gateway \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/ii_claw_runtime" \
  -e II_CLAW_API_KEY="5c3e2f56de9411068f675ef32ffa12735210b9cbfee2ba521367a3955334a343" \
  -e AI_WEBHOOK_URL=http://host.docker.internal:8000/ii-claw/webhook/inbound \
  -e AI_WEBHOOK_SECRET=ii-claw-webhook-secret \
  namtranii/ii-claw-runtime:latest

Once running, ii-claw-runtime is available at http://localhost:4200.

Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string. Create a new database for ii-claw-runtime (e.g., ii_claw_runtime). Tables are auto-created on first startup via migrations.
II_CLAW_API_KEY	API key for authenticating requests to ii-claw-runtime. This key is hardcoded in the config (backend II-Agent). Generate one with: echo -n "message" | openssl dgst -sha256 -hmac
AI_WEBHOOK_URL	The II-Agent endpoint that ii-claw-runtime forwards inbound messages to.
AI_WEBHOOK_SECRET	Shared secret used to HMAC-sign webhook payloads sent from ii-claw-runtime to II-Agent, so II-Agent can verify the request is authentic.

---

System Overview

                 ┌──────────────────────────────────────┐
                 │        External AI Backend            │
                 │   (your LLM app, any language)        │
                 └───────┬──────────────────┬────────────┘
                    ▲    │                  │
         webhook   │    │ async response   │ cron webhook
         forward   │    ▼                  ▼
              ┌────┴────────────────────────────────┐
              │         ii_claw_api (axum)           │
              │   /api/users/{id}/channels/*/send    │
              │   /api/users/{id}/channels/*/configure│
              │   /api/users/{id}/cron/jobs/*        │
              │   /hooks/wake                        │
              │   /api/health                        │
              └───┬──────────┬───────────┬───────┬───┘
                  │          │           │       │
          ┌───────┴───┐ ┌───┴─────┐ ┌───┴────┐ ┌┴──────────┐
          │ ii_claw_   │ │ ii_claw_│ │ii_claw_│ │ ii_claw_  │
          │ channels   │ │scheduler│ │ types  │ │ db        │
          │ (bridge)   │ │ (cron)  │ │(config)│ │(postgres) │
          └─────┬──────┘ └────────┘  └────────┘ └───────────┘
                │
    ┌───────────┼───────────┬───────────┐
    │           │           │           │
┌───┴──┐  ┌────┴──┐  ┌─────┴──┐  ┌────┴───┐
│Telegram│ │Discord│  │ Slack  │  │WhatsApp│  ...
└───────┘ └───────┘  └────────┘  └────────┘
    │           │           │           │
    └───────────┴───────────┴───────────┘
                    │
              End Users (messaging apps)

Multi-User Architecture

  Backend AI (user_id=abc-123)         Backend AI (user_id=def-456)
         │                                    │
         ▼                                    ▼
  POST /api/users/abc-123/             POST /api/users/def-456/
       channels/agent/configure              channels/my-bot/configure
         │                                    │
         ▼                                    ▼
  ┌──────────────────────────────────────────────────────┐
  │                   ii_claw_api                         │
  │                                                      │
  │  IIClawState                                         │
  │  ├── user_adapters: HashMap<AdapterKey, Adapter>     │ ← multi-user (DB)
  │  ├── db_pool: PgPool                                 │
  │  └── bridge_manager                                  │
  └──────────┬───────────────────────────┬───────────────┘
             │                           │
             ▼                           ▼
  ┌──────────────────┐        ┌──────────────────┐
  │ AdapterKey        │        │ AdapterKey        │
  │ user=abc-123      │        │ user=def-456      │
  │ instance="agent"  │        │ instance="my-bot" │
  │ → DiscordAdapter  │        │ → TelegramAdapter │
  └──────────────────┘        └──────────────────┘
             │                           │
             ▼                           ▼
     Discord Server A            Telegram Bot B