OpenClaw Signal 渠道
即时通讯
困难
通过 signal-cli 将 OpenClaw 连接到 Signal —— 这是一个第三方开源的 Signal 协议命令行客户端。此集成提供隐私优先的 AI 消息通信，支持完整的端到端加密。OpenClaw 通过 HTTP JSON-RPC 和 Server-Sent Events 与 signal-cli 守护进程通信，让你的 AI 助手可以在 Signal 上收发消息。机器人账号需要一个专用手机号。
快速信息
难度困难
分类即时通讯
支持功能数4 / 6
Signal 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
支持
消息线程
不支持
语音消息
不支持
群聊
支持
Signal 前置条件
- Signal 机器人账号的专用手机号（与个人号码分开）
- 服务器已安装 Java 运行时环境（JRE 25+）
- 已安装 signal-cli 并可在 PATH 中访问
- OpenClaw Gateway 已运行并配置
- 一个现有的 Signal 账号用于关联机器人（或进行新注册）
Signal 快速设置
1
安装 signal-cli
从官方 GitHub 仓库下载并安装 signal-cli。它需要 Java 25 或更高版本。在终端运行 'signal-cli --version' 验证安装是否成功。
2
关联或注册 Signal 账号
运行 'signal-cli link -n "OpenClaw"' 将 signal-cli 关联到现有 Signal 账号，然后从另一台设备扫描二维码。或者运行 'signal-cli -a +15551234567 register' 注册新账号。请使用专用号码 —— 在个人账号上运行会导致自发消息循环。
3
添加 Signal 渠道配置
在 ~/.openclaw/openclaw.json 中添加 Signal 渠道配置。将 'account' 字段设置为机器人的 E.164 格式手机号，并配置 dmPolicy（pairing、allowlist 或 open）来控制谁可以给你的助手发消息。
4
启动 Gateway 并发送测试消息
启动 Gateway 进程。OpenClaw 会自动启动 signal-cli 守护进程。从另一个 Signal 账号向机器人号码发送消息。如果使用默认的 pairing 策略，需通过 'openclaw pairing approve signal <code>' 审批发送者。
Signal 配置示例
config.json
{
"channels": {
"signal": {
"enabled": true,
"account": "+15551234567",
"dmPolicy": "pairing"
}
}
}Signal 深入了解
架构概述
OpenClaw 通过 signal-cli 连接 Signal —— 这是一个基于 Java 的命令行客户端，实现了完整的 Signal 协议。架构使用 HTTP JSON-RPC 接口和 Server-Sent Events (SSE) 实现实时消息传递。
默认情况下，OpenClaw 在 Gateway 启动时自动生成一个 signal-cli 守护进程。该守护进程处理所有 Signal 协议操作（加密、密钥交换、消息收发），而 OpenClaw 通过本地 HTTP API 与其通信。这使得 Signal 协议层与 AI 逻辑完全分离。
你也可以将 signal-cli 作为外部守护进程运行，并通过 httpUrl 配置将 OpenClaw 指向它 —— 这适用于独立管理 signal-cli 或在不同主机上运行的场景。
自动启动的守护进程默认绑定到 127.0.0.1:8080。如需不同地址，请修改 httpHost 和 httpPort。
外部运行 signal-cli 可以让你更好地控制更新和生命周期管理。将 httpUrl 设置为完整的守护进程 URL 即可禁用自动启动。
Signal 账号设置
你的机器人需要一个专用 Signal 账号。不要使用个人号码 —— Signal 会忽略自发消息，在同一号码上同时运行个人和机器人账号会导致路由冲突。
账号设置有两种方式：
• 关联到现有设备 —— 运行 'signal-cli link -n "OpenClaw"' 生成设备关联 URI。从主 Signal 应用扫描二维码。这是推荐的方式，因为最简单。
• 全新注册 —— 运行 'signal-cli -a +15551234567 register' 直接注册新的 Signal 账号。你需要通过短信或语音电话验证号码。
关联或注册完成后，signal-cli 会将凭证和密钥存储在本地。这些信息在重启后仍然有效。
openclaw.json
{
"channels": {
"signal": {
"account": "+15551234567",
"cliPath": "/usr/local/bin/signal-cli"
}
}
}避免在个人 Signal 号码上运行机器人。Signal 的自发消息保护机制会忽略发给自己的消息，机器人将无法正常工作。
外部守护进程模式
对于高级部署，你可以在 OpenClaw 外部将 signal-cli 作为独立守护进程运行。当你需要独立管理 signal-cli 更新、在单独的机器上运行，或在多个服务之间共享单个守护进程时，这非常有用。
手动启动守护进程：
signal-cli -a +15551234567 daemon --http=127.0.0.1:8080
然后通过设置 httpUrl 将 OpenClaw 指向它。配置了 httpUrl 后，OpenClaw 会跳过自动启动守护进程，转而连接到现有进程。
openclaw.json
{
"channels": {
"signal": {
"account": "+15551234567",
"httpUrl": "http://127.0.0.1:8080/api/v1/rpc"
}
}
}使用外部守护进程时，请确保在 Gateway 之前启动它。OpenClaw 会等待最多 startupTimeoutMs（最长 120 秒）直到守护进程可用。
私信策略
私信（DM）策略控制谁可以在私聊中与你的 AI 助手交互。OpenClaw 支持四种策略：
• pairing（默认）—— 新联系人首次给机器人发消息时会收到一个随机配对码。配对码在 1 小时后过期。在终端通过 'openclaw pairing approve signal <code>' 进行审批。审批通过后即可自由聊天。
• allowlist —— 只有 allowFrom 中列出的手机号或 UUID 可以给机器人发消息。其他人将被静默忽略。手机号使用 E.164 格式，纯 UUID 联系人使用 'uuid:<id>' 格式。
• open —— 任何给机器人发消息的人都会收到回复。需要在 allowFrom 列表中添加 '*' 作为安全确认。请谨慎使用。
• disabled —— 完全关闭私信功能。
openclaw.json
{
"channels": {
"signal": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567", "uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}
}
}注册 Signal 时未分享手机号的联系人将在 allowFrom 列表中显示为 'uuid:<id>'。查看 Gateway 日志可获取他们的 UUID。
可通过 dms["<phone_or_uuid>"].historyLimit 为每个联系人设置独立的历史限制，覆盖全局的 dmHistoryLimit。
群聊管理
OpenClaw 支持 Signal 群聊，并提供可配置的访问控制：
• open —— 接受所有群成员的消息
• allowlist —— 只有已批准的发送者（通过 groupAllowFrom）可以触发机器人
• disabled —— 忽略所有群消息
群聊对话与私信完全隔离。消息以 'agent:<agentId>:signal:group:<groupId>' 标记，为每个群组维护独立的上下文和历史。
你可以为每个群组配置 historyLimit 来控制包含多少条消息作为 AI 上下文（默认 50，设为 0 禁用历史）。
openclaw.json
{
"channels": {
"signal": {
"groupPolicy": "open",
"historyLimit": 50
}
}
}隐私与端到端加密
Signal 是私密通信的黄金标准。机器人与联系人之间的所有消息都使用 Signal 协议（Double Ratchet 算法 + X3DH 密钥协商）进行端到端加密。OpenClaw 在传输过程中永远无法看到明文消息 —— 解密在你服务器上的 signal-cli 进程中本地完成。
关键隐私特性：
• 消息在客户端之间加密 —— Signal 的服务器无法读取它们
• signal-cli 将加密密钥存储在你的服务器本地
• 没有数据通过 Anthropic、OpenAI 或任何第三方 AI 提供商的基础设施传输（消息在本地解密，由你的自托管 Gateway 处理，只有对话上下文被发送到你配置的 AI 提供商）
• 可通过 ignoreStories: true 完全忽略动态事件
为了获得最高隐私性，可将 Signal 与本地托管的 LLM 提供商（如 Ollama）结合使用，让所有数据完全保留在你的基础设施上。
表情回应
OpenClaw 支持在 Signal 消息上发送和接收表情回应。回应可用于确认（让用户知道消息已收到）和交互式代理行为。
回应语法使用消息工具，目标格式为 E.164 手机号、UUID 格式或群组格式：
• 私信回应：target=+15551234567 或 target=uuid:<id>
• 群组回应：target=signal:group:<groupId>，附带 targetAuthor=uuid:<sender>
全局或按账号配置回应行为：
• actions.reactions —— 启用/禁用回应功能（默认 true）
• reactionLevel —— off/ack（禁用）或 minimal/extensive（启用并附带指引）
openclaw.json
{
"channels": {
"signal": {
"reactionLevel": "minimal"
}
}
}媒体与附件
OpenClaw 可处理 Signal 上的媒体文件，包括图片、文档、音频和视频。媒体通过 signal-cli 以 base64 编码数据传输。
入站媒体会自动下载并处理，除非将 ignoreAttachments 设为 true。出站媒体在发送前通过 signal-cli 进行 base64 获取。
默认文件大小限制为 8 MB（mediaMaxMb）。Signal 本身支持更大的文件，但 base64 编码开销和处理时间使 8 MB 成为一个实用的默认值。
openclaw.json
{
"channels": {
"signal": {
"mediaMaxMb": 8,
"ignoreAttachments": false
}
}
}输入指示器与已读回执
OpenClaw 在生成 AI 回复时发送输入指示器，以保持自然的对话体验。Gateway 调用 signal-cli 的 sendTyping 端点，并在回复生成期间定期刷新指示器。
启用 sendReadReceipts 后，可以为已批准的私信联系人转发已读回执，让发送者知道消息已被处理。
注意：signal-cli 不支持群组已读回执。
openclaw.json
{
"channels": {
"signal": {
"sendReadReceipts": true
}
}
}文本分块与发送
对于较长的 AI 回复，OpenClaw 会自动将文本拆分为多条消息。默认分块大小为每条消息 4,000 个字符。
提供两种分块模式：
• length（默认）—— 在字符限制处硬性拆分
• newline —— 优先在段落边界拆分，然后应用字符限制
发送目标使用 E.164 手机号、UUID 或群组 ID：
• 私信：signal:+15551234567 或直接使用 E.164 号码
• UUID 私信：uuid:<id> 或直接使用 UUID
• 群组：signal:group:<groupId>
openclaw.json
{
"channels": {
"signal": {
"textChunkLimit": 4000,
"chunkMode": "newline"
}
}
}Signal 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用 Signal 渠道 |
| account | string | "" | 机器人的 E.164 格式手机号（例如 +15551234567）。必填 |
| cliPath | string | "signal-cli" | signal-cli 可执行文件的路径 |
| httpUrl | string | "" | 外部 signal-cli 守护进程的完整 URL。设置后将禁用自动启动 |
| httpHost | string | "127.0.0.1" | 自动启动的 signal-cli 守护进程绑定的主机地址 |
| httpPort | number | 8080 | 自动启动的 signal-cli 守护进程绑定的端口 |
| autoStart | boolean | true | 是否在 Gateway 启动时自动生成 signal-cli 守护进程 |
| startupTimeoutMs | number | 30000 | 等待 signal-cli 守护进程可用的最长时间（毫秒）。最大值 120000 |
| dmPolicy | string | "pairing" | 控制谁可以私信机器人。选项：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 允许给机器人发消息的手机号（E.164 格式）或 uuid:<id> 标识符 |
| dmHistoryLimit | number | 50 | 每个对话中包含的最近私信消息数量，作为 AI 上下文 |
| groupPolicy | string | "disabled" | 群聊策略。选项：disabled、allowlist、open |
| groupAllowFrom | string[] | [] | 允许在群组中触发机器人的手机号或 UUID（groupPolicy 为 allowlist 时使用） |
| historyLimit | number | 50 | 包含的最大群消息数量，作为 AI 上下文。设为 0 禁用 |
| sendReadReceipts | boolean | false | 是否为已批准的私信联系人转发已读回执信号 |
| textChunkLimit | number | 4000 | 分块前每条出站消息的最大字符数 |
| chunkMode | string | "length" | 文本分块模式。选项：length（硬性拆分）、newline（段落感知） |
| mediaMaxMb | number | 8 | 入站/出站附件的最大媒体文件大小（兆字节） |
| ignoreAttachments | boolean | false | 跳过下载入站媒体附件 |
| ignoreStories | boolean | false | 完全忽略 Signal 动态事件 |
| receiveMode | string | "" | 消息接收模式。选项：on-start（启动时获取）、manual |
| configWrites | boolean | true | 允许 /config 命令在运行时修改渠道设置 |
| reactionLevel | string | "ack" | 机器人回应能力。选项：off、ack、minimal、extensive |
enabled
Type: booleanDefault: true
启用或禁用 Signal 渠道
account
Type: stringDefault: ""
机器人的 E.164 格式手机号（例如 +15551234567）。必填
cliPath
Type: stringDefault: "signal-cli"
signal-cli 可执行文件的路径
httpUrl
Type: stringDefault: ""
外部 signal-cli 守护进程的完整 URL。设置后将禁用自动启动
httpHost
Type: stringDefault: "127.0.0.1"
自动启动的 signal-cli 守护进程绑定的主机地址
httpPort
Type: numberDefault: 8080
自动启动的 signal-cli 守护进程绑定的端口
autoStart
Type: booleanDefault: true
是否在 Gateway 启动时自动生成 signal-cli 守护进程
startupTimeoutMs
Type: numberDefault: 30000
等待 signal-cli 守护进程可用的最长时间（毫秒）。最大值 120000
dmPolicy
Type: stringDefault: "pairing"
控制谁可以私信机器人。选项：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
允许给机器人发消息的手机号（E.164 格式）或 uuid:<id> 标识符
dmHistoryLimit
Type: numberDefault: 50
每个对话中包含的最近私信消息数量，作为 AI 上下文
groupPolicy
Type: stringDefault: "disabled"
群聊策略。选项：disabled、allowlist、open
groupAllowFrom
Type: string[]Default: []
允许在群组中触发机器人的手机号或 UUID（groupPolicy 为 allowlist 时使用）
historyLimit
Type: numberDefault: 50
包含的最大群消息数量，作为 AI 上下文。设为 0 禁用
sendReadReceipts
Type: booleanDefault: false
是否为已批准的私信联系人转发已读回执信号
textChunkLimit
Type: numberDefault: 4000
分块前每条出站消息的最大字符数
chunkMode
Type: stringDefault: "length"
文本分块模式。选项：length（硬性拆分）、newline（段落感知）
mediaMaxMb
Type: numberDefault: 8
入站/出站附件的最大媒体文件大小（兆字节）
ignoreAttachments
Type: booleanDefault: false
跳过下载入站媒体附件
ignoreStories
Type: booleanDefault: false
完全忽略 Signal 动态事件
receiveMode
Type: stringDefault: ""
消息接收模式。选项：on-start（启动时获取）、manual
configWrites
Type: booleanDefault: true
允许 /config 命令在运行时修改渠道设置
reactionLevel
Type: stringDefault: "ack"
机器人回应能力。选项：off、ack、minimal、extensive
Signal 常见问题
Signal 故障排查
signal-cli 启动失败并出现 Java 错误
Java 未安装，或安装的版本太旧。signal-cli 需要 Java 25 或更高版本。
在服务器上安装 OpenJDK 25+。通过 'java --version' 验证。如果安装了多个 Java 版本，确保 PATH 中是正确的版本或设置 JAVA_HOME。同时运行 'signal-cli --version' 验证 signal-cli 安装是否正确。
机器人不响应任何消息
account 字段可能不正确，signal-cli 守护进程可能未运行，或发送者尚未通过配对审批。
检查 account 号码是否与已注册的 signal-cli 账号匹配（带国家代码的 E.164 格式）。运行 'openclaw status' 和 'openclaw gateway status' 验证守护进程是否正在运行。如果使用 pairing 策略，通过 'openclaw pairing list signal' 检查待处理的配对并审批发送者。
审批后私信仍被忽略
发送者可能不在 allowFrom 列表中（使用 allowlist 策略时），或发送者的标识符格式不匹配。
查看 Gateway 日志获取发送者的标识符。一些 Signal 用户注册时未分享手机号 —— 他们将显示为 'uuid:<id>' 而非手机号。将正确的标识符添加到 allowFrom。运行 'openclaw channels status --probe' 获取详细的渠道诊断信息。
群消息未被接收
groupPolicy 设为 'disabled'（默认值），或群组不在允许列表中。
将 groupPolicy 设为 'open' 以接受所有群消息，或使用 'allowlist' 并将群组 ID 添加到 groupAllowFrom。收到群消息时查看 Gateway 日志获取群组 ID。
外部守护进程连接失败（httpUrl 不可达）
signal-cli 守护进程未运行，URL 不正确，或防火墙阻止了连接。
确认守护进程正在运行并监听预期的 host:port。通过 'curl http://127.0.0.1:8080/api/v1/rpc' 测试连接性。如果跨机器运行，请检查防火墙规则。确保守护进程启动时使用的 --http 参数与 httpUrl 配置匹配。