Signal Custom

Name: Signal Custom
Rating: 3.5 (1 reviews)
Author: kaikozlov

By kaikozlov ⭐ 1 stars 👁 2 views ▲ 0 votes

Better Signal Channel for OpenClaw

GitHub

Install

npm install
```

README

# openclaw-signal-custom

A standalone Signal channel plugin for [OpenClaw](https://github.com/nicosql/openclaw), powered by `signal-cli`. Plugin id: `signal-custom`, config root: `channels.signal-custom`. Requires OpenClaw `>= 2026.3.24`.

This is a drop-in replacement for the bundled Signal channel. It covers the full `signal-cli` surface — DMs, groups, media, reactions, polls, stickers, stories, mentions, message editing, group admin, and more — with tested transport, clean formatting, and an access-control model that actually works.

## Features

**Messaging**
- Send and receive text, media, and view-once media
- Markdown-to-Signal formatting with native text styles (bold, italic, strikethrough, etc.)
- Native `@mentions` with automatic offset remapping from Markdown
- Reply/quote threading, silent sends, typing indicators, read receipts
- Configurable text chunking for long messages

**Group chat**
- Per-group `requireMention` mode and tool/skill policies
- Group management: add/remove members, promote admins, ban, and update name/description/avatar
- Group-specific allowlists and system prompts

**Rich content**
- Sticker packs (send and list installed packs)
- Reactions (send, remove, configurable notification level including ACK reactions)
- Polls (create, vote, receive results)
- Stories (send replies, receive inbound story context)
- Message edit and delete (local and remote)
- Link previews and shared contacts

**Inbound handling**
- DM access policies: open, pairing flow, or allowlist
- Group access policies: open or allowlist
- Local attachment-store fast path (skips network round-trip when `configPath` is set)
- Clean media prompt shaping — no junk injected into model context
- Audio transcription compatibility

**Transport**
- Auto-spawn and monitor a local `signal-cli` daemon, or connect to an external one
- HTTP JSON-RPC and TCP socket transports
- SSE event streaming with JSON-RPC polling fallback
- Automatic reconnection with exponential backoff

## Install

For a local repo checkout:

```bash
git clone <your-repo-url> openclaw-signal-custom
cd openclaw-signal-custom
pnpm install
```

`pnpm install` only installs this repo's dependencies. It does not register the
plugin with OpenClaw.

Link the repo into OpenClaw for development:

```bash
openclaw plugins install -l /absolute/path/to/openclaw-signal-custom
```

Check that OpenClaw sees it:

```bash
openclaw plugins inspect signal-custom
```

Then restart the gateway so the linked plugin is picked up cleanly:

```bash
openclaw gateway restart
```

If you do not want the bundled Signal channel running alongside it:

```bash
openclaw plugins disable signal
```

If you use `plugins.allow`, add the plugin explicitly:

```bash
openclaw config set plugins.allow '["signal-custom"]' --strict-json
```

## Setup

### Local daemon (recommended)

The plugin spawns and manages `signal-cli` for you. Point it at your Signal account:

```bash
openclaw config set channels.signal-custom.account '"+15551234567"' --strict-json
openclaw config set channels.signal-custom.configPath '"/Users/you/.local/share/signal-cli"' --strict-json
openclaw config set channels.signal-custom.cliPath '"signal-cli"' --strict-json
openclaw config set channels.signal-custom.autoStart true --strict-json
```

Set `configPath` to your `signal-cli` data directory. This is strongly recommended — it enables the local attachment fast path and lets the daemon find your account data.

### External daemon

Connect to an already-running `signal-cli` JSON-RPC instance:

```bash
openclaw config set channels.signal-custom.account '"+15551234567"' --strict-json
openclaw config set channels.signal-custom.httpUrl '"http://127.0.0.1:8080"' --strict-json
openclaw config set channels.signal-custom.autoStart false --strict-json
```

### Multi-account

Run multiple Signal accounts under one plugin:

```json5
{
  channels: {
    "signal-custom": {
      defaultAccount: "personal",
      accounts: {
        personal: {
          account: "+15551234567",
          configPath: "/Users/you/.local/share/signal-cli",
          autoStart: true,
        },
        work: {
          account: "+15559876543",
          configPath: "/Users/you/.local/share/signal-cli-work",
          autoStart: true,
        },
      },
    },
  },
}
```

## Configuration

All config lives under `channels.signal-custom` in your OpenClaw config file
(`openclaw.json`, which uses JSON5 syntax), or via `openclaw config set`.
See [src/config.ts](./src/config.ts) for the full schema with types and defaults.

### Connection

| Key | Type | Description |
|-----|------|-------------|
| `account` | string | Signal phone number |
| `configPath` | string | `signal-cli` config directory (enables local attachment fast path) |
| `httpUrl` | string | URL of an external JSON-RPC daemon |
| `cliPath` | string | Path to `signal-cli` binary (default: `"signal-cli"`) |
| `autoStart` | boolean | Spawn a local daemon automatically (default: `true`) |

### Access control

| Key | Default | Description |
|-----|---------|-------------|
| `dmPolicy` | `"pairing"` | `open`, `pairing`, `allowlist`, or `disabled` |
| `allowFrom` | — | DM sender allowlist (E.164, UUID, or `"*"`) |
| `groupPolicy` | `"allowlist"` | `open` or `allowlist` |
| `groupAllowFrom` | — | Group sender allowlist |

### Messaging

| Key | Description |
|-----|-------------|
| `textChunkLimit` | Max characters per outbound text chunk |
| `typingTtlMs` | Max duration for typing indicators |
| `sendReadReceipts` | Send read receipts on inbound messages |
| `responsePrefix` | Prefix applied to all bot replies |
| `mediaMaxMb` | Max inbound media size in MB |

### Reactions

| Key | Default | Description |
|-----|---------|-------------|
| `reactionLevel` | `"minimal"` | `off`, `ack`, `minimal`, or `extensive` |
| `reactionNotifications` | `"own"` | `off`, `own`, `all`, or `allowlist` |
| `ackReaction` | — | Emoji sent as ACK when level is `"ack"` |

### Actions

Fine-grained toggles under `actions`:

```json5
{
  channels: {
    "signal-custom": {
      actions: {
        reactions: true,
        unsend: true,
        poll: true,
        editMessage: true,
        deleteMessage: true,
        stickers: true,
        groupManagement: true,
      },
    },
  },
}
```

### Group settings

Per-group configuration under `groups.<group-id>`:

```json5
{
  channels: {
    "signal-custom": {
      groups: {
        "<group-id>": {
          requireMention: true,
          enabled: true,
          allowFrom: ["+15551112222"],
          systemPrompt: "You are a helpful assistant.",
          skills: ["web-search"],
          tools: {
            allow: ["read", "write"],
            deny: ["exec"],
          },
        },
      },
    },
  },
}
```

You can also inspect your active config path and edit the file directly:

```bash
openclaw config file
```

## Development

```bash
pnpm typecheck
pnpm test
```

channels