openclaw
diff --git a/‎changelog/fragments/pr-signal-container-mode.md‎
Lines changed: 1 addition & 0 deletions b/‎changelog/fragments/pr-signal-container-mode.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/.generated/config-baseline.sha256‎
Lines changed: 4 additions & 4 deletions b/‎docs/.generated/config-baseline.sha256‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎docs/channels/signal.md‎
Lines changed: 65 additions & 4 deletions b/‎docs/channels/signal.md‎
Lines changed: 65 additions & 4 deletions
diff --git a/‎extensions/signal/package.json‎
Lines changed: 3 additions & 0 deletions b/‎extensions/signal/package.json‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎extensions/signal/src/channel.ts‎
Lines changed: 3 additions & 1 deletion b/‎extensions/signal/src/channel.ts‎
Lines changed: 3 additions & 1 deletion
@@ -0,0 +1 @@
+- Signal/container mode: add REST API support for bbernhard/signal-cli-rest-api containerized deployments via a unified adapter layer, with automatic mode detection and `channels.signal.apiMode` config. (#10240) Thanks @Hua688.
@@ -1,4 +1,4 @@
-7317136882cafd0cfd23146218b7bec4a65a2c08328f7a1f8e22ac04789ec35d  config-baseline.json
-8e0f397eaeaa858f016a080e2585c69fa6744cdbb0e7f68d71cfc693971dbc8c  config-baseline.core.json
-25c6e70d5b4925e07549072159ce4fcad45813fed12fa36a2f43d3568ca8dd96  config-baseline.channel.json
-af8a8e8616a0146ad989ff1bc0e8cf62c61a4d434dd67bbe7fe082c5c204fada  config-baseline.plugin.json
+31ba805dfaa665fe16735d7c2f3a5e9fb0c349aeb5e301881b5da65cee62b1f8  config-baseline.json
+5552e7871057e05d5699f90f536ce58e62d5b8cfc6020d3e7106be7915fed041  config-baseline.core.json
+80f0f51caedf14dc2138d975b62852ff7c5cf085df1c734c9de279f5859a7eeb  config-baseline.channel.json
+3a08e5422ce1422d9e2b75feac7e44cdcd0c3dc1eea594f664bceec13cbe3f58  config-baseline.plugin.json
@@ -1,17 +1,19 @@
 ---
-summary: "Signal support via signal-cli (JSON-RPC + SSE), setup paths, and number model"
+summary: "Signal support via signal-cli (native daemon or bbernhard container), setup paths, and number model"
 read_when:
   - Setting up Signal support
   - Debugging Signal send/receive
 title: "Signal"
 ---
 
-Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.
+Status: external CLI integration. Gateway talks to `signal-cli` over HTTP — either native daemon (JSON-RPC + SSE) or bbernhard/signal-cli-rest-api container (REST + WebSocket).
 
 ## Prerequisites
 
 - OpenClaw installed on your server (Linux flow below tested on Ubuntu 24).
-- `signal-cli` available on the host where the gateway runs.
+- One of:
+  - `signal-cli` available on the host (native mode), **or**
+  - `bbernhard/signal-cli-rest-api` Docker container (container mode).
 - A phone number that can receive one verification SMS (for SMS registration path).
 - Browser access for Signal captcha (`signalcaptchas.org`) during registration.
 
@@ -179,6 +181,63 @@ If you want to manage `signal-cli` yourself (slow JVM cold starts, container ini
 
 This skips auto-spawn and the startup wait inside OpenClaw. For slow starts when auto-spawning, set `channels.signal.startupTimeoutMs`.
 
+## Container mode (bbernhard/signal-cli-rest-api)
+
+Instead of running `signal-cli` natively, you can use the [bbernhard/signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api) Docker container. This wraps `signal-cli` behind a REST API and WebSocket interface.
+
+Requirements:
+
+- The container **must** run with `MODE=json-rpc` for real-time message receiving.
+- Register or link your Signal account inside the container before connecting OpenClaw.
+
+Example `docker-compose.yml` service:
+
+```yaml
+signal-cli:
+  image: bbernhard/signal-cli-rest-api:latest
+  environment:
+    MODE: json-rpc
+  ports:
+    - "8080:8080"
+  volumes:
+    - signal-cli-data:/home/.local/share/signal-cli
+```
+
+OpenClaw config:
+
+```json5
+{
+  channels: {
+    signal: {
+      enabled: true,
+      account: "+15551234567",
+      httpUrl: "http://signal-cli:8080",
+      autoStart: false,
+      apiMode: "container", // or "auto" to detect automatically
+    },
+  },
+}
+```
+
+The `apiMode` field controls which protocol OpenClaw uses:
+
+| Value         | Behavior                                                                             |
+| ------------- | ------------------------------------------------------------------------------------ |
+| `"auto"`      | (Default) Probes both transports; streaming validates container WebSocket receive    |
+| `"native"`    | Force native signal-cli (JSON-RPC at `/api/v1/rpc`, SSE at `/api/v1/events`)         |
+| `"container"` | Force bbernhard container (REST at `/v2/send`, WebSocket at `/v1/receive/{account}`) |
+
+When `apiMode` is `"auto"`, OpenClaw caches the detected mode for 30 seconds to avoid repeated probes. Container receive is only selected for streaming after `/v1/receive/{account}` upgrades to WebSocket, which requires `MODE=json-rpc`.
+
+Container mode supports the same Signal channel operations as native mode where the container exposes matching APIs: sends, receives, attachments, typing indicators, read/viewed receipts, reactions, groups, and styled text. OpenClaw translates its native Signal RPC calls into the container's REST payloads, including `group.{base64(internal_id)}` group IDs and `text_mode: "styled"` for formatted text.
+
+Operational notes:
+
+- Use `autoStart: false` with container mode. OpenClaw should not spawn a native daemon when `apiMode: "container"` is selected.
+- Use `MODE=json-rpc` for receiving. `MODE=normal` can make `/v1/about` look healthy, but `/v1/receive/{account}` does not WebSocket-upgrade, so OpenClaw will not select container receive streaming in `auto` mode.
+- Set `apiMode: "container"` when you know the `httpUrl` points at bbernhard's REST API. Set `apiMode: "native"` when you know it points at native `signal-cli` JSON-RPC/SSE. Use `"auto"` when the deployment may vary.
+- Container attachment downloads honor the same media byte limits as native mode. Oversized responses are rejected before being fully buffered when the server sends `Content-Length`, and while streaming otherwise.
+
 ## Access control (DMs + groups)
 
 DMs:
@@ -202,7 +261,8 @@ Groups:
 
 ## How it works (behavior)
 
-- `signal-cli` runs as a daemon; the gateway reads events via SSE.
+- Native mode: `signal-cli` runs as a daemon; the gateway reads events via SSE.
+- Container mode: the gateway sends via REST API and receives via WebSocket.
 - Inbound messages are normalized into the shared channel envelope.
 - Replies always route back to the same number or group.
 
@@ -302,6 +362,7 @@ Full configuration: [Configuration](/gateway/configuration)
 Provider options:
 
 - `channels.signal.enabled`: enable/disable channel startup.
+- `channels.signal.apiMode`: `auto | native | container` (default: auto). See [Container mode](#container-mode-bbernhardsignal-cli-rest-api).
 - `channels.signal.account`: E.164 for the bot account.
 - `channels.signal.cliPath`: path to `signal-cli`.
 - `channels.signal.httpUrl`: full daemon URL (overrides host/port).
 
@@ -4,6 +4,9 @@
   "private": true,
   "description": "OpenClaw Signal channel plugin",
   "type": "module",
+  "dependencies": {
+    "ws": "^8.20.0"
+  },
   "devDependencies": {
     "@openclaw/plugin-sdk": "workspace:*"
   },
 
@@ -347,7 +347,9 @@ export const signalPlugin: ChannelPlugin<ResolvedSignalAccount, SignalProbe> =
         probeAccount: async ({ account, timeoutMs }) => {
           const baseUrl = account.baseUrl;
           const { probeSignal } = await loadSignalProbeModule();
-          return await probeSignal(baseUrl, timeoutMs);
+          return await probeSignal(baseUrl, timeoutMs, {
+            apiMode: account.config?.apiMode ?? "auto",
+          });
         },
         formatCapabilitiesProbe: ({ probe }) =>
           probe?.version ? [{ text: `Signal daemon: ${probe.version}` }] : [],
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+- Signal/container mode: add REST API support for bbernhard/signal-cli-rest-api containerized deployments via a unified adapter layer, with automatic mode detection and `channels.signal.apiMode` config. (#10240) Thanks @Hua688.