本页指导 OpenClaw 用户通过 signal-cli 将 Signal 设为聊天渠道。支持 QR 关联现有 Signal 账号或 SMS 注册专用号码，两种方式均需先安装 signal-cli。重要限制：机器人号码与个人号码需分离以避免循环；默认 DM 策略为 pairing，需手动审批配对码；群组默认 allowlist，须在 groupAllowFrom 配置后才处理消息。

OpenClaw 接入 Signal 配置教程（signal-cli）

快速配置（新手上路）

为机器人使用独立的 Signal 号码（推荐）。
在服务器上安装 signal-cli（JVM 版本需要先安装 JRE 25+）。
选择一种注册方式：
- 方式 A（QR 关联）： signal-cli link -n "OpenClaw"，然后用 Signal APP 扫码。
- 方式 B（SMS 注册）： 用验证码 + 短信验证注册专用号码。
配置 OpenClaw 配置文件（见下方最小示例）。
重启 Gateway：systemctl --user restart openclaw-gateway（根据实际服务类型调整）。
发送第一条私信给机器人号码，然后批准配对：openclaw pairing approve signal <CODE>。

最小配置文件：

json5

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      cliPath: "signal-cli",
      dmPolicy: "pairing",
      allowFrom: ["+15557654321"],
    },
  },
}

字段参考：

字段	说明
`account`	机器人手机号，E.164 格式
`cliPath`	`signal-cli` 路径（在 PATH 中可直接写名称）
`dmPolicy`	私信访问策略（推荐 `pairing`）
`allowFrom`	允许私信的手机号或 `uuid:<id>`

号码模型（重要限制）

Gateway 连接的是一个 Signal 设备（即 signal-cli 账号）。
如果在个人 Signal 账号上运行机器人，它会忽略你自己的消息（防循环保护）。
要实现“我发消息，机器人回复”，请使用独立的机器人号码。

注册方式一：QR 关联已有 Signal 账号

安装 signal-cli（JVM 或原生版本）。
运行 signal-cli link -n "OpenClaw"，然后在 Signal 中扫描显示的二维码。
在 OpenClaw 配置中填入对应的 account（关联后的号码）。
重启 Gateway。

多账号支持：使用 channels.signal.accounts 配置多个账号，每个账号可设 name。详情参见多账号通用模式。

注册方式二：SMS 注册专用机器人号码（Linux）

适用场景：需要一个全新的机器人号码，不占用现有 Signal APP 会话。

步骤 1：获取可接收 SMS 的号码

座机可选语音验证。推荐专用号码以避免账号冲突。

步骤 2：安装 signal-cli

bash

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version

如果使用 JVM 版本（signal-cli-${VERSION}.tar.gz），请先安装 JRE 25+。注意保持 signal-cli 更新，Signal 服务端 API 变更可能导致旧版本失效。

步骤 3：注册并验证号码

bash

signal-cli -a +<BOT_PHONE_NUMBER> register

如果需要验证码：

浏览器打开 https://signalcaptchas.org/registration/generate.html。
完成验证码，从“Open Signal”按钮复制 signalcaptcha://... 链接。

在与浏览器相同的外网 IP 上立即运行注册（验证码过期很快）：

bash

signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>

步骤 4：配置并验证

将 account 设为该号码后重启 Gateway：

bash

# 如果以用户级 systemd 运行：
systemctl --user restart openclaw-gateway

# 验证：
openclaw doctor
openclaw channels status --probe

步骤 5：配对 DM 发送方

用手机向机器人号码发送任意消息。
在服务器上批准：openclaw pairing approve signal <PAIRING_CODE>。
建议将机器人号码存为联系人，避免显示“未知联系人”。

WARNING

注册一个号码到 signal-cli 可能会导致该号码的主 Signal APP 会话失效。优先使用专用机器人号码，或使用 QR 关联模式。

上游参考：

signal-cli 官方文档：https://github.com/AsamK/signal-cli
验证码流程：https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
关联流程：https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

外部守护进程模式（httpUrl）

如果希望自己管理 signal-cli 进程（避免 JVM 冷启动或共享 CPU），可以单独运行守护进程，然后通过 httpUrl 连接：

json5

{
  channels: {
    signal: {
      httpUrl: "http://127.0.0.1:8080",
      autoStart: false,
    },
  },
}

这会跳过 OpenClaw 内部的自动启动和等待逻辑。如果自动启动时启动慢，可设置 channels.signal.startupTimeoutMs 增加超时时间（最大 120000 ms）。

容器模式（bbernhard/signal-cli-rest-api）

使用 bbernhard/signal-cli-rest-api Docker 容器替代原生 signal-cli。

要求

容器必须运行在 MODE=json-rpc 模式下才能实时接收消息。
在容器内注册或关联 Signal 账号后，再连接 OpenClaw。

docker-compose.yml 示例

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 配置

json5

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      httpUrl: "http://signal-cli:8080",
      autoStart: false,
      apiMode: "container", // 或 "auto" 自动检测
    },
  },
}

apiMode 字段控制协议：

值	行为
`"auto"`	（默认）探测两种 transport；流式连接验证容器 WebSocket 接收能力
`"native"`	强制使用原生 signal-cli（JSON-RPC `/api/v1/rpc`，SSE `/api/v1/events`）
`"container"`	强制使用 bbernhard 容器（REST `/v2/send`，WebSocket `/v1/receive/{account}`）

自动模式（auto）会缓存检测结果 30 秒。容器模式下，只有 /v1/receive/{account} 成功升级为 WebSocket 时才会选择容器接收流。必须 MODE=json-rpc 才能正常工作。

容器模式支持的功能：发送、接收、附件、打字指示器、已读回执、反应、群组、富文本。OpenClaw 将原生 RPC 调用翻译为容器 REST 负载（包括 group.{base64(internal_id)} 群组 ID 和 text_mode: "styled"）。

操作注意事项

使用 autoStart: false，不要让 OpenClaw 额外启动原生守护进程。
如果 MODE=normal，/v1/about 可能健康，但 /v1/receive/{account} 不会升级 WebSocket，自动模式将无法选择容器接收。
推荐显式设置 apiMode: "container" 或 "native"，避免自动探测的开销。
附件下载的媒体字节限制与原生模式一致。

DM 配对与群组访问控制

私信（DM）

默认策略：channels.signal.dmPolicy = "pairing"。
未知发送方会收到配对码，消息被忽略直到批准（配对码 1 小时后过期）。
批准命令：
- openclaw pairing list signal
- openclaw pairing approve signal <CODE>
仅 UUID 的发送方以 uuid:<id> 形式存入 channels.signal.allowFrom。

配对详细流程参见配对机制。

群组

channels.signal.groupPolicy：open | allowlist | disabled（默认 allowlist）。
channels.signal.groupAllowFrom：白名单，可包含群组 ID（支持 raw、group:<id>、signal:group:<id>）、发送方手机号、uuid:<id> 或 *。
channels.signal.groups["<group-id>" | "*"] 可覆盖群组行为：requireMention、tools、toolsBySender。
多账号场景使用 channels.signal.accounts.<id>.groups 进行每账号覆盖。
运行时注意：如果 channels.signal 配置完全缺失，群组检查会回退到 groupPolicy="allowlist"（即使 channels.defaults.groupPolicy 已设置）。

消息反应（Reactions）

使用 message action=react 工具，指定 channel=signal。

示例

message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅

配置项

channels.signal.actions.reactions：启用/禁用反应动作（默认 true）。
channels.signal.reactionLevel：off | ack | minimal | extensive。
- off/ack：禁用 Agent 反应（react 动作会报错）。
- minimal/extensive：启用并设置指导级别。
每账号覆盖：channels.signal.accounts.<id>.actions.reactions、channels.signal.accounts.<id>.reactionLevel。

媒体与限制

出站文本按 channels.signal.textChunkLimit 分块（默认 4000 字符）。
可选换行分块：设置 channels.signal.chunkMode="newline" 以空行（段落边界）为分割点，超长再按长度分割。
支持附件（base64 从 signal-cli 获取）。
默认媒体上限：channels.signal.mediaMaxMb（默认 8 MB）。
设置 channels.signal.ignoreAttachments 跳过媒体下载。
群组历史上下文使用 channels.signal.historyLimit（或 channels.signal.accounts.*.historyLimit），回退到 messages.groupChat.historyLimit；设置为 0 禁用（默认 50）。

输入状态与已读回执

输入状态：OpenClaw 通过 signal-cli sendTyping 发送输入状态，并在回复生成过程中持续刷新。
已读回执：当 channels.signal.sendReadReceipts 为 true 时，OpenClaw 为已允许的私信转发已读回执。
signal-cli 不暴露群组已读回执。

配置写入权限

Signal 渠道默认允许通过 /config set|unset 更新配置（需要 commands.config: true）。

禁用方法：

json5

{
  channels: { signal: { configWrites: false } },
}

故障排查：Signal 不回复怎么办

执行诊断阶梯：

bash

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

然后检查配对状态：

bash

openclaw pairing list signal

常见原因

守护进程可达但无回复：检查 httpUrl、account 以及接收模式。
私信被忽略：发送方处于待配对状态，需先批准配对码。
群组消息被忽略：群组发送方未被 groupAllowFrom 放行，或 requireMention 限制。
配置验证报错：运行 openclaw doctor --fix。
诊断未显示 Signal：确认 channels.signal.enabled: true。

额外调试命令：

bash

pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

更详细的排查流程参见渠道故障排查。

安全注意事项

signal-cli 在本地存储账号密钥（通常在 ~/.local/share/signal-cli/data/）。
服务器迁移或重建前备份该目录。
除非明确需要更宽松的私信访问，请保持 channels.signal.dmPolicy: "pairing"。
SMS 验证仅在注册或恢复流程中使用；一旦失去对号码/账号的控制权，重新注册会很麻烦。

配置参考（Signal 字段）

完整配置文档：Gateway 配置

配置项	说明
`channels.signal.enabled`	启用/禁用渠道
`channels.signal.account`	机器人 E.164 格式手机号
`channels.signal.cliPath`	`signal-cli` 路径
`channels.signal.httpUrl`	完整守护进程 URL（覆盖 host/port）
`channels.signal.httpHost`, `channels.signal.httpPort`	守护进程绑定地址（默认 127.0.0.1:8080）
`channels.signal.autoStart`	自动启动守护进程（未设 `httpUrl` 时默认 `true`）
`channels.signal.startupTimeoutMs`	启动等待超时（最大 120000 ms）
`channels.signal.receiveMode`	`on-start` 或 `manual`
`channels.signal.ignoreAttachments`	跳过附件下载
`channels.signal.ignoreStories`	忽略 stories
`channels.signal.sendReadReceipts`	转发已读回执
`channels.signal.dmPolicy`	`pairing` / `allowlist` / `open` / `disabled`（默认 `pairing`）
`channels.signal.allowFrom`	私信白名单（E.164 或 `uuid:<id>`）；`open` 需包含 `"*"`
`channels.signal.groupPolicy`	`open` / `allowlist` / `disabled`（默认 `allowlist`）
`channels.signal.groupAllowFrom`	群组白名单（群组 ID、手机号、UUID 或 `*`）
`channels.signal.groups`	按群组 ID 覆盖 `requireMention`、`tools`、`toolsBySender`
`channels.signal.accounts.<id>.groups`	多账号版本
`channels.signal.historyLimit`	群组上下文最大消息数（0 禁用，默认 50）
`channels.signal.dmHistoryLimit`	私信历史限制（轮次）；可逐用户覆盖
`channels.signal.textChunkLimit`	出站分块大小（字符数，默认 4000）
`channels.signal.chunkMode`	`length`（默认）或 `newline`（按空行分割）
`channels.signal.mediaMaxMb`	媒体上限（默认 8 MB）

常见问题

为什么我的 Signal 机器人不回复私信？

最常见的原因是发送方尚未配对。用手机向机器人发送任意消息，等待配对码，然后在服务器执行 openclaw pairing approve signal <CODE>。已配对的发送方才能触发回复。

如何撤销 Signal 配对？

配对码会在 1 小时后自动过期，无需手动撤销。如需立即禁用某个已配对的发送方，可以将其移出 channels.signal.allowFrom，并将 dmPolicy 设为 allowlist 或直接删除该用户的允许条目。

容器模式下 Signal 无法接收新消息怎么办？

确认容器运行在 MODE=json-rpc 模式，并在 OpenClaw 配置中设置 apiMode: "container" 或 "auto"。如果仍不工作，检查容器 WebSocket 端口 /v1/receive/{account} 是否能正常升级 WebSocket 连接。

OpenClaw 接入 Signal 配置教程（signal-cli） ​

快速配置（新手上路） ​

号码模型（重要限制） ​

注册方式一：QR 关联已有 Signal 账号 ​

注册方式二：SMS 注册专用机器人号码（Linux） ​

步骤 1：获取可接收 SMS 的号码 ​

步骤 2：安装 signal-cli ​

步骤 3：注册并验证号码 ​

步骤 4：配置并验证 ​

步骤 5：配对 DM 发送方 ​

外部守护进程模式（httpUrl） ​

容器模式（bbernhard/signal-cli-rest-api） ​

要求 ​

docker-compose.yml 示例 ​

OpenClaw 配置 ​

操作注意事项 ​

DM 配对与群组访问控制 ​

私信（DM） ​

群组 ​

消息反应（Reactions） ​

示例 ​

配置项 ​

媒体与限制 ​

输入状态与已读回执 ​

配置写入权限 ​

故障排查：Signal 不回复怎么办 ​

常见原因 ​

安全注意事项 ​

配置参考（Signal 字段） ​

常见问题 ​

为什么我的 Signal 机器人不回复私信？ ​

如何撤销 Signal 配对？ ​

容器模式下 Signal 无法接收新消息怎么办？ ​

OpenClaw 接入 Signal 配置教程（signal-cli）

快速配置（新手上路）

号码模型（重要限制）

注册方式一：QR 关联已有 Signal 账号

注册方式二：SMS 注册专用机器人号码（Linux）

步骤 1：获取可接收 SMS 的号码

步骤 2：安装 signal-cli

步骤 3：注册并验证号码

步骤 4：配置并验证

步骤 5：配对 DM 发送方

外部守护进程模式（httpUrl）

容器模式（bbernhard/signal-cli-rest-api）

要求

docker-compose.yml 示例

OpenClaw 配置

操作注意事项

DM 配对与群组访问控制

私信（DM）

群组

消息反应（Reactions）

示例

配置项

媒体与限制

输入状态与已读回执

配置写入权限

故障排查：Signal 不回复怎么办

常见原因

安全注意事项

配置参考（Signal 字段）

常见问题

为什么我的 Signal 机器人不回复私信？

如何撤销 Signal 配对？

容器模式下 Signal 无法接收新消息怎么办？