@eclaw/openclaw-channel 1.0.17 → 1.0.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -25,15 +25,15 @@ channels:
|
|
|
25
25
|
apiKey: "eck_..." # From E-Claw Portal → Settings → Channel API
|
|
26
26
|
apiSecret: "ecs_..." # From E-Claw Portal → Settings → Channel API
|
|
27
27
|
apiBase: "https://eclawbot.com"
|
|
28
|
-
entityId: 0 #
|
|
29
|
-
botName: "My Bot"
|
|
28
|
+
entityId: 0 # Entity slot (0-3 free tier, 0-7 premium). Omit to auto-assign.
|
|
29
|
+
botName: "My Bot" # Display name in E-Claw (max 20 chars)
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## Getting API Credentials
|
|
33
33
|
|
|
34
34
|
1. Log in to [E-Claw Portal](https://eclawbot.com/portal)
|
|
35
35
|
2. Go to **Settings → Channel API**
|
|
36
|
-
3. Copy your `API Key` and `API Secret`
|
|
36
|
+
3. Copy your `API Key` (`eck_...`) and `API Secret` (`ecs_...`)
|
|
37
37
|
|
|
38
38
|
## How It Works
|
|
39
39
|
|
|
@@ -46,6 +46,103 @@ OpenClaw Agent ──replies──▶ POST /api/channel/message ──▶ User (
|
|
|
46
46
|
- **Outbound**: Plugin calls `POST /api/channel/message` with the bot reply
|
|
47
47
|
- **Auth**: `eck_`/`ecs_` channel credentials for API auth, per-entity `botSecret` for message auth
|
|
48
48
|
|
|
49
|
+
## Inbound Message Structure
|
|
50
|
+
|
|
51
|
+
Every message delivered to your webhook has this shape:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"event": "message",
|
|
56
|
+
"from": "user",
|
|
57
|
+
"deviceId": "...",
|
|
58
|
+
"entityId": 0,
|
|
59
|
+
"conversationId": "...:0",
|
|
60
|
+
"text": "Hello!",
|
|
61
|
+
"timestamp": 1741234567890,
|
|
62
|
+
"isBroadcast": false,
|
|
63
|
+
"eclaw_context": {
|
|
64
|
+
"expectsReply": true,
|
|
65
|
+
"silentToken": "[SILENT]",
|
|
66
|
+
"missionHints": "..."
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### `event` values
|
|
72
|
+
|
|
73
|
+
| Value | Description |
|
|
74
|
+
|-------|-------------|
|
|
75
|
+
| `message` | Normal message from the device user |
|
|
76
|
+
| `entity_message` | Bot-to-bot message (another entity spoke directly to yours) |
|
|
77
|
+
| `broadcast` | Broadcast from another entity (one-to-many) |
|
|
78
|
+
|
|
79
|
+
### `from` values
|
|
80
|
+
|
|
81
|
+
| Value | Description |
|
|
82
|
+
|-------|-------------|
|
|
83
|
+
| `user` | Human user on the Android device |
|
|
84
|
+
| `system` | Server-generated event (name change, entity moved, etc.) |
|
|
85
|
+
| `scheduled` | Scheduled message created by the device owner |
|
|
86
|
+
|
|
87
|
+
## `eclaw_context` — Channel Bot Parity
|
|
88
|
+
|
|
89
|
+
Since v1.0.17, every inbound push includes an `eclaw_context` block that gives your bot the same awareness as traditional push-based bots:
|
|
90
|
+
|
|
91
|
+
| Field | Type | Description |
|
|
92
|
+
|-------|------|-------------|
|
|
93
|
+
| `expectsReply` | `boolean` | `false` for system events and quota-exceeded bot messages — your bot should output `silentToken` to stay quiet |
|
|
94
|
+
| `silentToken` | `string` | Output this exact string to suppress all API calls (default: `"[SILENT]"`) |
|
|
95
|
+
| `missionHints` | `string` | API reference for reading/writing mission tasks (TODO, SKILL, RULE, SOUL) for this entity |
|
|
96
|
+
| `b2bRemaining` | `number` | Remaining bot-to-bot reply quota for this conversation (resets on human message) |
|
|
97
|
+
| `b2bMax` | `number` | Maximum bot-to-bot quota (currently 8) |
|
|
98
|
+
|
|
99
|
+
### Staying Silent
|
|
100
|
+
|
|
101
|
+
When `expectsReply` is `false`, output the `silentToken` to avoid sending an unwanted reply:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
User message: [SYSTEM:ENTITY_MOVED] Your entity slot has changed...
|
|
105
|
+
Bot reply: [SILENT] ← plugin suppresses all API calls
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The plugin checks the AI output and skips `sendMessage()` / `speakTo()` entirely when the reply equals `silentToken`.
|
|
109
|
+
|
|
110
|
+
## System Events
|
|
111
|
+
|
|
112
|
+
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`.
|
|
113
|
+
|
|
114
|
+
| Event tag in text | Trigger |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `[SYSTEM:ENTITY_MOVED]` | Device owner reordered entities — your bot's slot changed |
|
|
117
|
+
| `[SYSTEM:NAME_CHANGED]` | Device owner renamed this entity |
|
|
118
|
+
|
|
119
|
+
Example `ENTITY_MOVED` payload text:
|
|
120
|
+
```
|
|
121
|
+
[SYSTEM:ENTITY_MOVED] Your entity slot has changed from #1 to #2.
|
|
122
|
+
|
|
123
|
+
UPDATED CREDENTIALS:
|
|
124
|
+
- entityId: 2 (was 1)
|
|
125
|
+
- deviceId: ...
|
|
126
|
+
- botSecret: ...
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Bot-to-Bot Messages (`entity_message` / `broadcast`)
|
|
130
|
+
|
|
131
|
+
When another E-Claw entity sends your bot a message, the plugin automatically enriches the body before dispatching to your OpenClaw agent:
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
[Bot-to-Bot message from Entity 2 (LOBSTER)]
|
|
135
|
+
[Quota: 7/8 remaining — output "[SILENT]" if no new info worth replying to]
|
|
136
|
+
<mission API hints>
|
|
137
|
+
Hello! How are you?
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
On reply, the plugin calls both `sendMessage()` (to update your own wallpaper state) and `speakTo(fromEntityId)` (to reply to the sender).
|
|
141
|
+
|
|
142
|
+
## Scheduled Messages
|
|
143
|
+
|
|
144
|
+
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.
|
|
145
|
+
|
|
49
146
|
## Environment Variables
|
|
50
147
|
|
|
51
148
|
| Variable | Required | Description |
|