​

Signal (signal-cli)

​

Thiết lập nhanh (cho người mới)

• Dùng một số Signal riêng cho bot (khuyến nghị).
• Cài đặt signal-cli (cần Java).
• Liên kết thiết bị bot và khởi động daemon:
• Cấu hình OpenClaw và khởi động gateway.

​

Thiết lập nhanh (cho người mới)

1. Dùng một số Signal riêng cho bot (khuyến nghị).
2. Cài đặt signal-cli (yêu cầu Java nếu bạn sử dụng bản build JVM).
3. Chọn một trong các cách thiết lập:
   • Cách A (liên kết QR): signal-cli link -n "OpenClaw" và quét bằng Signal.
   • Cách B (đăng ký SMS): đăng ký một số chuyên dụng với captcha + xác minh SMS.
4. Cấu hình OpenClaw và khởi động lại gateway.
5. Gửi DM đầu tiên và chấp thuận ghép nối (openclaw pairing approve signal <CODE>).

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

​

Nó là gì

• Kênh Signal qua signal-cli (không phải libsignal nhúng).
• Định tuyến xác định: phản hồi luôn quay lại Signal.
• DM dùng chung phiên chính của tác tử; nhóm được cô lập (agent:<agentId>:signal:group:<groupId>).

​

Mô hình số (quan trọng)

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

​

Mô hình số (quan trọng)

• Gateway kết nối tới một thiết bị Signal (tài khoản signal-cli).
• Nếu chạy bot trên tài khoản Signal cá nhân của bạn, nó sẽ bỏ qua tin nhắn của chính bạn (bảo vệ vòng lặp).
• Để có hành vi “tôi nhắn bot và nó trả lời”, hãy dùng một số bot riêng.

​

Thiết lập cách A: liên kết tài khoản Signal hiện có (QR)

1. Cài đặt signal-cli (bản JVM hoặc bản native).
2. Liên kết một tài khoản bot:
   • signal-cli link -n "OpenClaw" rồi quét QR trong Signal.
3. Cấu hình Signal và khởi động gateway.

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

​

Kiểm soát truy cập (DM + nhóm)

1. Mặc định: channels.signal.dmPolicy = "pairing".
   • Sử dụng một số bot chuyên dụng để tránh xung đột tài khoản/phiên.
2. Người gửi chưa biết sẽ nhận mã ghép cặp; tin nhắn bị bỏ qua cho đến khi được duyệt (mã hết hạn sau 1 giờ).

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. Đăng ký và xác minh số điện thoại:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Văn bản gửi đi được chia khối theo channels.signal.textChunkLimit (mặc định 4000).
2. Tùy chọn chia theo dòng mới: đặt channels.signal.chunkMode="newline" để tách theo dòng trống (ranh giới đoạn) trước khi chia theo độ dài.
3. Hỗ trợ tệp đính kèm (base64 lấy từ signal-cli).
4. Giới hạn media mặc định: channels.signal.mediaMaxMb (mặc định 8).

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

4. Chỉ báo đang gõ: OpenClaw gửi tín hiệu đang gõ qua signal-cli sendTyping và làm mới trong khi đang tạo phản hồi.

# Nếu bạn chạy gateway dưới dạng dịch vụ systemd của người dùng:
systemctl --user restart openclaw-gateway

# Sau đó xác minh:
openclaw doctor
openclaw channels status --probe

5. Dùng message action=react với channel=signal.
   • Gửi bất kỳ tin nhắn nào đến số bot.
   • Phê duyệt mã trên máy chủ: openclaw pairing approve signal <PAIRING_CODE>.
   • Lưu số bot vào danh bạ trên điện thoại để tránh hiển thị “Unknown contact”.

• signal-cli README: https://github.com/AsamK/signal-cli
• Luồng captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Luồng liên kết: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Chế độ daemon bên ngoài (httpUrl)

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

​

Kiểm soát truy cập (DM + nhóm)

• Mặc định: channels.signal.dmPolicy = "pairing".
• Người gửi chưa biết sẽ nhận mã ghép cặp; tin nhắn bị bỏ qua cho đến khi được duyệt (mã hết hạn sau 1 giờ).
• Duyệt qua:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Pairing is the default token exchange for Signal DMs. Details: Pairing
• Người gửi chỉ có UUID (từ sourceUuid) được lưu dưới dạng uuid:<id> trong channels.signal.allowFrom.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom kiểm soát ai có thể kích hoạt trong nhóm khi đặt allowlist.

​

Cách hoạt động (hành vi)

• signal-cli chạy như một daemon; gateway đọc sự kiện qua SSE.
• Tin nhắn vào được chuẩn hóa vào phong bì kênh dùng chung.
• Phản hồi luôn được định tuyến về cùng số hoặc nhóm.

​

Tham chiếu cấu hình (Signal)

• Văn bản gửi đi được chia khối theo channels.signal.textChunkLimit (mặc định 4000).
• Tùy chọn chia theo dòng mới: đặt channels.signal.chunkMode="newline" để tách theo dòng trống (ranh giới đoạn) trước khi chia theo độ dài.
• Hỗ trợ tệp đính kèm (base64 lấy từ signal-cli).
• Giới hạn media mặc định: channels.signal.mediaMaxMb (mặc định 8).
• Dùng channels.signal.ignoreAttachments để bỏ qua tải media.
• Group history context uses channels.signal.historyLimit (or channels.signal.accounts.*.historyLimit), falling back to messages.groupChat.historyLimit. Set 0 to disable (default 50).

​

Đang gõ + biên nhận đã đọc

• channels.signal.enabled: bật/tắt khởi động kênh.
• channels.signal.account: E.164 cho tài khoản bot.
• channels.signal.cliPath: đường dẫn tới signal-cli.

​

Phản ứng (công cụ tin nhắn)

• agents.list[].groupChat.mentionPatterns (Signal không hỗ trợ nhắc tên gốc).
• messages.groupChat.mentionPatterns (dự phòng toàn cục).
• messageId là dấu thời gian Signal của tin nhắn bạn đang phản ứng.
• Phản ứng trong nhóm cần targetAuthor hoặc 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: bật/tắt hành động phản ứng (mặc định true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack tắt phản ứng của tác tử (công cụ tin nhắn react sẽ báo lỗi).
  • minimal/extensive bật phản ứng của tác tử và đặt mức hướng dẫn.
• Per-account overrides: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel`.

​

Đích gửi (CLI/cron)

• DM: signal:+15551234567 (hoặc E.164 trần).
• DM bằng UUID: uuid:<id> (hoặc UUID trần).
• Nhóm: signal:group:<groupId>.
• Tên người dùng: username:<name> (nếu tài khoản Signal của bạn hỗ trợ).

​

Xử lý sự cố

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

openclaw pairing list signal

• Daemon truy cập được nhưng không có phản hồi: kiểm tra cài đặt tài khoản/daemon (httpUrl, account) và chế độ nhận.
• DM bị bỏ qua: người gửi đang chờ duyệt ghép cặp.
• Tin nhắn nhóm bị bỏ qua: chặn do kiểm soát người gửi/nhắc tên trong nhóm.
• Lỗi xác thực cấu hình sau khi chỉnh sửa: chạy openclaw doctor --fix.
• Signal không xuất hiện trong chẩn đoán: xác nhận 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

​

Lưu ý bảo mật

• signal-cli lưu trữ khóa tài khoản cục bộ (thường tại ~/.local/share/signal-cli/data/).
• Sao lưu trạng thái tài khoản Signal trước khi di chuyển hoặc xây dựng lại máy chủ.
• Giữ channels.signal.dmPolicy: "pairing" trừ khi bạn thực sự muốn mở rộng quyền truy cập DM.
• Xác minh SMS chỉ cần cho quy trình đăng ký hoặc khôi phục, nhưng việc mất quyền kiểm soát số/tài khoản có thể làm phức tạp quá trình đăng ký lại.

​

Tham chiếu cấu hình (Signal)

• channels.signal.enabled: bật/tắt khởi động kênh.
• channels.signal.account: E.164 cho tài khoản bot.
• channels.signal.cliPath: đường dẫn tới signal-cli.
• channels.signal.httpUrl: URL daemon đầy đủ (ghi đè host/port).
• channels.signal.httpHost, channels.signal.httpPort: bind daemon (mặc định 127.0.0.1:8080).
• channels.signal.autoStart: tự khởi chạy daemon (mặc định true nếu httpUrl chưa đặt).
• channels.signal.startupTimeoutMs: thời gian chờ khởi động tính bằng ms (giới hạn 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: bỏ qua tải tệp đính kèm.
• channels.signal.ignoreStories: bỏ qua stories từ daemon.
• channels.signal.sendReadReceipts: chuyển tiếp biên nhận đã đọc.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (mặc định: ghép cặp).
• channels.signal.allowFrom: DM allowlist (E.164 or uuid:<id>). open yêu cầu "*". Signal has no usernames; use phone/UUID ids.
• channels.signal.groupPolicy: open | allowlist | disabled (mặc định: danh sách cho phép).
• channels.signal.groupAllowFrom: danh sách cho phép người gửi trong nhóm.
• channels.signal.historyLimit: số tin nhắn nhóm tối đa để đưa vào ngữ cảnh (0 để tắt).
• channels.signal.dmHistoryLimit: giới hạn lịch sử DM theo lượt người dùng. Per-user overrides: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: kích thước chia khối gửi đi (ký tự).
• channels.signal.chunkMode: length (mặc định) hoặc newline để tách theo dòng trống (ranh giới đoạn) trước khi chia theo độ dài.
• channels.signal.mediaMaxMb: giới hạn media vào/ra (MB).

• agents.list[].groupChat.mentionPatterns (Signal không hỗ trợ nhắc tên gốc).
• messages.groupChat.mentionPatterns (dự phòng toàn cục).
• messages.responsePrefix.