將 OpenClaw 連接到 Signal：5 分鐘完成設定指南

先決條件

你的伺服器上已安裝 OpenClaw（下方的 Linux 流程已在 Ubuntu 24 測試過）。
執行 Gateway 的主機上可以使用 signal-cli。
一個可以接收簡訊驗證碼的電話號碼（用於 SMS 註冊路徑）。
註冊期間需要瀏覽器存取 Signal captcha (signalcaptchas.org)。

快速設定（初學者）

建議為機器人使用獨立的 Signal 號碼。
安裝 signal-cli（如果你使用 JVM 版本，則需要 Java）。
選擇一種設定路徑：
- 路徑 A (QR 連結)： 執行 signal-cli link -n "OpenClaw" 並用 Signal 掃描。
- 路徑 B (SMS 註冊)： 使用 captcha 和簡訊驗證註冊專用號碼。
設定 OpenClaw 並重啟 Gateway。
發送第一則私訊 (DM) 並核准配對 (openclaw pairing approve signal <CODE>)。

最小配置範例：

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

欄位參考：

欄位	描述
`account`	E.164 格式的機器人電話號碼 (`+15551234567`)
`cliPath`	`signal-cli` 的路徑（如果在 `PATH` 中則填 `signal-cli`）
`dmPolicy`	私訊存取策略（建議使用 `pairing`）
`allowFrom`	允許傳送私訊的電話號碼或 `uuid:<id>` 值

這是什麼

透過 signal-cli 運作的 Signal 頻道（而非內嵌的 libsignal）。
確定性路由：回覆總是會傳回 Signal。
私訊會共用 Agent 的主對話；群組則是獨立的 (agent:<agentId>:signal:group:<groupId>)。

設定寫入權限

預設情況下，Signal 被允許寫入由 /config set|unset 觸發的設定更新（需要 commands.config: true）。

你可以使用以下方式停用：

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

門號模型（重要）

Gateway 會連接到一個 Signal 裝置（也就是 signal-cli 帳號）。
如果你在個人的 Signal 帳號上執行機器人，它會忽略你發出的訊息（這是為了防止無限迴圈）。
如果你想要實現「我傳訊息給機器人，它會回覆我」的功能，請使用一個獨立的機器人門號。

設定路徑 A：連結現有的 Signal 帳號 (QR)

安裝 signal-cli（JVM 或 native 版本）。
連結機器人帳號：
- 執行 signal-cli link -n "OpenClaw"，然後用 Signal 掃描 QR code。
設定 Signal 並啟動 Gateway。

範例：

{
  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 的門號（市話則使用語音驗證）。
- 建議使用專用的機器人門號，以避免帳號或 session 衝突。
在 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

如果你使用 JVM 版本 (signal-cli-${VERSION}.tar.gz)，請先安裝 JRE 25+。請保持 signal-cli 為最新版本；上游開發者提到，隨著 Signal 伺服器 API 的變動，舊版本可能會失效。

註冊並驗證門號：

signal-cli -a +<BOT_PHONE_NUMBER> register

如果需要驗證碼 (captcha)：

開啟 https://signalcaptchas.org/registration/generate.html。
完成驗證，從 “Open Signal” 按鈕中複製 signalcaptcha://... 連結目標。
盡可能在與瀏覽器相同的外部 IP 下執行指令。
立即再次執行註冊（驗證碼 token 很快就會過期）：

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

設定 OpenClaw，重啟 Gateway 並驗證 Channel：

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

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

配對你的 DM 傳送者：
- 傳送任何訊息到機器人門號。
- 在伺服器上核准代碼：openclaw pairing approve signal <PAIRING_CODE>。
- 將機器人門號儲存到你手機的聯絡人中，以避免顯示為「未知聯絡人」。

重要提示：使用 signal-cli 註冊門號帳號可能會導致該門號原本的 Signal App session 失效。建議優先使用專用的機器人門號，或者如果你需要保留現有的手機 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)

外部 Daemon 模式 (httpUrl)

如果你想自行管理 signal-cli（例如為了解決 JVM 冷啟動慢、容器初始化或共享 CPU 的問題），可以單獨執行 daemon 並讓 OpenClaw 指向它：

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

這會跳過 OpenClaw 內部的自動產生 (auto-spawn) 與啟動等待。如果在使用自動產生模式時啟動太慢，請設定 channels.signal.startupTimeoutMs。

存取控制 (私訊 + 群組)

私訊 (DMs)：

預設值：channels.signal.dmPolicy = "pairing"。
未知傳送者會收到配對碼；在核准前訊息會被忽略（配對碼 1 小時後過期）。
透過以下方式核准：
- openclaw pairing list signal
- openclaw pairing approve signal <CODE>
Pairing 是 Signal 私訊預設的 token 交換方式。詳情請看：Pairing
僅限 UUID 的傳送者（來自 sourceUuid）會以 uuid:<id> 格式儲存在 channels.signal.allowFrom 中。

群組：

channels.signal.groupPolicy = open | allowlist | disabled。
當設定為 allowlist 時，channels.signal.groupAllowFrom 控制誰可以在群組中觸發機器人。
channels.signal.groups["<group-id>" | "*"] 可以透過 requireMention、tools 和 toolsBySender 來覆蓋群組行為。
在多帳號設定中，使用 channels.signal.accounts.<id>.groups 進行個別帳號的覆蓋。
執行階段筆記：如果完全缺少 channels.signal 設定，系統在進行群組檢查時會退回到 groupPolicy="allowlist"（即使已設定 channels.defaults.groupPolicy）。

運作原理 (行為)

signal-cli 以 daemon 模式執行；Gateway 透過 SSE 讀取事件。
進入的訊息會被正規化為共享的 channel envelope。
回覆總是會路由回同一個號碼或群組。

媒體與限制

外傳文字會依照 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）。

輸入中狀態與已讀回執

輸入中指標 (Typing indicators)：OpenClaw 透過 signal-cli sendTyping 傳送輸入訊號，並在回覆執行期間持續更新。
已讀回執 (Read receipts)：當 channels.signal.sendReadReceipts 為 true 時，OpenClaw 會轉發已核准私訊的已讀回執。
signal-cli 不支援顯示群組的已讀回執。

表情回應 (message tool)

你可以使用 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 tool 的 react 會報錯）。
- minimal/extensive 會啟用 Agent 的表情回應並設定引導層級。
個別帳號覆寫設定：channels.signal.accounts.<id>.actions.reactions、channels.signal.accounts.<id>.reactionLevel。

傳送目標 (CLI/cron)

在 CLI 或 cron 任務中，你可以使用以下格式來指定傳送目標：

私訊 (DMs)：signal:+15551234567（或直接使用 E.164 格式）。
UUID 私訊：uuid:<id>（或直接輸入 UUID）。
群組：signal:group:<groupId>。
使用者名稱：username:<name>（前提是你的 Signal 帳號支援此功能）。

故障排除

遇到問題時，先照著這個順序跑一遍：

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

如果有需要，再確認一下 DM 的配對狀態：

openclaw pairing list signal

常見問題：

Daemon 可以連上但沒有回應：檢查你的帳號或 Daemon 設定（httpUrl, account）以及接收模式。
DM 被忽略：傳送者還在等待配對審核。
群組訊息被忽略：群組傳送者或提及（mention）的過濾機制擋住了傳輸。
修改後出現設定驗證錯誤：執行 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

完整的排錯流程請看：/channels/troubleshooting。

安全注意事項

signal-cli 會把帳號金鑰存在本地端（通常在 ~/.local/share/signal-cli/data/）。
在遷移伺服器或重建之前，記得先備份 Signal 的帳號狀態。
除非你明確想要更開放的 DM 存取權限，否則建議維持 channels.signal.dmPolicy: "pairing"。
雖然只有在註冊或復原流程才需要 SMS 驗證，但如果弄丟門號或帳號主控權，重新註冊會變得很麻煩。

Signal 配置參考

完整的配置請參考：Configuration

Provider 選項：

channels.signal.enabled: 開啟或關閉頻道。
channels.signal.account: 機器人帳號的 E.164 格式號碼。
channels.signal.cliPath: signal-cli 的路徑。
channels.signal.httpUrl: 完整的 daemon URL（會覆蓋 host/port 設定）。
channels.signal.httpHost, channels.signal.httpPort: daemon 綁定的位址（預設為 127.0.0.1:8080）。
channels.signal.autoStart: 自動啟動 daemon（如果未設定 httpUrl，預設為 true）。
channels.signal.startupTimeoutMs: 啟動等待超時，單位為毫秒（最高 120000）。
channels.signal.receiveMode: on-start | manual。
channels.signal.ignoreAttachments: 跳過附件下載。
channels.signal.ignoreStories: 忽略來自 daemon 的限時動態 (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（或 "*"）作為 key。支援的欄位：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)。

相關全域選項：

agents.list[].groupChat.mentionPatterns (Signal 不支援原生 mention)。
messages.groupChat.mentionPatterns (全域備援設定)。
messages.responsePrefix。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。