Signal

​

Önkoşullar

• Sunucunuzda OpenClaw kurulu (aşağıdaki Linux akışı Ubuntu 24 üzerinde test edildi).
• Şunlardan biri:
  • Ana makinede signal-cli kullanılabilir (yerel mod), veya
  • bbernhard/signal-cli-rest-api Docker container (container modu).
• Bir doğrulama SMS’i alabilen bir telefon numarası (SMS kayıt yolu için).
• Kayıt sırasında Signal captcha (signalcaptchas.org) için tarayıcı erişimi.

​

Hızlı kurulum (başlangıç)

1. Bot için ayrı bir Signal numarası kullanın (önerilir).
2. OpenClaw plugin’ini kurun:

openclaw plugins install @openclaw/signal

3. signal-cli kurun (JVM derlemesini kullanıyorsanız Java gerekir).
4. Bir kurulum yolu seçin:
   • Yol A (QR bağlantısı): signal-cli link -n "OpenClaw" ve Signal ile tarayın.
   • Yol B (SMS kaydı): captcha + SMS doğrulaması ile ayrılmış bir numara kaydedin.
5. OpenClaw’ı yapılandırın ve gateway’i yeniden başlatın.
6. İlk DM’yi gönderin ve eşleştirmeyi onaylayın (openclaw pairing approve signal <CODE>).

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

​

Nedir

• signal-cli üzerinden Signal kanalı (gömülü libsignal değil).
• Deterministik yönlendirme: yanıtlar her zaman Signal’a geri gider.
• DM’ler agent’ın ana oturumunu paylaşır; gruplar yalıtılır (agent:<agentId>:signal:group:<groupId>).

​

Yapılandırma yazımları

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

​

Numara modeli (önemli)

• Gateway bir Signal cihazına (signal-cli hesabı) bağlanır.
• Botu kişisel Signal hesabınızda çalıştırırsanız, kendi mesajlarınızı yok sayar (döngü koruması).
• “Bota mesaj atıyorum ve yanıt veriyor” için ayrı bir bot numarası kullanın.

​

Kurulum yolu A: mevcut Signal hesabını bağlama (QR)

1. signal-cli kurun (JVM veya yerel derleme).
2. Bir bot hesabı bağlayın:
   • signal-cli link -n "OpenClaw" ardından QR’ı Signal içinde tarayın.
3. Signal’ı yapılandırın ve gateway’i başlatın.

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

​

Kurulum yolu B: ayrılmış bot numarası kaydetme (SMS, Linux)

1. SMS alabilen bir numara edinin (veya sabit hatlar için sesli doğrulama).
   • Hesap/oturum çakışmalarını önlemek için ayrılmış bir bot numarası kullanın.
2. Gateway ana makinesine signal-cli kurun:

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. Numarayı kaydedin ve doğrulayın:

signal-cli -a +<BOT_PHONE_NUMBER> register

1. https://signalcaptchas.org/registration/generate.html adresini açın.
2. Captcha’yı tamamlayın, “Open Signal” içinden signalcaptcha://... bağlantı hedefini kopyalayın.
3. Mümkün olduğunda tarayıcı oturumuyla aynı harici IP’den çalıştırın.
4. Kaydı hemen yeniden çalıştırın (captcha token’ları hızlıca sona erer):

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

4. OpenClaw’ı yapılandırın, gateway’i yeniden başlatın, kanalı doğrulayın:

# Gateway'i kullanıcı systemd hizmeti olarak çalıştırıyorsanız:
systemctl --user restart openclaw-gateway.service

# Ardından doğrulayın:
openclaw doctor
openclaw channels status --probe

5. DM göndereninizi eşleştirin:
   • Bot numarasına herhangi bir mesaj gönderin.
   • Sunucuda kodu onaylayın: openclaw pairing approve signal <PAIRING_CODE>.
   • “Bilinmeyen kişi” uyarısını önlemek için bot numarasını telefonunuzda kişi olarak kaydedin.

• signal-cli README: https://github.com/AsamK/signal-cli
• Captcha akışı: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
• Bağlama akışı: https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)

​

Harici daemon modu (httpUrl)

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

​

Container modu (bbernhard/signal-cli-rest-api)

• Gerçek zamanlı mesaj almak için container mutlaka MODE=json-rpc ile çalışmalıdır.
• OpenClaw’a bağlanmadan önce Signal hesabınızı container içinde kaydedin veya bağlayın.

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", // veya otomatik algılama için "auto"
    },
  },
}

• Container moduyla autoStart: false kullanın. apiMode: "container" seçildiğinde OpenClaw yerel bir daemon başlatmamalıdır.
• Alım için MODE=json-rpc kullanın. MODE=normal, /v1/about için sağlıklı görünebilir, ancak /v1/receive/{account} WebSocket’e yükselmez; bu yüzden OpenClaw auto modunda container alım akışını seçmez.
• httpUrl değerinin bbernhard’ın REST API’sine işaret ettiğini biliyorsanız apiMode: "container" ayarlayın. Yerel signal-cli JSON-RPC/SSE’ye işaret ettiğini biliyorsanız apiMode: "native" ayarlayın. Dağıtım değişebiliyorsa "auto" kullanın.
• Container ek indirmeleri, yerel modla aynı medya bayt sınırlarına uyar. Sunucu Content-Length gönderdiğinde aşırı büyük yanıtlar tam olarak arabelleğe alınmadan önce, aksi halde akış sırasında reddedilir.

​

Erişim denetimi (DM’ler + gruplar)

• Varsayılan: channels.signal.dmPolicy = "pairing".
• Bilinmeyen gönderenler bir eşleştirme kodu alır; mesajlar onaylanana kadar yok sayılır (kodlar 1 saat sonra sona erer).
• Şununla onaylayın:
  • openclaw pairing list signal
  • openclaw pairing approve signal <CODE>
• Eşleştirme, Signal DM’leri için varsayılan token değişimidir. Ayrıntılar: Eşleştirme
• Yalnızca UUID gönderenler (sourceUuid üzerinden), channels.signal.allowFrom içinde uuid:<id> olarak saklanır.

• channels.signal.groupPolicy = open | allowlist | disabled.
• channels.signal.groupAllowFrom, allowlist ayarlandığında hangi grupların veya gönderenlerin grup yanıtlarını tetikleyebileceğini denetler; girdiler Signal grup kimlikleri (ham, group:<id> veya signal:group:<id>), gönderen telefon numaraları, uuid:<id> değerleri veya * olabilir.
• channels.signal.groups["<group-id>" | "*"], requireMention, tools ve toolsBySender ile grup davranışını geçersiz kılabilir.
• Çoklu hesap kurulumlarında hesap başına geçersiz kılmalar için channels.signal.accounts.<id>.groups kullanın.
• Bir Signal grubunu groupAllowFrom üzerinden izin listesine almak, kendi başına bahsetme geçidini devre dışı bırakmaz. Özellikle yapılandırılmış bir channels.signal.groups["<group-id>"] girdisi, requireMention=true ayarlanmadıkça her grup mesajını işler.
• Çalışma zamanı notu: channels.signal tamamen eksikse, çalışma zamanı grup denetimleri için groupPolicy="allowlist" değerine geri döner (channels.defaults.groupPolicy ayarlı olsa bile).

​

Nasıl çalışır (davranış)

• Yerel mod: signal-cli daemon olarak çalışır; gateway olayları SSE üzerinden okur.
• Container modu: gateway REST API üzerinden gönderir ve WebSocket üzerinden alır.
• Gelen mesajlar paylaşılan kanal zarfına normalize edilir.
• Yanıtlar her zaman aynı numaraya veya gruba geri yönlendirilir.

​

Medya + sınırlar

• Giden metin channels.signal.textChunkLimit değerine göre parçalara ayrılır (varsayılan 4000).
• İsteğe bağlı yeni satır parçalama: uzunluğa göre parçalamadan önce boş satırlardan (paragraf sınırları) bölmek için channels.signal.chunkMode="newline" ayarlayın.
• Ekler desteklenir (signal-cli üzerinden base64 olarak alınır).
• Sesli not ekleri, contentType eksik olduğunda MIME yedeği olarak signal-cli dosya adını kullanır; böylece ses transkripsiyonu AAC sesli notlarını yine de sınıflandırabilir.
• Varsayılan medya sınırı: channels.signal.mediaMaxMb (varsayılan 8).
• Medya indirmeyi atlamak için channels.signal.ignoreAttachments kullanın.
• Grup geçmişi bağlamı channels.signal.historyLimit (veya channels.signal.accounts.*.historyLimit) kullanır, yoksa messages.groupChat.historyLimit değerine geri döner. Devre dışı bırakmak için 0 ayarlayın (varsayılan 50).

​

Yazıyor + okundu alındıları

• Yazma göstergeleri: OpenClaw, signal-cli sendTyping aracılığıyla yazma sinyalleri gönderir ve bir yanıt çalışırken bunları yeniler.
• Okundu bilgileri: channels.signal.sendReadReceipts true olduğunda OpenClaw, izin verilen DM’ler için okundu bilgilerini iletir.
• signal-cli, gruplar için okundu bilgilerini sunmaz.

​

Yaşam döngüsü durumu tepkileri

​

Tepkiler (ileti aracı)

• channel=signal ile message action=react kullanın.
• Hedefler: gönderen E.164 veya UUID (eşleştirme çıktısından uuid:<id> kullanın; yalın UUID de çalışır).
• messageId, tepki verdiğiniz iletinin Signal zaman damgasıdır.
• Grup tepkileri targetAuthor veya targetAuthorUuid gerektirir.

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: tepki eylemlerini etkinleştir/devre dışı bırak (varsayılan true).
• channels.signal.reactionLevel: off | ack | minimal | extensive.
  • off/ack, ajan tepkilerini devre dışı bırakır (ileti aracı react hata verir).
  • minimal/extensive, ajan tepkilerini etkinleştirir ve yönlendirme düzeyini ayarlar.
• Hesap bazlı geçersiz kılmalar: channels.signal.accounts.<id>.actions.reactions, channels.signal.accounts.<id>.reactionLevel.

​

Onay tepkileri

• 👍 bir kez onaylar.
• 👎 reddeder.
• Bir istek kalıcı onay sunduğunda /approve <id> allow-always kullanın.

​

Teslim hedefleri (CLI/cron)

• DM’ler: signal:+15551234567 (veya düz E.164).
• UUID DM’leri: uuid:<id> (veya yalın UUID).
• Gruplar: signal:group:<groupId>.
• Kullanıcı adları: username:<name> (Signal hesabınız destekliyorsa).

​

Takma adlar

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

​

Sorun giderme

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

openclaw pairing list signal

• Daemon erişilebilir ama yanıt yok: hesap/daemon ayarlarını (httpUrl, account) ve alma modunu doğrulayın.
• DM’ler yok sayılıyor: gönderen eşleştirme onayı bekliyor.
• Grup iletileri yok sayılıyor: grup göndereninden/mention geçitleri teslimi engelliyor.
• Düzenlemelerden sonra yapılandırma doğrulama hataları: openclaw doctor --fix çalıştırın.
• Signal tanılarda eksik: channels.signal.enabled: true olduğunu doğrulayın.

openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20

​

Güvenlik notları

• signal-cli, hesap anahtarlarını yerel olarak saklar (genellikle ~/.local/share/signal-cli/data/).
• Sunucu geçişi veya yeniden oluşturma öncesinde Signal hesap durumunu yedekleyin.
• Daha geniş DM erişimini açıkça istemediğiniz sürece channels.signal.dmPolicy: "pairing" olarak tutun.
• SMS doğrulaması yalnızca kayıt veya kurtarma akışları için gereklidir, ancak numaranın/hesabın denetimini kaybetmek yeniden kaydı zorlaştırabilir.

​

Yapılandırma başvurusu (Signal)

• channels.signal.enabled: kanal başlangıcını etkinleştir/devre dışı bırak.
• channels.signal.apiMode: auto | native | container (varsayılan: auto). Bkz. Container modu.
• channels.signal.account: bot hesabı için E.164.
• channels.signal.cliPath: signal-cli yolu.
• channels.signal.configPath: isteğe bağlı signal-cli --config dizini.
• channels.signal.httpUrl: tam daemon URL’si (host/port değerlerini geçersiz kılar).
• channels.signal.httpHost, channels.signal.httpPort: daemon bağlaması (varsayılan 127.0.0.1:8080).
• channels.signal.autoStart: daemon’ı otomatik başlat (varsayılan true, httpUrl ayarlanmamışsa).
• channels.signal.startupTimeoutMs: ms cinsinden başlangıç bekleme zaman aşımı (üst sınır 120000).
• channels.signal.receiveMode: on-start | manual.
• channels.signal.ignoreAttachments: ek indirmelerini atla.
• channels.signal.ignoreStories: daemon’dan gelen story’leri yok say.
• channels.signal.sendReadReceipts: okundu bilgilerini ilet.
• channels.signal.dmPolicy: pairing | allowlist | open | disabled (varsayılan: pairing).
• channels.signal.allowFrom: DM izin listesi (E.164 veya uuid:<id>). open, "*" gerektirir. Signal’de kullanıcı adları yoktur; telefon/UUID kimlikleri kullanın.
• channels.signal.aliases: DM veya grup teslim hedefleri için OpenClaw tarafı takma adlar.
• channels.signal.groupPolicy: open | allowlist | disabled (varsayılan: allowlist).
• channels.signal.groupAllowFrom: grup izin listesi; Signal grup kimliklerini (ham, group:<id> veya signal:group:<id>), gönderen E.164 numaralarını veya uuid:<id> değerlerini kabul eder.
• channels.signal.groups: Signal grup kimliğine (veya "*") göre anahtarlanmış grup bazlı geçersiz kılmalar. Desteklenen alanlar: requireMention, tools, toolsBySender.
• channels.signal.accounts.<id>.groups: çok hesaplı kurulumlar için channels.signal.groups değerinin hesap bazlı sürümü.
• channels.signal.accounts.<id>.aliases: üst düzey takma adlarla birleştirilen hesap bazlı takma adlar.
• channels.signal.historyLimit: bağlam olarak eklenecek en fazla grup iletisi (0 devre dışı bırakır).
• channels.signal.dmHistoryLimit: kullanıcı turları cinsinden DM geçmiş sınırı. Kullanıcı bazlı geçersiz kılmalar: channels.signal.dms["<phone_or_uuid>"].historyLimit.
• channels.signal.textChunkLimit: giden parça boyutu (karakter).
• channels.signal.chunkMode: uzunluğa göre parçalamadan önce boş satırlarda (paragraf sınırları) bölmek için length (varsayılan) veya newline.
• channels.signal.mediaMaxMb: gelen/giden medya üst sınırı (MB).

• agents.list[].groupChat.mentionPatterns (Signal yerel mention’ları desteklemez).
• messages.groupChat.mentionPatterns (genel yedek).
• messages.responsePrefix.

​

İlgili

• Kanallara Genel Bakış — desteklenen tüm kanallar
• Eşleştirme — DM kimlik doğrulaması ve eşleştirme akışı
• Gruplar — grup sohbeti davranışı ve mention geçidi
• Kanal Yönlendirme — iletiler için oturum yönlendirmesi
• Güvenlik — erişim modeli ve sağlamlaştırma