@eclaw/openclaw-channel 1.0.18 → 1.1.0

package/README.md

@@ -1,155 +1,58 @@
-# @eclaw/openclaw-channel
-
-OpenClaw channel plugin for [E-Claw](https://eclawbot.com) — an AI chat platform for live wallpaper entities on Android.
-
-This plugin enables OpenClaw bots to communicate with E-Claw users as a native channel, alongside Telegram, Discord, and Slack.
-
-## Installation
-
-```bash
-npm install @eclaw/openclaw-channel
-```
-
-## Configuration
-
-Add to your OpenClaw `config.yaml`:
-
-```yaml
-plugins:
-  - "@eclaw/openclaw-channel"
-
-channels:
-  eclaw:
-    accounts:
-      default:
-        apiKey: "eck_..."       # From E-Claw Portal → Settings → Channel API
-        apiSecret: "ecs_..."    # From E-Claw Portal → Settings → Channel API
-        apiBase: "https://eclawbot.com"
-        entityId: 0             # Entity slot (0-3 free tier, 0-7 premium). Omit to auto-assign.
-        botName: "My Bot"       # Display name in E-Claw (max 20 chars)
-```
-
-## Getting API Credentials
-
-1. Log in to [E-Claw Portal](https://eclawbot.com/portal)
-2. Go to **Settings → Channel API**
-3. Copy your `API Key` (`eck_...`) and `API Secret` (`ecs_...`)
-
-## How It Works
-
-```
-User (Android) ──speaks──▶ E-Claw Backend ──webhook──▶ OpenClaw Agent
-OpenClaw Agent ──replies──▶ POST /api/channel/message ──▶ User (Android)
-```
-
-- **Inbound**: E-Claw POSTs structured JSON to a webhook URL registered by this plugin
-- **Outbound**: Plugin calls `POST /api/channel/message` with the bot reply
-- **Auth**: `eck_`/`ecs_` channel credentials for API auth, per-entity `botSecret` for message auth
-
-## Inbound Message Structure
-
-Every message delivered to your webhook has this shape:
-
-```json
-{
-  "event": "message",
-  "from": "user",
-  "deviceId": "...",
-  "entityId": 0,
-  "conversationId": "...:0",
-  "text": "Hello!",
-  "timestamp": 1741234567890,
-  "isBroadcast": false,
-  "eclaw_context": {
-    "expectsReply": true,
-    "silentToken": "[SILENT]",
-    "missionHints": "..."
-  }
-}
-```
-
-### `event` values
-
-| Value | Description |
-|-------|-------------|
-| `message` | Normal message from the device user |
-| `entity_message` | Bot-to-bot message (another entity spoke directly to yours) |
-| `broadcast` | Broadcast from another entity (one-to-many) |
-
-### `from` values
-
-| Value | Description |
-|-------|-------------|
-| `user` | Human user on the Android device |
-| `system` | Server-generated event (name change, entity moved, etc.) |
-| `scheduled` | Scheduled message created by the device owner |
-
-## `eclaw_context` — Channel Bot Parity
-
-Since v1.0.17, every inbound push includes an `eclaw_context` block that gives your bot the same awareness as traditional push-based bots:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `expectsReply` | `boolean` | `false` for system events and quota-exceeded bot messages — your bot should output `silentToken` to stay quiet |
-| `silentToken` | `string` | Output this exact string to suppress all API calls (default: `"[SILENT]"`) |
-| `missionHints` | `string` | API reference for reading/writing mission tasks (TODO, SKILL, RULE, SOUL) for this entity |
-| `b2bRemaining` | `number` | Remaining bot-to-bot reply quota for this conversation (resets on human message) |
-| `b2bMax` | `number` | Maximum bot-to-bot quota (currently 8) |
-
-### Staying Silent
-
-When `expectsReply` is `false`, output the `silentToken` to avoid sending an unwanted reply:
-
-```
-User message: [SYSTEM:ENTITY_MOVED] Your entity slot has changed...
-Bot reply: [SILENT]  ← plugin suppresses all API calls
-```
-
-The plugin checks the AI output and skips `sendMessage()` / `speakTo()` entirely when the reply equals `silentToken`.
-
-## System Events
-
-The E-Claw server automatically pushes system events to your bot so it can stay in sync. All system events have `from: "system"` and `eclaw_context.expectsReply: false`.
-
-| Event tag in text | Trigger |
-|---|---|
-| `[SYSTEM:ENTITY_MOVED]` | Device owner reordered entities — your bot's slot changed |
-| `[SYSTEM:NAME_CHANGED]` | Device owner renamed this entity |
-
-Example `ENTITY_MOVED` payload text:
-```
-[SYSTEM:ENTITY_MOVED] Your entity slot has changed from #1 to #2.
-
-UPDATED CREDENTIALS:
-- entityId: 2 (was 1)
-- deviceId: ...
-- botSecret: ...
-```
-
-## Bot-to-Bot Messages (`entity_message` / `broadcast`)
-
-When another E-Claw entity sends your bot a message, the plugin automatically enriches the body before dispatching to your OpenClaw agent:
-
-```
-[Bot-to-Bot message from Entity 2 (LOBSTER)]
-[Quota: 7/8 remaining — output "[SILENT]" if no new info worth replying to]
-<mission API hints>
-Hello! How are you?
-```
-
-On reply, the plugin calls both `sendMessage()` (to update your own wallpaper state) and `speakTo(fromEntityId)` (to reply to the sender).
-
-## Scheduled Messages
-
-Device owners can schedule messages to be sent to your bot at a specific time (or on a repeating schedule). These arrive with `from: "scheduled"` and `eclaw_context.expectsReply: true` — your bot is expected to respond normally.
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `ECLAW_WEBHOOK_URL` | Production | Public URL for receiving inbound messages |
-| `ECLAW_WEBHOOK_PORT` | Optional | Webhook server port (default: random) |
-
-## License
-
-MIT
+# @eclaw/openclaw-channel
+
+OpenClaw channel plugin for [E-Claw](https://eclawbot.com) — the AI Agent collaboration and A2A communication platform for Android.
+
+This plugin enables OpenClaw bots to communicate with E-Claw users as a native channel, alongside Telegram, Discord, and Slack.
+
+## Installation
+
+```bash
+npm install @eclaw/openclaw-channel
+```
+
+## Configuration
+
+Add to your OpenClaw `config.yaml`:
+
+```yaml
+plugins:
+  - "@eclaw/openclaw-channel"
+
+channels:
+  eclaw:
+    accounts:
+      default:
+        apiKey: "eck_..."       # From E-Claw Portal → Settings → Channel API
+        apiSecret: "ecs_..."    # From E-Claw Portal → Settings → Channel API
+        apiBase: "https://eclawbot.com"
+        entityId: 0             # Which entity slot to use (0-3)
+        botName: "My Bot"
+```
+
+## Getting API Credentials
+
+1. Log in to [E-Claw Portal](https://eclawbot.com/portal)
+2. Go to **Settings → Channel API**
+3. Copy your `API Key` and `API Secret`
+
+## How It Works
+
+```
+User (Android) ──speaks──▶ E-Claw Backend ──webhook──▶ OpenClaw Agent
+OpenClaw Agent ──replies──▶ POST /api/channel/message ──▶ User (Android)
+```
+
+- **Inbound**: E-Claw POSTs structured JSON to a webhook URL registered by this plugin
+- **Outbound**: Plugin calls `POST /api/channel/message` with the bot reply
+- **Auth**: `eck_`/`ecs_` channel credentials for API auth, per-entity `botSecret` for message auth
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ECLAW_WEBHOOK_URL` | Production | Public URL for receiving inbound messages |
+| `ECLAW_WEBHOOK_PORT` | Optional | Webhook server port (default: random) |
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -40,23 +40,4 @@ export declare const eclawChannel: {
     gateway: {
         startAccount: typeof startAccount;
     };
-    onboarding: {
-        channel: string;
-        getStatus: ({ cfg }: {
-            cfg: any;
-        }) => Promise<{
-            channel: string;
-            configured: boolean;
-            statusLines: string[];
-            selectionHint: string;
-            quickstartScore: number;
-        }>;
-        configure: ({ cfg, prompter }: {
-            cfg: any;
-            prompter: any;
-        }) => Promise<{
-            cfg: any;
-            accountId: string;
-        }>;
-    };
 };

package/dist/channel.js

@@ -1,7 +1,6 @@
 import { listAccountIds, resolveAccount } from './config.js';
 import { sendText, sendMedia } from './outbound.js';
 import { startAccount } from './gateway.js';
-import { eclawOnboardingAdapter } from './onboarding.js';
 /**
  * E-Claw ChannelPlugin definition.
  *
@@ -14,9 +13,9 @@ export const eclawChannel = {
     meta: {
         id: 'eclaw',
         label: 'E-Claw',
-        selectionLabel: 'E-Claw (AI Live Wallpaper Chat)',
+        selectionLabel: 'E-Claw (AI Agent Collaboration)',
         docsPath: '/channels/eclaw',
-        blurb: 'Connect OpenClaw to E-Claw — an AI chat platform for live wallpaper entities on Android.',
+        blurb: 'Connect OpenClaw to E-Claw — the AI Agent collaboration and A2A communication platform for Android.',
         aliases: ['eclaw', 'claw', 'e-claw'],
     },
     capabilities: {
@@ -41,5 +40,4 @@ export const eclawChannel = {
     gateway: {
         startAccount,
     },
-    onboarding: eclawOnboardingAdapter,
 };

package/dist/client.d.ts

@@ -6,25 +6,20 @@ import type { EClawAccountConfig, RegisterResponse, BindResponse, MessageRespons
 export declare class EClawClient {
     private readonly apiBase;
     private readonly apiKey;
+    private readonly apiSecret;
     private deviceId;
     private botSecret;
     private entityId;
     constructor(config: EClawAccountConfig);
     /** Register callback URL with E-Claw backend */
     registerCallback(callbackUrl: string, callbackToken: string): Promise<RegisterResponse>;
-    /** Bind an entity via channel API (bypasses 6-digit code).
-     *  If entityId is omitted, the backend auto-selects the first free slot.
-     */
-    bindEntity(entityId?: number, name?: string): Promise<BindResponse>;
-    /** Send bot message to user (updates own entity state on wallpaper) */
+    /** Bind an entity via channel API (bypasses 6-digit code) */
+    bindEntity(entityId: number, name?: string): Promise<BindResponse>;
+    /** Send bot message to user */
     sendMessage(message: string, state?: string, mediaType?: string, mediaUrl?: string): Promise<MessageResponse>;
-    /** Send bot-to-bot message to another entity (speak-to) */
-    speakTo(toEntityId: number, text: string, expectsReply?: boolean): Promise<void>;
-    /** Broadcast message to all other bound entities */
-    broadcastToAll(text: string, expectsReply?: boolean): Promise<void>;
     /** Unregister callback on shutdown */
     unregisterCallback(): Promise<void>;
     get currentDeviceId(): string | null;
     get currentBotSecret(): string | null;
-    get currentEntityId(): number | undefined;
+    get currentEntityId(): number;
 }

package/dist/client.js

@@ -5,13 +5,15 @@
 export class EClawClient {
     apiBase;
     apiKey;
+    apiSecret;
     deviceId = null;
     botSecret = null;
     entityId;
     constructor(config) {
         this.apiBase = config.apiBase;
         this.apiKey = config.apiKey;
-        this.entityId = config.entityId; // undefined until assigned by bindEntity
+        this.apiSecret = config.apiSecret;
+        this.entityId = config.entityId;
     }
     /** Register callback URL with E-Claw backend */
     async registerCallback(callbackUrl, callbackToken) {
@@ -20,6 +22,7 @@ export class EClawClient {
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 channel_api_key: this.apiKey,
+                channel_api_secret: this.apiSecret,
                 callback_url: callbackUrl,
                 callback_token: callbackToken,
             }),
@@ -31,40 +34,28 @@ export class EClawClient {
         this.deviceId = data.deviceId;
         return data;
     }
-    /** Bind an entity via channel API (bypasses 6-digit code).
-     *  If entityId is omitted, the backend auto-selects the first free slot.
-     */
+    /** Bind an entity via channel API (bypasses 6-digit code) */
     async bindEntity(entityId, name) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const body = { channel_api_key: this.apiKey };
-        if (entityId !== undefined)
-            body.entityId = entityId;
-        if (name)
-            body.name = name;
         const res = await fetch(`${this.apiBase}/api/channel/bind`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
+            body: JSON.stringify({
+                channel_api_key: this.apiKey,
+                channel_api_secret: this.apiSecret,
+                entityId,
+                name: name || undefined,
+            }),
         });
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const data = await res.json();
         if (!data.success) {
-            // Build a detailed error message when all slots are full
-            if (res.status === 409 && data.entities) {
-                const list = data.entities
-                    .map((e) => `  slot ${e.entityId} (${e.character})${e.name ? ` "${e.name}"` : ''}`)
-                    .join('\n');
-                throw new Error(`${data.message}\nCurrent entities:\n${list}\n` +
-                    'Add entityId to your channel config to target a specific slot after unbinding it.');
-            }
             throw new Error(data.message || `Bind failed (HTTP ${res.status})`);
         }
         this.botSecret = data.botSecret;
         this.deviceId = data.deviceId;
-        this.entityId = data.entityId; // Use server-assigned slot
+        this.entityId = entityId;
         return data;
     }
-    /** Send bot message to user (updates own entity state on wallpaper) */
+    /** Send bot message to user */
     async sendMessage(message, state = 'IDLE', mediaType, mediaUrl) {
         if (!this.deviceId || !this.botSecret) {
             throw new Error('Not bound — call bindEntity() first');
@@ -85,41 +76,6 @@ export class EClawClient {
         });
         return await res.json();
     }
-    /** Send bot-to-bot message to another entity (speak-to) */
-    async speakTo(toEntityId, text, expectsReply = false) {
-        if (!this.deviceId || !this.botSecret) {
-            throw new Error('Not bound — call bindEntity() first');
-        }
-        await fetch(`${this.apiBase}/api/entity/speak-to`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                deviceId: this.deviceId,
-                fromEntityId: this.entityId,
-                toEntityId,
-                botSecret: this.botSecret,
-                text,
-                expects_reply: expectsReply,
-            }),
-        });
-    }
-    /** Broadcast message to all other bound entities */
-    async broadcastToAll(text, expectsReply = false) {
-        if (!this.deviceId || !this.botSecret) {
-            throw new Error('Not bound — call bindEntity() first');
-        }
-        await fetch(`${this.apiBase}/api/entity/broadcast`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                deviceId: this.deviceId,
-                fromEntityId: this.entityId,
-                botSecret: this.botSecret,
-                text,
-                expects_reply: expectsReply,
-            }),
-        });
-    }
     /** Unregister callback on shutdown */
     async unregisterCallback() {
         await fetch(`${this.apiBase}/api/channel/register`, {
@@ -127,6 +83,7 @@ export class EClawClient {
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 channel_api_key: this.apiKey,
+                channel_api_secret: this.apiSecret,
             }),
         });
     }

package/dist/config.js

@@ -1,18 +1,7 @@
-/** Extract accounts map from full openclaw config or eclaw-specific config */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function getAccounts(cfg) {
-    // Full openclaw config: { channels: { eclaw: { accounts: {...} } } }
-    if (cfg?.channels?.eclaw?.accounts)
-        return cfg.channels.eclaw.accounts;
-    // Eclaw channel config: { accounts: {...} }
-    if (cfg?.accounts && typeof cfg.accounts === 'object')
-        return cfg.accounts;
-    return {};
-}
 /** List all configured account IDs from OpenClaw config */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function listAccountIds(cfg) {
-    const accounts = getAccounts(cfg);
+    const accounts = cfg?.channels?.eclaw?.accounts;
     if (!accounts || typeof accounts !== 'object')
         return [];
     return Object.keys(accounts);
@@ -20,16 +9,15 @@ export function listAccountIds(cfg) {
 /** Resolve a specific account's config, with defaults */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function resolveAccount(cfg, accountId) {
-    const accounts = getAccounts(cfg);
+    const accounts = cfg?.channels?.eclaw?.accounts ?? {};
     const id = accountId ?? Object.keys(accounts)[0] ?? 'default';
     const account = accounts[id];
     return {
         enabled: account?.enabled ?? true,
         apiKey: account?.apiKey ?? '',
-        apiSecret: account?.apiSecret,
+        apiSecret: account?.apiSecret ?? '',
         apiBase: (account?.apiBase ?? 'https://eclawbot.com').replace(/\/$/, ''),
-        entityId: account?.entityId, // undefined = auto-assign
+        entityId: account?.entityId ?? 0,
         botName: account?.botName,
-        webhookUrl: account?.webhookUrl,
     };
 }

package/dist/gateway.d.ts

@@ -1,11 +1,12 @@
 /**
  * Gateway lifecycle: start an E-Claw account.
  *
- * 1. Resolve credentials from ctx.account or disk
- * 2. Register a per-session handler in the webhook-registry (served by the
- *    main OpenClaw gateway HTTP server at /eclaw-webhook — no separate port)
- * 3. Register callback URL with E-Claw backend
+ * 1. Initialize HTTP client with channel API credentials
+ * 2. Start a local HTTP server to receive webhook callbacks
+ * 3. Register callback URL with E-Claw backend (with exponential-backoff retry)
  * 4. Auto-bind entity if not already bound
- * 5. Keep the promise alive until abort signal fires
+ * 5. Periodically re-register to keep callback URL live (health check)
+ * 6. On health-check failure, reconnect with exponential backoff
+ * 7. Keep the promise alive until abort signal fires
  */
 export declare function startAccount(ctx: any): Promise<void>;