@eclaw/openclaw-channel 1.1.0 → 1.1.2

package/README.md

@@ -1,58 +1,244 @@
-# @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
+# @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) |
+
+## Troubleshooting
+
+### `Config invalid: channels.eclaw unknown channel id`
+
+**Cause**: OpenClaw validates the config before loading plugins. If `channels.eclaw` is already in the config but the plugin hasn't loaded yet (e.g. after upgrade), validation fails.
+
+**Fix**: Run this script in the Zeabur terminal, then do a **full container restart** from the Zeabur Dashboard (not SIGUSR1 in-process restart):
+
+```bash
+cat > /tmp/fix-cfg.js << 'EOF'
+var fs = require('fs');
+var p = '/home/node/.openclaw/openclaw.json';
+var cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+if (cfg.plugins && cfg.plugins.installs) {
+  delete cfg.plugins.installs['openclaw-channel'];
+}
+if (cfg.plugins && cfg.plugins.entries) {
+  delete cfg.plugins.entries['openclaw-channel'];
+}
+cfg.plugins = cfg.plugins || {};
+cfg.plugins.allow = cfg.plugins.allow || [];
+if (!cfg.plugins.allow.includes('openclaw-channel')) {
+  cfg.plugins.allow.push('openclaw-channel');
+}
+fs.writeFileSync(p, JSON.stringify(cfg, null, 2));
+console.log('Done:', JSON.stringify(cfg.plugins, null, 2));
+EOF
+node /tmp/fix-cfg.js
+```
+
+---
+
+### `plugin already exists: delete it first` (on upgrade)
+
+Running `openclaw plugins install @eclaw/openclaw-channel@X.Y.Z` directly fails when an older version is present. Use this full upgrade script instead:
+
+```bash
+cat > /tmp/upgrade-eclaw.js << 'EOF'
+var fs = require('fs'), { execSync } = require('child_process');
+var p = '/home/node/.openclaw/openclaw.json';
+var cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+
+// 1. Save eclaw channel config
+var saved = cfg.channels && cfg.channels.eclaw;
+
+// 2. Strip entries that cause validation to fail
+if (cfg.channels) delete cfg.channels.eclaw;
+if (cfg.plugins) {
+  if (cfg.plugins.entries)  delete cfg.plugins.entries['openclaw-channel'];
+  if (cfg.plugins.allow)    cfg.plugins.allow = cfg.plugins.allow.filter(x => x !== 'openclaw-channel');
+  if (cfg.plugins.installs) delete cfg.plugins.installs['openclaw-channel'];
+}
+fs.writeFileSync(p, JSON.stringify(cfg, null, 2));
+
+// 3. Remove old plugin files
+execSync('rm -rf /home/node/.openclaw/extensions/openclaw-channel');
+
+// 4. Install new version (update version number below)
+var out = execSync('openclaw plugins install @eclaw/openclaw-channel@1.0.18 2>&1', { encoding: 'utf8' });
+console.log(out);
+
+// 5. Restore channel config
+cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+if (saved) { cfg.channels = cfg.channels || {}; cfg.channels.eclaw = saved; }
+cfg.plugins.allow = cfg.plugins.allow || [];
+if (!cfg.plugins.allow.includes('openclaw-channel')) cfg.plugins.allow.push('openclaw-channel');
+fs.writeFileSync(p, JSON.stringify(cfg, null, 2));
+console.log('Done — restart the service from Zeabur Dashboard.');
+EOF
+node /tmp/upgrade-eclaw.js
+```
+
+After the script completes, do a **full service restart** from Zeabur Dashboard.
+
+---
+
+### In-process restart (`SIGUSR1`) doesn't apply channel config changes
+
+In-process restart validates the config before loading plugins, so `channels.eclaw` appears as an unknown channel and the restart fails. Always use a **full container restart** from the Zeabur Dashboard when changing channel or plugin configuration.
+
+---
+
+### Bot doesn't receive messages / webhook not called
+
+1. Check `ECLAW_WEBHOOK_URL` is a publicly reachable URL (not `localhost`)
+2. Verify the callback was registered: the plugin logs `Account default ready!` on startup
+3. In E-Claw Portal, confirm the entity shows as channel-bound (green dot)
+4. Check server logs: `curl "https://eclawbot.com/api/logs?deviceId=...&deviceSecret=...&limit=20"`
+
+## License
+
+MIT

package/dist/channel.d.ts

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

package/dist/client.d.ts

@@ -6,20 +6,25 @@ 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) */
-    bindEntity(entityId: number, name?: string): Promise<BindResponse>;
-    /** Send bot message to user */
+    /** 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) */
     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;
+    get currentEntityId(): number | undefined;
 }

package/dist/client.js

@@ -5,15 +5,13 @@
 export class EClawClient {
     apiBase;
     apiKey;
-    apiSecret;
     deviceId = null;
     botSecret = null;
     entityId;
     constructor(config) {
         this.apiBase = config.apiBase;
         this.apiKey = config.apiKey;
-        this.apiSecret = config.apiSecret;
-        this.entityId = config.entityId;
+        this.entityId = config.entityId; // undefined until assigned by bindEntity
     }
     /** Register callback URL with E-Claw backend */
     async registerCallback(callbackUrl, callbackToken) {
@@ -22,7 +20,6 @@ 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,
             }),
@@ -34,28 +31,40 @@ export class EClawClient {
         this.deviceId = data.deviceId;
         return data;
     }
-    /** Bind an entity via channel API (bypasses 6-digit code) */
+    /** Bind an entity via channel API (bypasses 6-digit code).
+     *  If entityId is omitted, the backend auto-selects the first free slot.
+     */
     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({
-                channel_api_key: this.apiKey,
-                channel_api_secret: this.apiSecret,
-                entityId,
-                name: name || undefined,
-            }),
+            body: JSON.stringify(body),
         });
+        // 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 = entityId;
+        this.entityId = data.entityId; // Use server-assigned slot
         return data;
     }
-    /** Send bot message to user */
+    /** Send bot message to user (updates own entity state on wallpaper) */
     async sendMessage(message, state = 'IDLE', mediaType, mediaUrl) {
         if (!this.deviceId || !this.botSecret) {
             throw new Error('Not bound — call bindEntity() first');
@@ -76,6 +85,41 @@ 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`, {
@@ -83,7 +127,6 @@ 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,7 +1,18 @@
+/** 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 = cfg?.channels?.eclaw?.accounts;
+    const accounts = getAccounts(cfg);
     if (!accounts || typeof accounts !== 'object')
         return [];
     return Object.keys(accounts);
@@ -9,15 +20,16 @@ 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 = cfg?.channels?.eclaw?.accounts ?? {};
+    const accounts = getAccounts(cfg);
     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 ?? 0,
+        entityId: account?.entityId, // undefined = auto-assign
         botName: account?.botName,
+        webhookUrl: account?.webhookUrl,
     };
 }

package/dist/gateway.d.ts

@@ -1,12 +1,11 @@
 /**
  * Gateway lifecycle: start an E-Claw account.
  *
- * 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)
+ * 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
  * 4. Auto-bind entity if not already bound
- * 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
+ * 5. Keep the promise alive until abort signal fires
  */
 export declare function startAccount(ctx: any): Promise<void>;