Signal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Điều kiện tiên quyết

• OpenClaw đã được cài đặt trên máy chủ của bạn (luồng Linux bên dưới đã được kiểm thử trên Ubuntu 24).
• Một trong các lựa chọn:
  • signal-cli có sẵn trên máy chủ (chế độ native), hoặc
  • container Docker bbernhard/signal-cli-rest-api (chế độ container).
• Một số điện thoại có thể nhận một tin nhắn SMS xác minh (cho đường dẫn đăng ký bằng SMS).
• Quyền truy cập trình duyệt cho captcha Signal (signalcaptchas.org) trong quá trình đăng ký.

​

Thiết lập nhanh (người mới bắt đầu)

1. Dùng một số Signal riêng cho bot (khuyến nghị).
2. Cài đặt signal-cli (cần Java nếu bạn dùng bản dựng JVM).
3. Chọn một đường dẫn thiết lập:
   • Đường dẫn A (liên kết QR): signal-cli link -n "OpenClaw" và quét bằng Signal.
   • Đường dẫn B (đăng ký SMS): đăng ký một số riêng bằng 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à phê duyệt ghép nối (openclaw pairing approve signal <CODE>).

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

​

Đây là gì

• Kênh Signal thông qua signal-cli (không nhúng libsignal).
• Đị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 agent; nhóm được cô lập (agent:<agentId>:signal:group:<groupId>).

​

Ghi cấu hình

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

​

Mô hình số điện thoại (quan trọng)

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

​

Đường dẫn thiết lập A: liên kết tài khoản Signal hiện có (QR)

1. Cài đặt signal-cli (bản dựng JVM hoặc 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"],
    },
  },
}

​

Đường dẫn thiết lập B: đăng ký số bot riêng (SMS, Linux)

1. Lấy một số có thể nhận SMS (hoặc xác minh bằng cuộc gọi cho điện thoại cố định).
   • Dùng một số bot riêng để tránh xung đột tài khoản/phiên.
2. Cài đặt signal-cli trên máy chủ Gateway:

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ố:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. Mở https://signalcaptchas.org/registration/generate.html.
2. Hoàn tất captcha, sao chép đích liên kết signalcaptcha://... từ “Open Signal”.
3. Chạy từ cùng IP bên ngoài với phiên trình duyệt khi có thể.
4. Chạy lại đăng ký ngay lập tức (token captcha hết hạn nhanh):

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

4. Cấu hình OpenClaw, khởi động lại Gateway, xác minh kênh:

# 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. Ghép nối người gửi DM của bạn:
   • Gửi bất kỳ tin nhắn nào tới số bot.
   • Phê duyệt mã trên máy chủ: openclaw pairing approve signal <PAIRING_CODE>.
   • Lưu số bot làm liên hệ trên điện thoại để tránh “Unknown contact”.

• README của signal-cli: 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,
    },
  },
}

​

Chế độ container (bbernhard/signal-cli-rest-api)

• Container phải chạy với MODE=json-rpc để nhận tin nhắn theo thời gian thực.
• Đăng ký hoặc liên kết tài khoản Signal của bạn bên trong container trước khi kết nối OpenClaw.

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
    },
  },
}

• Dùng autoStart: false với chế độ container. OpenClaw không nên spawn daemon native khi chọn apiMode: "container".
• Dùng MODE=json-rpc để nhận. MODE=normal có thể làm /v1/about trông khỏe mạnh, nhưng /v1/receive/{account} không nâng cấp lên WebSocket, nên OpenClaw sẽ không chọn streaming nhận qua container trong chế độ auto.
• Đặt apiMode: "container" khi bạn biết httpUrl trỏ tới API REST của bbernhard. Đặt apiMode: "native" khi bạn biết nó trỏ tới JSON-RPC/SSE của signal-cli native. Dùng "auto" khi cách triển khai có thể thay đổi.
• Tải xuống tệp đính kèm trong chế độ container tuân thủ cùng giới hạn byte media như chế độ native. Phản hồi quá cỡ bị từ chối trước khi được buffer đầy đủ khi máy chủ gửi Content-Length, và bị từ chối trong khi streaming trong các trường hợp khác.

​

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

• Mặc định: channels.signal.dmPolicy = "pairing".
• Người gửi không xác định nhận một mã ghép nối; tin nhắn bị bỏ qua cho đến khi được phê duyệt (mã hết hạn sau 1 giờ).
• Phê duyệt qua:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Ghép nối là trao đổi token mặc định cho DM Signal. Chi tiết: Ghép nối
• 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 nhóm hoặc người gửi nào có thể kích hoạt phản hồi nhóm khi đặt allowlist; mục nhập có thể là ID nhóm Signal (thô, group:<id>, hoặc signal:group:<id>), số điện thoại người gửi, giá trị uuid:<id>, hoặc *.
• channels.signal.groups["<group-id>" | "*"] có thể ghi đè hành vi nhóm bằng requireMention, tools, và toolsBySender.
• Dùng channels.signal.accounts.<id>.groups cho ghi đè theo từng tài khoản trong thiết lập nhiều tài khoản.
• Việc đưa một nhóm Signal vào danh sách cho phép thông qua groupAllowFrom tự nó không tắt cổng yêu cầu nhắc tên. Một mục channels.signal.groups["<group-id>"] được cấu hình cụ thể sẽ xử lý mọi tin nhắn nhóm trừ khi đặt requireMention=true.
• Ghi chú runtime: nếu channels.signal hoàn toàn thiếu, runtime sẽ quay về groupPolicy="allowlist" cho kiểm tra nhóm (ngay cả khi channels.defaults.groupPolicy được đặt).

​

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

• Chế độ native: signal-cli chạy như một daemon; Gateway đọc sự kiện qua SSE.
• Chế độ container: Gateway gửi qua API REST và nhận qua WebSocket.
• Tin nhắn đến được chuẩn hóa vào envelope kênh dùng chung.
• Phản hồi luôn định tuyến trở lại cùng số hoặc nhóm.

​

Media + giới hạn

• Văn bản gửi đi được chia đoạn theo channels.signal.textChunkLimit (mặc định 4000).
• Chia đoạn theo dòng mới tùy chọn: đặt channels.signal.chunkMode="newline" để chia tại các dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
• Hỗ trợ tệp đính kèm (base64 được lấy từ signal-cli).
• Tệp đính kèm ghi chú thoại dùng tên tệp của signal-cli làm MIME dự phòng khi thiếu contentType, để phiên âm âm thanh vẫn có thể phân loại bản ghi nhớ giọng nói AAC.
• Giới hạn media mặc định: channels.signal.mediaMaxMb (mặc định 8).
• Dùng channels.signal.ignoreAttachments để bỏ qua việc tải xuống media.
• Ngữ cảnh lịch sử nhóm dùng channels.signal.historyLimit (hoặc channels.signal.accounts.*.historyLimit), rồi quay về messages.groupChat.historyLimit. Đặt 0 để tắt (mặc định 50).

​

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

• Chỉ báo đang nhập: OpenClaw gửi tín hiệu đang nhập qua signal-cli sendTyping và làm mới chúng trong khi phản hồi đang chạy.
• Biên nhận đã đọc: khi channels.signal.sendReadReceipts là true, OpenClaw chuyển tiếp biên nhận đã đọc cho các DM được phép.
• Signal-cli không cung cấp biên nhận đã đọc cho nhóm.

​

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

• Sử dụng message action=react với channel=signal.
• Mục tiêu: E.164 của người gửi hoặc UUID (dùng uuid:<id> từ đầu ra ghép cặp; UUID trần cũng dùng được).
• messageId là dấu thời gian Signal của tin nhắn mà bạn đang phản ứng.
• Phản ứng trong nhóm yêu cầu 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 các 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 nhân (công cụ tin nhắn react sẽ báo lỗi).
  • minimal/extensive bật phản ứng của tác nhân và đặt mức hướng dẫn.
• Ghi đè theo từng tài khoản: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Mục tiêu gửi (CLI/cron)

• Tin nhắn trực tiếp: signal:+15551234567 (hoặc E.164 thuần).
• Tin nhắn trực tiếp 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ợ).

​

Khắc phục 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: xác minh thiết lập tài khoản/daemon (httpUrl, account) và chế độ nhận.
• Tin nhắn trực tiếp bị bỏ qua: người gửi đang chờ phê duyệt ghép cặp.
• Tin nhắn nhóm bị bỏ qua: cổng kiểm soát theo người gửi/nhắc đến trong nhóm chặn việc gửi.
• Lỗi xác thực cấu hình sau khi chỉnh sửa: chạy openclaw doctor --fix.
• Signal thiếu 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

​

Ghi chú bảo mật

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

​

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

• channels.signal.enabled: bật/tắt khởi động kênh.
• channels.signal.apiMode: auto | native | container (mặc định: auto). Xem Chế độ container.
• channels.signal.account: E.164 cho tài khoản bot.
• channels.signal.cliPath: đường dẫn đến signal-cli.
• channels.signal.httpUrl: URL daemon đầy đủ (ghi đè host/port).
• channels.signal.httpHost, channels.signal.httpPort: liên kết daemon (mặc định 127.0.0.1:8080).
• channels.signal.autoStart: tự động sinh daemon (mặc định true nếu chưa đặt httpUrl).
• 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 xuống tệp đính kèm.
• channels.signal.ignoreStories: bỏ qua tin từ daemon.
• channels.signal.sendReadReceipts: chuyển tiếp biên nhận đã đọc.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing).
• channels.signal.allowFrom: danh sách cho phép tin nhắn trực tiếp (E.164 hoặc uuid:<id>). open yêu cầu "*". Signal không có tên người dùng; dùng ID điện thoại/UUID.
• channels.signal.groupPolicy: open | allowlist | disabled (mặc định: allowlist).
• channels.signal.groupAllowFrom: danh sách cho phép nhóm; chấp nhận ID nhóm Signal (thô, group:<id>, hoặc signal:group:<id>), số E.164 của người gửi, hoặc giá trị uuid:<id>.
• channels.signal.groups: ghi đè theo từng nhóm, khóa theo ID nhóm Signal (hoặc "*"). Trường được hỗ trợ: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: phiên bản theo từng tài khoản của channels.signal.groups cho thiết lập nhiều tài khoản.
• channels.signal.historyLimit: số tin nhắn nhóm tối đa đưa vào làm ngữ cảnh (0 tắt).
• channels.signal.dmHistoryLimit: giới hạn lịch sử tin nhắn trực tiếp theo lượt người dùng. Ghi đè theo từng người dùng: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: kích thước đoạn 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 văn) trước khi chia đoạn theo độ dài.
• channels.signal.mediaMaxMb: giới hạn phương tiện gửi đến/gửi đi (MB).

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

​

Liên quan

• Tổng quan kênh — tất cả kênh được hỗ trợ
• Ghép cặp — xác thực tin nhắn trực tiếp và luồng ghép cặp
• Nhóm — hành vi trò chuyện nhóm và cổng kiểm soát nhắc đến
• Định tuyến kênh — định tuyến phiên cho tin nhắn
• Bảo mật — mô hình truy cập và gia cố