Signal

​

號碼模型（請先閱讀）

• 閘道會連線到一個 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 帳號（QR）

1. 安裝 signal-cli（JVM 或原生建置），或讓 openclaw channels add 為你安裝。
2. 連結機器人帳號：signal-cli link -n "OpenClaw"，然後在 Signal 中掃描 QR。
3. 設定 Signal 並啟動閘道。

​

設定路徑 B：註冊專用機器人號碼（SMS，Linux）

1. 取得可接收 SMS 的號碼（或市話可用語音驗證）。專用機器人號碼可避免帳號／工作階段衝突。
2. 在閘道主機上安裝 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. 完成 captcha，從「Open Signal」複製 signalcaptcha://... 連結目標。
3. 可行時，請從與瀏覽器工作階段相同的外部 IP 執行（captcha token 很快就會過期）。
4. 立即註冊並驗證：

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

4. 設定 OpenClaw、重新啟動閘道，並驗證頻道：

# 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
• Captcha 流程：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 私訊的預設 token 交換。詳細資訊：配對
• 僅 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，執行階段會在群組檢查時 fallback 到 groupPolicy="allowlist"（即使已設定 channels.defaults.groupPolicy）。

​

運作方式（行為）

• 原生模式：signal-cli 以守護程式執行；閘道透過 SSE 讀取事件。
• 容器模式：閘道透過 REST API 傳送，並透過 WebSocket 接收。
• 傳入訊息會正規化為共享頻道 envelope。
• 回覆一律路由回相同號碼或群組。

​

媒體 + 限制

• 外送文字會依 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。

​

傳遞目標（命令列介面/排程）

• 私訊：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（覆寫主機/連接埠）。
• channels.signal.httpHost、channels.signal.httpPort：常駐程式綁定（預設 127.0.0.1:8080）。
• channels.signal.autoStart：自動產生常駐程式（如果未設定 httpUrl，預設為 true）。
• channels.signal.startupTimeoutMs：啟動等待逾時，單位為毫秒（最小 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。

​

相關

• 頻道概觀 - 所有支援的頻道
• 配對 - 私訊驗證與配對流程
• 群組 - 群組聊天行為與提及閘控
• 頻道路由 - 訊息的工作階段路由
• 安全 - 存取模型與強化