Signal（signal-cli）

状态：外部 CLI 集成。Gateway 通过 HTTP JSON-RPC + SSE 与 signal-cli 通信。

前置条件

服务器已安装 OpenClaw（Linux 流程以 Ubuntu 24 为例）。
Gateway 所在主机已安装 signal-cli。
一个可接收一条验证短信的手机号（SMS 注册路径需要）。
注册时需要浏览器访问 Signal 验证码页面（signalcaptchas.org）。

快速配置（新手上路）

想让你的小龙虾开口说话，先把 signal-cli 喂饱：

为机器人使用独立的 Signal 号码（推荐）。
安装 signal-cli（JVM 版本需要先装 Java）。
选择一种注册方式：
- 方式 A（QR 关联）： signal-cli link -n "OpenClaw"，然后用 Signal APP 扫码。
- 方式 B（SMS 注册）： 用验证码 + 短信验证注册专用号码。
配置 OpenClaw，重启 Gateway。
发送第一条私信并完成配对：openclaw pairing approve signal <CODE>。

最小配置示例：

json5

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

字段说明：

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

功能说明

通过 signal-cli 实现 Signal 渠道（非内嵌 libsignal）。
确定性路由：回复始终发回 Signal。
私信共用 Agent 主会话；群组独立隔离（agent:<agentId>:signal:group:<groupId>）。

配置写入

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

禁用写入：

json5

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

号码模型（重要）

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

方式 A：关联已有 Signal 账号（QR 扫码）

安装 signal-cli（JVM 或原生版本）。
关联机器人账号：
- signal-cli link -n "OpenClaw"，然后在 Signal 中扫码。
配置 Signal 并启动 Gateway。

配置示例：

json5

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

多账号支持：使用 channels.signal.accounts 配置每个账号，可设置可选的 name。参见 gateway/configuration 中的通用多账号模式。

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

当你需要一个专用机器人号码、而不是关联现有 Signal APP 账号时使用此方式。

准备一个可接收 SMS 的号码（座机可选语音验证）。
- 使用专用机器人号码，避免账号/会话冲突。
在 Gateway 主机上安装 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 变更可能导致旧版本失效。

注册并验证号码：

bash

signal-cli -a +<BOT_PHONE_NUMBER> register

如需验证码：

打开 https://signalcaptchas.org/registration/generate.html。
完成验证码，从"Open Signal"按钮复制 signalcaptcha://... 链接目标。
尽可能在与浏览器会话相同的外网 IP 上运行。
立即重新运行注册（验证码 token 有效期很短）：

bash

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

配置 OpenClaw，重启 Gateway，验证渠道：

bash

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

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

配对私信发送方：
- 向机器人号码发送任意消息。
- 在服务器上批准：openclaw pairing approve signal <PAIRING_CODE>。
- 将机器人号码保存为联系人，避免显示"未知联系人"。

重要提示： 用 signal-cli 注册一个手机号账号，可能会导致该号码的 Signal 主 APP 会话失效。建议使用专用机器人号码，或者在需要保留现有手机 APP 的情况下使用 QR 关联模式。

上游参考资料：

signal-cli README：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 场景），可以单独运行守护进程，然后让 OpenClaw 连接它：

json5

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

这会跳过 OpenClaw 内部的自动启动和等待逻辑。对于自动启动时启动慢的情况，可以设置 channels.signal.startupTimeoutMs。

访问控制（私信 + 群组）

私信：

默认：channels.signal.dmPolicy = "pairing"。
未知发送方会收到配对码；代码过期前（1小时）消息被忽略。
批准方式：
- openclaw pairing list signal
- openclaw pairing approve signal <CODE>
配对是 Signal 私信的默认 token 交换机制。详情：配对机制
来自 sourceUuid 的仅 UUID 发送方以 uuid:<id> 形式存入 channels.signal.allowFrom。

群组：

channels.signal.groupPolicy = open | allowlist | disabled。
channels.signal.groupAllowFrom 控制 allowlist 模式下哪些人可以在群组中触发机器人。
channels.signal.groups["<group-id>" | "*"] 可用 requireMention、tools 和 toolsBySender 覆盖群组行为。
多账号场景下使用 channels.signal.accounts.<id>.groups 进行每账号覆盖。
运行时说明：如果 channels.signal 完全缺失，运行时会回退到 groupPolicy="allowlist" 进行群组检查（即使设置了 channels.defaults.groupPolicy）。

工作原理

signal-cli 以守护进程运行；Gateway 通过 SSE 读取事件。
入站消息被规范化为共享渠道信封。
回复始终路由回相同的号码或群组。

媒体与限制

出站文本按 channels.signal.textChunkLimit 分块（默认 4000）。
可选换行分块：设置 channels.signal.chunkMode="newline" 以空行（段落边界）为优先分割点，超长再按长度分割。
支持附件（从 signal-cli 获取 base64）。
默认媒体上限：channels.signal.mediaMaxMb（默认 8）。
使用 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 不对群组公开已读回执。

消息反应（message 工具）

使用 message action=react 并指定 channel=signal。
目标：发送方 E.164 号码或 UUID（使用配对输出中的 uuid:<id>，纯 UUID 也可）。
messageId 是被回应消息的 Signal 时间戳。
群组反应需要 targetAuthor 或 targetAuthorUuid。

示例：

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 反应（message 工具的 react 会报错）。
- minimal/extensive 启用 Agent 反应并设置指导级别。
每账号覆盖：channels.signal.accounts.<id>.actions.reactions、channels.signal.accounts.<id>.reactionLevel。

投递目标（CLI/定时任务）

私信：signal:+15551234567（或纯 E.164 格式）。
UUID 私信：uuid:<id>（或纯 UUID）。
群组：signal:group:<groupId>。
用户名：username:<name>（如果你的 Signal 账号支持）。

故障排查

先跑一遍诊断梯子：

bash

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

然后确认私信配对状态：

bash

openclaw pairing list signal

常见问题：

守护进程可达但无回复：检查账号/守护进程设置（httpUrl、account）和接收模式。
私信被忽略：发送方待配对批准。
群组消息被忽略：群组发送方/提及门控拦截。
编辑配置后验证报错：运行 openclaw doctor --fix。
诊断中没有 Signal：确认 channels.signal.enabled: true。

额外检查：

bash

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

更多排查流程参见：渠道故障排查。

安全注意事项

signal-cli 在本地存储账号密钥（通常在 ~/.local/share/signal-cli/data/）。
服务器迁移或重建前备份 Signal 账号状态。
除非明确需要更宽松的私信访问，请保持 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：启动等待超时（最大 120000ms）。
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 需要包含 "*"。Signal 无用户名，使用手机号/UUID。
channels.signal.groupPolicy：open | allowlist | disabled（默认：allowlist）。
channels.signal.groupAllowFrom：群组发送方白名单。
channels.signal.groups：按 Signal 群组 ID（或 "*"）的每群组覆盖。支持字段：requireMention、tools、toolsBySender。
channels.signal.accounts.<id>.groups：多账号场景下 channels.signal.groups 的每账号版本。
channels.signal.historyLimit：作为上下文纳入的最大群组消息数（0 禁用）。
channels.signal.dmHistoryLimit：私信历史限制（用户轮次）。每用户覆盖：channels.signal.dms["<phone_or_uuid>"].historyLimit。
channels.signal.textChunkLimit：出站分块大小（字符数）。
channels.signal.chunkMode：length（默认）或 newline（按空行分割后再按长度分割）。
channels.signal.mediaMaxMb：入站/出站媒体上限（MB）。

Signal（signal-cli） ​

前置条件 ​

快速配置（新手上路） ​

功能说明 ​

配置写入 ​

号码模型（重要） ​

方式 A：关联已有 Signal 账号（QR 扫码） ​

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

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

访问控制（私信 + 群组） ​

工作原理 ​

媒体与限制 ​

输入状态与已读回执 ​

消息反应（message 工具） ​

投递目标（CLI/定时任务） ​

故障排查 ​

安全注意事项 ​

配置参考（Signal） ​

Signal（signal-cli）

前置条件

快速配置（新手上路）

功能说明

配置写入

号码模型（重要）

方式 A：关联已有 Signal 账号（QR 扫码）

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

外部守护进程模式（httpUrl）

访问控制（私信 + 群组）

工作原理

媒体与限制

输入状态与已读回执

消息反应（message 工具）

投递目标（CLI/定时任务）

故障排查

安全注意事项

配置参考（Signal）