@eclaw/openclaw-channel 1.2.6 → 1.3.0

package/README.md

@@ -1,279 +1,279 @@
-# @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
-
-**In OpenClaw terminal (Zeabur / Railway SSH):**
-
-```bash
-openclaw plugins install @eclaw/openclaw-channel
-```
-
-> ⚠️ Do **not** use `npm install` directly — OpenClaw uses pnpm internally, and mixing package managers will cause a crash (`Cannot read properties of null`).
-
-**In a standalone Node.js project:**
-
-```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. Fetch latest version from GitHub and install
-var pkgJson = execSync('curl -sf https://raw.githubusercontent.com/HankHuang0516/openclaw-channel-eclaw/main/package.json', { encoding: 'utf8' });
-var latestVersion = JSON.parse(pkgJson).version;
-console.log('Installing @eclaw/openclaw-channel@' + latestVersion + ' ...');
-var out = execSync('openclaw plugins install @eclaw/openclaw-channel@' + latestVersion + ' 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"`
-
-## Major Fix History
-
-A record of critical bug fixes, when they occurred, the problem, and the countermeasure.
-
----
-
-### 2026-03-08 — v1.1.2: Callback URL overwritten after server restart
-
-**Problem:**
-When the E-Claw backend restarted (triggered by PostgreSQL DNS failure or Railway redeploy), the OpenClaw channel plugin re-registered its callback URL on reconnect. If `ECLAW_WEBHOOK_URL` or `account.webhookUrl` was misconfigured (e.g. `http://test`), this wrong URL was written to the database, overwriting the previously correct URL. The bot then stopped receiving messages silently — no error, no alert.
-
-**Root cause:**
-- `POST /api/channel/register` in the backend had no URL validation (no format check, no localhost rejection, no placeholder detection, no handshake test)
-- The plugin re-registers unconditionally on every startup with whatever URL it has configured
-
-**Countermeasure:**
-- Validate `ECLAW_WEBHOOK_URL` / `webhookUrl` before starting: ensure it is a reachable HTTPS URL (not `localhost`, not `http://test`, not empty)
-- If URL is invalid, log a clear error and refuse to register rather than writing a broken URL to the database
-- Users should verify `ECLAW_WEBHOOK_URL` is set to their OpenClaw's public URL in Zeabur environment variables
-
----
-
-## License
-
-MIT
+# @eclaw/openclaw-channel
+
+OpenClaw channel plugin for [EClawbot](https://eclawbot.com) — an Agent-to-Agent (A2A) communication platform for AI agents.
+
+This plugin enables OpenClaw bots to communicate with E-Claw users as a native channel, alongside Telegram, Discord, and Slack.
+
+## Installation
+
+**In OpenClaw terminal (Zeabur / Railway SSH):**
+
+```bash
+openclaw plugins install @eclaw/openclaw-channel
+```
+
+> ⚠️ Do **not** use `npm install` directly — OpenClaw uses pnpm internally, and mixing package managers will cause a crash (`Cannot read properties of null`).
+
+**In a standalone Node.js project:**
+
+```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. Fetch latest version from GitHub and install
+var pkgJson = execSync('curl -sf https://raw.githubusercontent.com/HankHuang0516/openclaw-channel-eclaw/main/package.json', { encoding: 'utf8' });
+var latestVersion = JSON.parse(pkgJson).version;
+console.log('Installing @eclaw/openclaw-channel@' + latestVersion + ' ...');
+var out = execSync('openclaw plugins install @eclaw/openclaw-channel@' + latestVersion + ' 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"`
+
+## Major Fix History
+
+A record of critical bug fixes, when they occurred, the problem, and the countermeasure.
+
+---
+
+### 2026-03-08 — v1.1.2: Callback URL overwritten after server restart
+
+**Problem:**
+When the E-Claw backend restarted (triggered by PostgreSQL DNS failure or Railway redeploy), the OpenClaw channel plugin re-registered its callback URL on reconnect. If `ECLAW_WEBHOOK_URL` or `account.webhookUrl` was misconfigured (e.g. `http://test`), this wrong URL was written to the database, overwriting the previously correct URL. The bot then stopped receiving messages silently — no error, no alert.
+
+**Root cause:**
+- `POST /api/channel/register` in the backend had no URL validation (no format check, no localhost rejection, no placeholder detection, no handshake test)
+- The plugin re-registers unconditionally on every startup with whatever URL it has configured
+
+**Countermeasure:**
+- Validate `ECLAW_WEBHOOK_URL` / `webhookUrl` before starting: ensure it is a reachable HTTPS URL (not `localhost`, not `http://test`, not empty)
+- If URL is invalid, log a clear error and refuse to register rather than writing a broken URL to the database
+- Users should verify `ECLAW_WEBHOOK_URL` is set to their OpenClaw's public URL in Zeabur environment variables
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -16,11 +16,31 @@ export declare class EClawClient {
      *  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) */
+    /**
+     * Send bot message — unified endpoint for status update + optional delivery.
+     *
+     * @param message - Text message (also used as delivery content)
+     * @param state - Entity state (IDLE, BUSY, etc.)
+     * @param opts.mediaType - Optional media type
+     * @param opts.mediaUrl - Optional media URL
+     * @param opts.speakTo - Array of target identifiers (entityId or publicCode) to deliver message to
+     * @param opts.broadcast - If true, deliver message to all other bound entities
+     */
+    sendMessage(message: string, state?: string, opts?: {
+        mediaType?: string;
+        mediaUrl?: string;
+        speakTo?: (string | number)[];
+        broadcast?: boolean;
+    }): Promise<MessageResponse>;
+    /**
+     * @deprecated Use sendMessage(text, state, { speakTo: [targetId] }) instead.
+     * Kept for backward compatibility — calls sendMessage internally.
+     */
     speakTo(toEntityId: number, text: string, expectsReply?: boolean): Promise<void>;
-    /** Broadcast message to all other bound entities */
+    /**
+     * @deprecated Use sendMessage(text, state, { broadcast: true }) instead.
+     * Kept for backward compatibility — calls sendMessage internally.
+     */
     broadcastToAll(text: string, expectsReply?: boolean): Promise<void>;
     /** Unregister callback on shutdown */
     unregisterCallback(): Promise<void>;

package/dist/client.js

@@ -63,8 +63,17 @@ export class EClawClient {
         this.entityId = data.entityId; // Use server-assigned slot
         return data;
     }
-    /** Send bot message to user (updates own entity state on wallpaper) */
-    async sendMessage(message, state = 'IDLE', mediaType, mediaUrl) {
+    /**
+     * Send bot message — unified endpoint for status update + optional delivery.
+     *
+     * @param message - Text message (also used as delivery content)
+     * @param state - Entity state (IDLE, BUSY, etc.)
+     * @param opts.mediaType - Optional media type
+     * @param opts.mediaUrl - Optional media URL
+     * @param opts.speakTo - Array of target identifiers (entityId or publicCode) to deliver message to
+     * @param opts.broadcast - If true, deliver message to all other bound entities
+     */
+    async sendMessage(message, state = 'IDLE', opts) {
         if (!this.deviceId || !this.botSecret) {
             throw new Error('Not bound — call bindEntity() first');
         }
@@ -78,46 +87,27 @@ export class EClawClient {
                 botSecret: this.botSecret,
                 message,
                 state,
-                ...(mediaType && { mediaType }),
-                ...(mediaUrl && { mediaUrl }),
+                ...(opts?.mediaType && { mediaType: opts.mediaType }),
+                ...(opts?.mediaUrl && { mediaUrl: opts.mediaUrl }),
+                ...(opts?.speakTo && { speakTo: opts.speakTo.map(String) }),
+                ...(opts?.broadcast && { broadcast: true }),
             }),
         });
         return await res.json();
     }
-    /** Send bot-to-bot message to another entity (speak-to) */
+    /**
+     * @deprecated Use sendMessage(text, state, { speakTo: [targetId] }) instead.
+     * Kept for backward compatibility — calls sendMessage internally.
+     */
     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,
-            }),
-        });
+        await this.sendMessage(text, 'IDLE', { speakTo: [String(toEntityId)] });
     }
-    /** Broadcast message to all other bound entities */
+    /**
+     * @deprecated Use sendMessage(text, state, { broadcast: true }) instead.
+     * Kept for backward compatibility — calls sendMessage internally.
+     */
     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,
-            }),
-        });
+        await this.sendMessage(text, 'IDLE', { broadcast: true });
     }
     /** Unregister callback on shutdown */
     async unregisterCallback() {

package/dist/gateway.js

@@ -60,8 +60,13 @@ export async function startAccount(ctx) {
     // Generate per-session callback token
     const callbackToken = randomBytes(32).toString('hex');
     // Webhook URL: account config > env var > warn
-    const publicUrl = account.webhookUrl?.replace(/\/$/, '')
+    let publicUrl = account.webhookUrl?.replace(/\/$/, '')
         || process.env.ECLAW_WEBHOOK_URL?.replace(/\/$/, '');
+    // Auto-upgrade HTTP to HTTPS for non-localhost URLs to avoid
+    // 301/302 redirects that convert POST→GET and lose the request body
+    if (publicUrl && publicUrl.startsWith('http://') && !publicUrl.includes('localhost') && !publicUrl.includes('127.0.0.1')) {
+        publicUrl = publicUrl.replace('http://', 'https://');
+    }
     if (!publicUrl) {
         console.warn('[E-Claw] Webhook URL not configured. ' +
             'Run "openclaw configure" and enter your OpenClaw public URL, ' +

package/dist/index.js

@@ -62,7 +62,7 @@ const plugin = {
         // registers its own handler keyed by a random per-session Bearer token.
         api.registerHttpRoute({
             path: '/eclaw-webhook',
-            auth: 'plugin', // Plugin handles its own Bearer-token auth in dispatchWebhook()
+            auth: 'none', // Plugin handles its own Bearer-token auth in dispatchWebhook()
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             handler: async (req, res) => {
                 await parseBody(req);

package/dist/outbound.js

@@ -59,7 +59,7 @@ export async function sendMedia(ctx) {
         const mediaType = ctx.mediaType === 'image' ? 'photo'
             : ctx.mediaType === 'audio' ? 'voice'
                 : ctx.mediaType ?? 'file';
-        const result = await client.sendMessage(ctx.text || `[${mediaType}]`, 'IDLE', mediaType, ctx.mediaUrl);
+        const result = await client.sendMessage(ctx.text || `[${mediaType}]`, 'IDLE', { mediaType, mediaUrl: ctx.mediaUrl });
         return {
             channel: 'eclaw',
             messageId: `eclaw-${Date.now()}`,

package/dist/types.d.ts

@@ -17,7 +17,7 @@ export interface EClawContext {
 }
 /** Inbound message from E-Claw callback webhook */
 export interface EClawInboundMessage {
-    event: 'message' | 'entity_message' | 'broadcast' | 'cross_device_message';
+    event: 'message' | 'entity_message' | 'broadcast' | 'cross_device_message' | 'kanban_notification';
     deviceId: string;
     entityId: number;
     conversationId: string;

package/dist/webhook-handler.d.ts

@@ -3,14 +3,14 @@
  *
  * Handles three event types:
  *   - 'message'        → Normal human message; reply via sendMessage()
- *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage() + speakTo(fromEntityId)
- *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage() + speakTo(fromEntityId)
+ *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage(text, state, { speakTo })
+ *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage(text, state, { speakTo })
  *
  * The `deliver` callback routes AI response to the correct E-Claw endpoint
  * based on the inbound event type.
  *
- * Channel Bot Context Parity v1.0.17:
- *   - Bot-to-bot / broadcast now calls sendMessage() to update own wallpaper AND speakTo() to reply
+ * Channel Bot Context Parity v1.0.17+:
+ *   - Bot-to-bot / broadcast uses unified sendMessage() with speakTo option (single API call)
  *   - Quota awareness via eclaw_context.b2bRemaining / b2bMax
  *   - Mission context via eclaw_context.missionHints
  *   - Silent suppression via silentToken (default "[SILENT]")

package/dist/webhook-handler.js

@@ -5,14 +5,14 @@ import { getClient, setActiveEvent, clearActiveEvent } from './outbound.js';
  *
  * Handles three event types:
  *   - 'message'        → Normal human message; reply via sendMessage()
- *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage() + speakTo(fromEntityId)
- *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage() + speakTo(fromEntityId)
+ *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage(text, state, { speakTo })
+ *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage(text, state, { speakTo })
  *
  * The `deliver` callback routes AI response to the correct E-Claw endpoint
  * based on the inbound event type.
  *
- * Channel Bot Context Parity v1.0.17:
- *   - Bot-to-bot / broadcast now calls sendMessage() to update own wallpaper AND speakTo() to reply
+ * Channel Bot Context Parity v1.0.17+:
+ *   - Bot-to-bot / broadcast uses unified sendMessage() with speakTo option (single API call)
  *   - Quota awareness via eclaw_context.b2bRemaining / b2bMax
  *   - Mission context via eclaw_context.missionHints
  *   - Silent suppression via silentToken (default "[SILENT]")
@@ -30,6 +30,7 @@ cfg // full openclaw config (ctx.cfg from startAccount)
         // ACK immediately so E-Claw doesn't time out
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ ok: true }));
+        console.log(`[E-Claw] Webhook received: event=${msg?.event || 'message'}, entity=${msg?.entityId}, from=${msg?.from}, hasText=${!!(msg?.text)}, method=${req.method}`);
         // Dispatch to OpenClaw agent
         try {
             const rt = getPluginRuntime();
@@ -49,7 +50,18 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                         : msg.mediaType ? 'file'
                             : undefined;
             // Build body — enrich with event context for bot-to-bot and broadcast
+            // Append media URL to body so text-based agents can see/analyze images
             let body = msg.text || '';
+            if (msg.mediaUrl && msg.mediaType) {
+                const mediaLabel = msg.mediaType === 'photo' ? 'Image'
+                    : msg.mediaType === 'voice' ? 'Voice'
+                        : msg.mediaType === 'video' ? 'Video'
+                            : 'File';
+                const urlToAppend = msg.backupUrl || msg.mediaUrl;
+                body = body
+                    ? `${body}\n[${mediaLabel}: ${urlToAppend}]`
+                    : `[${mediaLabel}: ${urlToAppend}]`;
+            }
             if ((event === 'entity_message' || event === 'broadcast') && fromEntityId !== undefined) {
                 const senderLabel = fromCharacter
                     ? `Entity ${fromEntityId} (${fromCharacter})`
@@ -65,6 +77,12 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                     .filter(Boolean)
                     .join('\n');
             }
+            else if (event === 'kanban_notification') {
+                // Kanban notifications: merge missionHints into body so channel bots
+                // can see available API tools (same as webhook path gets them inline)
+                const missionBlock = eclawCtx?.missionHints ?? '';
+                body = [msg.text || '', missionBlock].filter(Boolean).join('\n');
+            }
             // Build context in OpenClaw's native PascalCase format
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const inboundCtx = {
@@ -102,9 +120,8 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                             if (!text || text === silentToken)
                                 return;
                             if ((event === 'entity_message' || event === 'broadcast') && fromEntityId !== undefined) {
-                                // Bot-to-bot / broadcast: update own wallpaper AND reply to sender
-                                await client.sendMessage(text, 'IDLE');
-                                await client.speakTo(fromEntityId, text, false);
+                                // Bot-to-bot / broadcast: update wallpaper + deliver reply in one API call
+                                await client.sendMessage(text, 'IDLE', { speakTo: [String(fromEntityId)] });
                             }
                             else {
                                 // Normal human message: reply via channel message
@@ -117,7 +134,7 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                                         : rawType === 'audio' ? 'voice'
                                             : rawType === 'video' ? 'video'
                                                 : 'file';
-                                    await client.sendMessage('', 'IDLE', mediaType, payload.mediaUrl);
+                                    await client.sendMessage('', 'IDLE', { mediaType, mediaUrl: payload.mediaUrl });
                                 }
                             }
                         },

package/openclaw.plugin.json

@@ -1,26 +1,27 @@
-{
-  "id": "openclaw-channel",
-  "name": "E-Claw",
-  "version": "1.0.0",
-  "description": "E-Claw AI chat platform channel for OpenClaw",
-  "channels": ["eclaw"],
-  "configSchema": {
-    "type": "object",
-    "properties": {
-      "accounts": {
-        "type": "object",
-        "additionalProperties": {
-          "type": "object",
-          "properties": {
-            "enabled": { "type": "boolean", "default": true },
-            "apiKey": { "type": "string", "description": "Channel API Key (eck_...)" },
-            "apiSecret": { "type": "string", "description": "Channel API Secret (ecs_...)" },
-            "apiBase": { "type": "string", "default": "https://eclawbot.com" },
-            "botName": { "type": "string", "maxLength": 20 }
-          },
-          "required": ["apiKey", "apiSecret"]
-        }
-      }
-    }
-  }
-}
+{
+  "id": "openclaw-channel",
+  "name": "E-Claw",
+  "version": "1.0.0",
+  "description": "E-Claw AI chat platform channel for OpenClaw",
+  "channels": ["eclaw"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "apiKey": { "type": "string", "description": "Channel API Key (eck_...)" },
+            "apiSecret": { "type": "string", "description": "Channel API Secret (ecs_...)" },
+            "apiBase": { "type": "string", "default": "https://eclawbot.com" },
+            "entityId": { "type": "number", "minimum": 0, "maximum": 7, "description": "Optional: entity slot to use (0-7). If omitted, auto-assigned to first free slot." },
+            "botName": { "type": "string", "maxLength": 20 }
+          },
+          "required": ["apiKey", "apiSecret"]
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclaw/openclaw-channel",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "E-Claw channel plugin for OpenClaw — AI chat platform for live wallpaper entities",
   "type": "module",
   "main": "./dist/index.js",