Signal (signal-cli)

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

快速设置（入门）

为机器人使用独立 Signal 号码（推荐）。
安装 signal-cli（需 Java）。
链接设备并启动守护进程：
- signal-cli link -n "Moltbot"
配置 Moltbot 并启动网关。

最小配置：


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

说明

通过 signal-cli 的 Signal 频道（非内嵌 libsignal）。
确定性路由：回复始终发回 Signal。
私聊共享 agent 主会话；群组独立（agent:<agentId>:signal:group:<groupId>）。

配置写入

默认允许 Signal 写入由 /config set|unset 触发的配置更新（需 commands.config: true）。禁用方式：


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

号码模型（重要）

网关连接的是一个 Signal 设备（即 signal-cli 账号）。
若用个人 Signal 账号跑机器人，会忽略你自己的消息（防回环）。
要实现「你发消息给机器人、机器人回复」，请用独立的机器人号码。

设置（快速路径）

安装 signal-cli（需 Java）。
链接机器人账号：
- signal-cli link -n "Moltbot"，然后在 Signal 里扫二维码。
配置 Signal 并启动网关。

示例：


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

多账号：使用 channels.signal.accounts，每账号单独配置并可设 name。共享模式见配置。

外部守护进程模式（httpUrl）

若希望自行管理 signal-cli（JVM 冷启动慢、容器初始化或共享 CPU），可单独运行守护进程并让 Moltbot 指向它：


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

这样会跳过自动启动及 Moltbot 内的启动等待。自动启动时若启动较慢，可设置 channels.signal.startupTimeoutMs。

访问控制（私聊 + 群组）

私聊：

默认：channels.signal.dmPolicy = "pairing"。
未知发件人收到配对码；在批准前消息被忽略（配对码 1 小时后过期）。
批准方式：
- moltbot pairing list signal
- moltbot pairing approve signal <CODE>
配对是 Signal 私聊的默认 token 交换方式。详见配对。
仅 UUID 的发件人（来自 sourceUuid）在 channels.signal.allowFrom 中存为 uuid:<id>。

群组：

channels.signal.groupPolicy = open | allowlist | disabled。
channels.signal.groupAllowFrom 在设为 allowlist 时控制谁可在群组中触发。

行为说明

signal-cli 以守护进程运行；网关通过 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）。

输入中与已读回执

输入中：Moltbot 通过 signal-cli sendTyping 发送输入中信号，并在回复进行中刷新。
已读回执：当 channels.signal.sendReadReceipts 为 true 时，Moltbot 会转发已放行私聊的已读回执。
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 账号支持）。

配置参考（Signal）

完整配置见配置。本频道选项：

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）。
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.historyLimit：作为上下文的群组消息上限（0 表示禁用）。
channels.signal.dmHistoryLimit：私聊历史轮次上限。每用户覆盖：channels.signal.dms["<phone_or_uuid>"].historyLimit。
channels.signal.textChunkLimit：出站分块大小（字符）。
channels.signal.chunkMode：length（默认）或 newline，在按长度分块前按空行（段落边界）拆分。
channels.signal.mediaMaxMb：入站/出站媒体上限（MB）。