Signal

​

号码模型（先读这里）

• Gateway 网关连接到一个 Signal 设备：即 signal-cli 账号。
• 在 你的个人 Signal 账号上运行机器人会让它忽略你自己的消息（循环保护）。
• 对于“我给机器人发短信，它回复我”的场景，请使用一个单独的机器人号码。

​

安装

openclaw plugins install @openclaw/signal

​

快速设置

openclaw plugins install @openclaw/signal

openclaw channels add

openclaw gateway call channels.status --params '{"probe":true}'

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

​

它是什么

• 确定性路由：回复始终回到 Signal。
• 私信共享智能体的主会话；群组会隔离（agent:<agentId>:signal:group:<groupId>）。
• 默认情况下，Signal 可以写入由 /config set|unset 触发的配置更新（需要 commands.config: true）。可通过 channels.signal.configWrites: false 禁用。

​

设置路径 A：链接现有 Signal 账号（二维码）

1. 安装 signal-cli（JVM 或原生构建），或让 openclaw channels add 为你安装。
2. 链接一个机器人账号：signal-cli link -n "OpenClaw"，然后在 Signal 中扫描二维码。
3. 配置 Signal 并启动 Gateway 网关。

​

设置路径 B：注册专用机器人号码（短信，Linux）

1. 获取一个可以接收短信的号码（固定电话可使用语音验证）。专用机器人号码可以避免账号/会话冲突。
2. 在 Gateway 网关主机上安装 signal-cli：

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

3. 注册并验证号码：

signal-cli -a +<BOT_PHONE_NUMBER> register

1. 打开 https://signalcaptchas.org/registration/generate.html。
2. 完成验证码，从 “Open Signal” 复制 signalcaptcha://... 链接目标。
3. 尽可能从与浏览器会话相同的外部 IP 运行（验证码令牌很快过期）。
4. 立即注册并验证：

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

4. 配置 OpenClaw，重启 Gateway 网关，并验证渠道：

# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service

# Then verify:
openclaw doctor
openclaw channels status --probe

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

• 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）

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

​

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

• 容器必须使用 MODE=json-rpc 运行，才能实时接收消息。
• 在连接 OpenClaw 之前，请先在容器内注册或链接你的 Signal 账号。

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

{
  channels: {
    signal: {
      enabled: true,
      account: "+15551234567",
      httpUrl: "http://signal-cli:8080",
      autoStart: false,
      apiMode: "container", // or "auto" to detect automatically
    },
  },
}

• 容器模式请使用 autoStart: false；选择 apiMode: "container" 时，OpenClaw 不应启动原生守护进程。
• 接收消息请使用 MODE=json-rpc。MODE=normal 可能让 /v1/about 看起来健康，但 /v1/receive/{account} 不会升级为 WebSocket，因此 OpenClaw 在 auto 模式下不会选择容器接收流式传输。
• 当 httpUrl 指向 bbernhard REST API 时设置 apiMode: "container"；指向原生 signal-cli JSON-RPC/SSE 时设置 "native"；部署可能变化时设置 "auto"。
• 容器附件下载遵循与原生模式相同的媒体字节限制。当服务器发送 Content-Length 时，超大响应会在完整缓冲前被拒绝；否则会在流式传输过程中拒绝。

​

访问控制（私信 + 群组）

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

• channels.signal.groupPolicy = open | allowlist | disabled。
• 当设置为 allowlist 时，channels.signal.groupAllowFrom 控制哪些群组或发送方可以触发群组回复；条目可以是 Signal 群组 ID（原始值、group:<id> 或 signal:group:<id>）、发送方电话号码、uuid:<id> 值或 *。
• channels.signal.groups["<group-id>" | "*"] 可以通过 requireMention、tools 和 toolsBySender 覆盖群组行为。
• 在多账号设置中，使用 channels.signal.accounts.<id>.groups 进行每账号覆盖。
• 通过 groupAllowFrom 将群组加入允许列表本身不会禁用提及门控。除非显式设置 requireMention: true，否则专门配置的 channels.signal.groups["<group-id>"] 条目会处理每条群组消息。
• 运行时说明：如果完全缺失 channels.signal，运行时会在群组检查时回退到 groupPolicy="allowlist"（即使设置了 channels.defaults.groupPolicy）。

​

工作方式（行为）

• 原生模式：signal-cli 作为守护进程运行；Gateway 网关通过 SSE 读取事件。
• 容器模式：Gateway 网关通过 REST API 发送，并通过 WebSocket 接收。
• 入站消息会被规范化为共享渠道信封。
• 回复始终路由回同一个号码或群组。

​

媒体 + 限制

• 出站文本会按 channels.signal.textChunkLimit 分块（默认 4000）。
• 可选的换行分块：设置 channels.signal.chunkMode="newline"，先按空行（段落边界）拆分，再按长度分块。
• 支持附件（从 signal-cli 获取 base64）。
• 当缺少 contentType 时，语音笔记附件会使用 signal-cli 文件名作为 MIME 回退，因此音频转录仍可识别 AAC 语音备忘录。
• 默认媒体上限：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 不会公开群组的已读回执。

​

生命周期状态表情回应

​

表情回应（消息工具）

• 目标：发送者 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（默认 minimal）。
  • off/ack 会禁用智能体表情回应（消息工具 react 会报错）。
  • minimal/extensive 会启用智能体表情回应并设置引导级别。
• 按账号覆盖：channels.signal.accounts.<id>.actions.reactions、channels.signal.accounts.<id>.reactionLevel。

​

审批表情回应

• 👍 批准一次。
• 👎 拒绝。
• 当请求提供持久审批时，使用 /approve <id> allow-always。

​

投递目标（CLI/cron）

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

​

别名

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
        jane: "uuid:123e4567-e89b-12d3-a456-426614174000",
        ops: "group:<groupId>",
      },
      defaultTo: "signal:me",
    },
  },
}

openclaw message send --channel signal --target signal:ops --message "Deployment is complete"

{
  channels: {
    signal: {
      aliases: {
        me: "+15557654321",
      },
      accounts: {
        work: {
          aliases: {
            ops: "group:<workGroupId>",
          },
        },
      },
    },
  },
}

​

故障排查

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

openclaw pairing list signal

• 守护进程可访问但没有回复：验证账号/守护进程设置（httpUrl、account）和接收模式。
• 私信被忽略：发送者正在等待配对审批。
• 群组消息被忽略：群组发送者/提及门控阻止了投递。
• 编辑后出现配置验证错误：运行 openclaw doctor --fix。
• 诊断中缺少 Signal：确认 channels.signal.enabled: true。

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）

• channels.signal.enabled：启用/禁用渠道启动。
• channels.signal.apiMode：auto | native | container（默认：auto）。参见 容器模式。
• channels.signal.account：机器人账号的 E.164。
• channels.signal.cliPath：指向 signal-cli 的路径。
• channels.signal.configPath：可选的 signal-cli --config 目录。
• 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：启动等待超时时间，单位 ms（最小 1000，上限 120000；默认 30000）。
• channels.signal.receiveMode：on-start | manual。
• channels.signal.ignoreAttachments：跳过附件下载。
• channels.signal.ignoreStories：忽略来自守护进程的动态。
• channels.signal.sendReadReceipts：转发已读回执。
• channels.signal.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）。
• channels.signal.allowFrom：私信允许列表（E.164 或 uuid:<id>）。open 需要 "*"。Signal 没有用户名；使用电话/UUID ID。
• channels.signal.aliases：用于私信或群组投递目标的 OpenClaw 侧别名。
• channels.signal.groupPolicy：open | allowlist | disabled（默认：allowlist）。
• channels.signal.groupAllowFrom：群组允许列表；接受 Signal 群组 ID（原始值、group:<id> 或 signal:group:<id>）、发送者 E.164 号码或 uuid:<id> 值。
• channels.signal.groups：按群组覆盖，键为 Signal 群组 ID（或 "*"）。支持字段：requireMention、tools、toolsBySender。
• channels.signal.accounts.<id>.groups：用于多账号设置的 channels.signal.groups 按账号版本。
• channels.signal.accounts.<id>.aliases：按账号别名，与顶层别名合并。
• channels.signal.historyLimit：作为上下文包含的最大群组消息数（0 表示禁用）。
• channels.signal.dmHistoryLimit：以用户轮次计的私信历史限制。按用户覆盖：channels.signal.dms["<phone_or_uuid>"].historyLimit。
• channels.signal.textChunkLimit：出站分块大小，单位字符（默认 4000）。
• channels.signal.chunkMode：length（默认）或 newline，用于在按长度分块前按空行（段落边界）拆分。
• channels.signal.mediaMaxMb：入站/出站媒体上限，单位 MB（默认 8）。
• channels.signal.reactionLevel：off | ack | minimal | extensive（默认 minimal）。参见 表情回应。
• channels.signal.reactionNotifications：off | own | all | allowlist（默认 own）- 智能体何时接收来自他人的传入表情回应通知。
• channels.signal.reactionAllowlist：当 reactionNotifications: "allowlist" 时，其表情回应会通知智能体的发送者。
• channels.signal.blockStreaming、channels.signal.blockStreamingCoalesce：跨渠道共享的块模式流式传输控制。参见 流式传输。

• agents.list[].groupChat.mentionPatterns（Signal 不支持原生提及）。
• messages.groupChat.mentionPatterns（全局回退）。
• messages.responsePrefix。

​

相关

• 渠道概览 - 所有支持的渠道
• 配对 - 私信身份验证和配对流程
• 群组 - 群聊行为和提及门控
• 频道路由 - 消息的会话路由
• 安全 - 访问模型和加固