Signal 채널 구성: signal-cli로 개인 AI 어시스턴트 연결 | Clawdbot 튜토리얼

이 과정을 완료하면 할 수 있는 것

이 과정을 마치면 다음을 수행할 수 있습니다:

✅ signal-cli 설치 및 구성
✅ Clawdbot에서 Signal 채널 설정
✅ 개인 메시지 및 그룹을 통해 AI 어시스턴트와 상호작용
✅ DM 페어링 메커니즘으로 계정 보호
✅ 다중 Signal 계정 구성
✅ Signal의 입력 중 표시기, 읽음 확인, 리액션 활용

현재 직면한 문제

Signal로 AI 어시스턴트를 사용하고 싶지만 몇 가지 문제에 직면했습니다:

❌ Signal과 Clawdbot의 연결 방법을 모릅니다
❌ 개인정보 보호에 우려가 있어 데이터를 클라우드에 업로드하고 싶지 않습니다
❌ AI 어시스턴트에 메시지를 보낼 수 있는 사용자를 제어하는 방법이 불확실합니다
❌ 여러 Signal 계정 간에 전환해야 합니다

왜 Signal인가요?

Signal은 종단 간 암호화된 메시징 애플리케이션으로, 모든 통신이 암호화되어 발신자와 수신자만 메시지를 읽을 수 있습니다. Clawdbot은 signal-cli를 통해 통합하여 프라이버시를 유지하면서 AI 어시스턴트 기능을 활용할 수 있습니다.

Signal 채널 사용 시기

Signal 채널 사용에 적합한 시나리오:

프라이버시 우선 통신 채널이 필요한 경우
팀 또는 친구 그룹이 Signal을 사용하는 경우
개인 장치에서 AI 어시스턴트를 실행해야 하는 경우
보호된 DM 페어링 메커니즘을 통해 액세스를 제어해야 하는 경우

별도의 Signal 계정

개인 번호 대신 별도의 Signal 번호를 bot 계정으로 사용하는 것이 좋습니다. 이렇게 하면 메시지 루프(bot가 자신의 메시지를 무시)를 방지하고 업무와 개인 통신을 분리할 수 있습니다.

시작 전 준비

시작하기 전에 다음 단계를 완료했는지 확인하세요:

사전 요구사항

✅ 빠르게 시작하기 튜토리얼 완료
✅ Clawdbot이 설치되고 정상적으로 실행 가능
✅ 하나 이상의 AI 모델 제공자 구성(Anthropic, OpenAI, OpenRouter 등)
✅ Java 설치(signal-cli 필요)

핵심 개념

Clawdbot의 Signal 통합은 signal-cli를 기반으로 하며 다음과 같은 방식으로 작동합니다:

데몬 모드: signal-cli가 백그라운드 데몬으로 실행되어 HTTP JSON-RPC 인터페이스를 제공합니다
이벤트 스트림(SSE): Clawdbot은 Server-Sent Events(SSE)를 통해 Signal 이벤트를 수신합니다
표준화된 메시지: Signal 메시지는 통합된 내부 형식으로 변환된 후 AI Agent로 라우팅됩니다
결정적 라우팅: 모든 응답은 원본 메시지의 발신자 또는 그룹으로 다시 전송됩니다

핵심 설계 원칙:

로컬 우선: signal-cli가 장치에서 실행되며 모든 통신이 암호화됩니다
다중 계정 지원: 여러 Signal 계정을 구성할 수 있습니다
액세스 제어: 기본적으로 DM 페어링 메커니즘이 활성화되어 있으므로 승인 없이는 알 수 없는 사용자가 메시지를 보낼 수 없습니다
컨텍스트 격리: 그룹 메시지는 독립적인 세션 컨텍스트를 가지며 DM과 혼합되지 않습니다

따라하기

1단계: signal-cli 설치

이유 signal-cli는 Signal의 명령행 인터페이스로, Clawdbot은 이를 통해 Signal 네트워크와 통신합니다.

설치 방법

macOS (Homebrew)Linux (Ubuntu/Debian)Windows (WSL2)

bash

brew install signal-cli

bash

# https://github.com/AsamK/signal-cli/releases 에서 최신 버전 확인
# 최신 signal-cli 릴리스 패키지 다운로드(VERSION을 실제 버전 번호로 교체)
wget https://github.com/AsamK/signal-cli/releases/download/vVERSION/signal-cli-VERSION.tar.gz

# /opt 디렉토리에 압축 해제
sudo tar -xvf signal-cli-VERSION.tar.gz -C /opt/

# 심볼릭 링크 생성(선택 사항)
sudo ln -s /opt/signal-cli-VERSION/bin/signal-cli /usr/local/bin/signal-cli

bash

# WSL2에서 Linux 설치 방법 사용
# 참고: Windows는 WSL2를 사용하므로 signal-cli 설치는 Linux 절차를 따릅니다

설치 확인

bash

signal-cli --version
# 다음을 확인해야 합니다: signal-cli 버전 번호(예: 0.13.x 이상)

확인해야 할 내용: signal-cli 버전 번호가 출력됩니다.

Java 요구사항

signal-cli는 Java 런타임(일반적으로 Java 11 이상)이 필요합니다. Java가 설치되고 구성되었는지 확인하세요:

bash

java -version
# 다음을 확인해야 합니다: openjdk version "11.x.x" 이상

참고: 자세한 Java 버전 요구사항은 signal-cli 공식 문서를 참조하세요.

2단계: Signal 계정 연결

이유 계정을 연결해야 signal-cli가 Signal 번호를 대신하여 메시지를 보내고 받을 수 있습니다.

권장 사항: 별도의 Signal 번호를 bot 계정으로 사용하세요.

연결 단계

연결 명령 생성:

bash

signal-cli link -n "Clawdbot"

-n "Clawdbot"은 장치 이름을 "Clawdbot"으로 지정합니다(사용자 정의 가능).

QR 코드 스캔:

명령을 실행하면 터미널에 QR 코드가 표시됩니다:

tsconfig: 2369:35 - warning - *! is deprecated: Use .nonNull().
  (deprecated-non-null)

To link your device, navigate to
  Signal Settings > Linked Devices > (+) Link New Device
  on your phone and scan the QR code displayed below.

██████████████████████████████████████████████
██████████████████████████████████████████████
██████████████████████████████████████████████
██████████████████████████████████████████████
██████████████████████████████████████████████
...

Signal 모바일 앱에서:
- Signal 설정 열기
- "연결된 장치"(Linked Devices) 선택
- "(+) 새 장치 연결"(Link New Device) 클릭
- 터미널에 표시된 QR 코드 스캔

확인해야 할 내용: 연결에 성공하면 터미널에 다음과 같은 출력이 표시됩니다:

INFO  Account restored (Number: +15551234567)
INFO  Configuration created at: ~/.local/share/signal-cli/data

다중 장치 지원

Signal은 최대 4개의 장치를 연결할 수 있습니다. Clawdbot은 이 중 하나의 장치로 실행됩니다. Signal 모바일 앱의 "연결된 장치"에서 이러한 장치를 보고 관리할 수 있습니다.

3단계: Clawdbot의 Signal 채널 구성

이유 구성 파일은 Clawdbot에 signal-cli에 연결하는 방법과 Signal에서 오는 메시지를 처리하는 방법을 알려줍니다.

구성 방법

세 가지 구성 방법이 있으며 가장 적합한 방법을 선택하세요:

방법 1: 빠른 구성(단일 계정)

가장 간단한 방법으로 단일 계정 시나리오에 적합합니다.

~/.clawdbot/clawdbot.json 편집:

json

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

구성 설명:

필드	값	설명
`enabled`	`true`	Signal 채널 활성화
`account`	`"+15551234567"`	Signal 계정(E.164 형식)
`cliPath`	`"signal-cli"`	signal-cli 명령 경로
`dmPolicy`	`"pairing"`	DM 액세스 정책(기본값: 페어링 모드)
`allowFrom`	`["+15557654321"]`	DM 전송 허용 번호 허용 목록

방법 2: 다중 계정 구성

여러 Signal 계정을 관리해야 하는 경우 accounts 개체를 사용하세요:

json

{
  "channels": {
    "signal": {
      "enabled": true,
      "accounts": {
        "work": {
          "account": "+15551234567",
          "name": "Work Bot",
          "httpPort": 8080,
          "dmPolicy": "pairing",
          "allowFrom": ["+15557654321"]
        },
        "personal": {
          "account": "+15559876543",
          "name": "Personal Bot",
          "httpPort": 8081,
          "dmPolicy": "allowlist",
          "allowFrom": ["*"]
        }
      }
    }
  }
}

구성 설명:

각 계정에는 고유한 ID가 있습니다(예: work, personal)
각 계정은 다른 포트, 정책 및 권한을 가질 수 있습니다
name은 CLI/UI 목록에 사용되는 선택 사항인 표시 이름입니다

방법 3: 외부 데몬 모드

signal-cli를 직접 관리하려는 경우(예: 컨테이너 내에서 또는 CPU 공유) 자동 시작을 비활성화하세요:

json

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

구성 설명:

httpUrl: 전체 데몬 URL(httpHost 및 httpPort 재정의)
autoStart: false로 설정하여 signal-cli 자동 시작 비활성화
Clawdbot은 이미 실행 중인 signal-cli 데몬에 연결합니다

확인해야 할 내용: 구성 파일을 저장한 후 구문 오류가 없습니다.

구성 검증

Clawdbot은 시작할 때 구성을 검증합니다. 구성에 오류가 있으면 로그에 자세한 오류 메시지가 표시됩니다.

4단계: Gateway 시작

이유 Gateway를 시작하면 Clawdbot은 자동으로 signal-cli 데몬을 시작합니다(autoStart를 비활성화하지 않은 경우)하고 Signal 메시지 수신을 시작합니다.

시작 명령

bash

clawdbot gateway start

확인해야 할 내용: 다음과 같은 출력:

[INFO] Starting Clawdbot Gateway...
[INFO] Starting signal-cli daemon...
[INFO] signal-cli: INFO  Starting daemon...
[INFO] signal-cli: INFO  Daemon started on http://127.0.0.1:8080
[INFO] Signal channel ready (account: +15551234567)
[INFO] Gateway listening on ws://127.0.0.1:18789
[INFO] Clawdbot Gateway started successfully

Channel 상태 확인

bash

clawdbot channels status

확인해야 할 내용: 다음과 같은 출력:

Signal Channels:
  ├─ +15551234567 (Work Bot)
  │   ├─ Status: Connected
  │   ├─ Daemon: http://127.0.0.1:8080
  │   └─ Mode: Auto-start

5단계: 첫 번째 메시지 전송

이유 구성이 올바른지 확인하고 Clawdbot이 Signal 메시지를 수신하고 처리할 수 있는지 확인합니다.

메시지 전송

Signal 모바일 앱에서 bot 번호로 메시지 전송:

안녕하세요, Clawdbot!

첫 번째 메시지 처리:

dmPolicy="pairing"(기본값)인 경우 알 수 없는 사용자에게 페어링 코드가 전송됩니다:

❌ 권한 없는 발신자

계속하려면 다음 코드로 이 페어링을 승인하세요:

📝 페어링 코드: ABC123

코드는 1시간 후에 만료됩니다.

승인하려면 다음을 실행하세요:
clawdbot pairing approve signal ABC123

페어링 승인:

bash

clawdbot pairing list signal

승인 대기 중인 페어링 요청 나열:

Pending Pairings (Signal):
  ├─ ABC123
  │   ├─ Sender: +15557654321
  │   ├─ UUID: uuid:123e4567-e89b-12d3-a456-426614174000
  │   └─ Expires: 2026-01-27 12:00:00

페어링 승인:

bash

clawdbot pairing approve signal ABC123

두 번째 메시지 전송:
페어링에 성공하면 다시 메시지 전송:
```
안녕하세요, Clawdbot!
```

확인해야 할 내용:

Signal 모바일 앱에서 AI 응답 수신:

안녕하세요! Clawdbot입니다. 귀하의 개인 AI 어시스턴트입니다. 어떻게 도와드릴까요?

Gateway 로그에 표시됨:

[INFO] Received Signal message from +15557654321
[INFO] Processing message through Agent...
[INFO] Sending Signal response to +15557654321

체크포인트 ✅:

[ ] signal-cli 데몬 실행 중
[ ] Channel 상태에 "Connected" 표시
[ ] 메시지 전송 후 AI 응답 수신
[ ] Gateway 로그에 오류 메시지 없음

자신의 메시지는 무시됩니다

개인 Signal 번호에서 bot을 실행하는 경우 bot은 사용자가 보낸 메시지를 무시합니다(루프 보호). 별도의 bot 번호를 사용하는 것이 좋습니다.

문제 해결 팁

문제 1: signal-cli 시작 실패

문제: signal-cli 데몬을 시작할 수 없습니다

가능한 원인:

Java가 설치되지 않았거나 버전이 너무 낮음
포트가 이미 사용 중
signal-cli 경로가 올바르지 않음

해결 방법:

bash

# Java 버전 확인
java -version

# 포트 사용 확인
lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows (PowerShell)

# signal-cli 경로 확인
which signal-cli

문제 2: 페어링 코드 만료

문제: 페어링 코드가 1시간 후에 만료됩니다

해결 방법:

메시지를 다시 전송하여 새 페어링 코드를 받고 1시간 내에 승인하세요.

문제 3: 그룹 메시지 응답 없음

문제: Signal 그룹에서 @ 멘션으로 bot을 언급했으나 응답이 없습니다

가능한 원인:

groupPolicy가 allowlist로 설정되어 있지만 groupAllowFrom에 없습니다
Signal은 Discord/Slack과 달리 기본 @ 멘션을 지원하지 않습니다

해결 방법:

그룹 정책 구성:

json

{
  "channels": {
    "signal": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15557654321"]
    }
  }
}

또는 명령 트리거 사용(commands.config: true가 구성된 경우):

@clawdbot help

문제 4: 미디어 파일 다운로드 실패

문제: Signal 메시지의 이미지나 첨부 파일을 처리할 수 없습니다

가능한 원인:

파일 크기가 mediaMaxMb 제한을 초과함(기본값 8MB)
ignoreAttachments가 true로 설정됨

해결 방법:

json

{
  "channels": {
    "signal": {
      "mediaMaxMb": 20,
      "ignoreAttachments": false
    }
  }
}

문제 5: 긴 메시지 잘림 현상

문제: 전송된 메시지가 여러 부분으로 분할됩니다

원인: Signal에는 메시지 길이 제한이 있습니다(기본값 4000자). Clawdbot은 자동으로 청킹을 수행합니다

해결 방법:

청킹 구성 조정:

json

{
  "channels": {
    "signal": {
      "textChunkLimit": 2000,
      "chunkMode": "newline"
    }
  }
}

chunkMode 옵션:

length(기본값): 길이별 청킹
newline: 빈 줄로 먼저 분할(단락 경계)한 다음 길이별로 청킹

이 과정 요약

이 과정에서는 Signal 채널 구성 및 사용을 완료했습니다:

핵심 개념:

Signal 채널은 signal-cli를 기반으로 하며 HTTP JSON-RPC + SSE를 통해 통신합니다
메시지 루프를 방지하기 위해 별도의 bot 번호를 사용하는 것이 좋습니다
기본적으로 DM 페어링 메커니즘이 활성화되어 계정 보안을 보호합니다

핵심 구성:

account: Signal 계정(E.164 형식)
cliPath: signal-cli 경로
dmPolicy: DM 액세스 정책(기본값 pairing)
allowFrom: DM 허용 목록
groupPolicy / groupAllowFrom: 그룹 정책

실용 기능:

다중 계정 지원
그룹 메시지(독립 컨텍스트)
입력 중 표시기
읽음 확인
Reactions(이모지 반응)

문제 해결:

clawdbot channels status로 Channel 상태 확인
clawdbot pairing list signal로 승인 대기 중인 페어링 요청 확인
Gateway 로그에서 자세한 오류 정보 확인

다음 과정 미리보기

다음 과정에서는 **iMessage 채널**을 학습합니다.
다음 내용을 배우게 됩니다:
macOS에서 iMessage 채널 구성 방법
BlueBubbles 확장 지원 사용
iMessage의 특수 기능(읽음 확인, 입력 중 표시기 등)
iOS 노드 통합(Camera, Canvas, Voice Wake)

Clawdbot의 강력한 기능을 계속 탐색하세요!🚀

부록: 소스 코드 참조

클릭하여 소스 코드 위치 펼치기

업데이트 시간: 2026-01-27

기능	파일 경로	행 번호
Signal RPC 클라이언트	`src/signal/client.ts`	1-186
Signal 데몬 관리	`src/signal/daemon.ts`	1-85
다중 계정 지원	`src/signal/accounts.ts`	1-84
Signal 모니터링 및 이벤트 처리	`src/signal/monitor.ts`	-
메시지 전송	`src/signal/send.ts`	-
Reactions 전송	`src/signal/send-reactions.ts`	-
Reaction 수준 구성	`src/signal/reaction-level.ts`	-

구성 유형 정의:

SignalAccountConfig: src/config/types.signal.ts:13-87
SignalConfig: src/config/types.signal.ts:89-93

핵심 상수:

DEFAULT_TIMEOUT_MS = 10_000: Signal RPC 요청 기본 제한 시간(10초) 출처: src/signal/client.ts:29
기본 HTTP 포트: 8080 출처: src/signal/accounts.ts:59
기본 텍스트 청킹 크기: 4000자 출처: docs/channels/signal.md:113

핵심 함수:

signalRpcRequest<T>(): JSON-RPC 요청을 signal-cli로 전송 출처: src/signal/client.ts:54-90
streamSignalEvents(): SSE를 통해 Signal 이벤트 구독 출처: src/signal/client.ts:112-185
spawnSignalDaemon(): signal-cli 데몬 시작 출처: src/signal/daemon.ts:50-84
resolveSignalAccount(): Signal 계정 구성 해결 출처: src/signal/accounts.ts:49-77
listEnabledSignalAccounts(): 활성화된 Signal 계정 나열 출처: src/signal/accounts.ts:79-83

처음부터 사용하기

일반적으로 사용되는 채팅 도구 연결

AI 초능력 잠금 해제

문제가 발생하면

Signal 채널 구성: signal-cli로 개인 AI 어시스턴트 연결 | Clawdbot 튜토리얼

이 과정을 완료하면 할 수 있는 것

현재 직면한 문제

Signal 채널 사용 시기

시작 전 준비

핵심 개념

따라하기

1단계: signal-cli 설치

2단계: Signal 계정 연결

3단계: Clawdbot의 Signal 채널 구성

방법 1: 빠른 구성(단일 계정)

방법 2: 다중 계정 구성

방법 3: 외부 데몬 모드

4단계: Gateway 시작

5단계: 첫 번째 메시지 전송

문제 해결 팁

문제 1: signal-cli 시작 실패

문제 2: 페어링 코드 만료

문제 3: 그룹 메시지 응답 없음

문제 4: 미디어 파일 다운로드 실패

문제 5: 긴 메시지 잘림 현상

이 과정 요약

다음 과정 미리보기

부록: 소스 코드 참조

Signal 채널 구성: signal-cli로 개인 AI 어시스턴트 연결 | Clawdbot 튜토리얼 ​

이 과정을 완료하면 할 수 있는 것 ​

현재 직면한 문제 ​

Signal 채널 사용 시기 ​

시작 전 준비 ​

핵심 개념 ​

따라하기 ​

1단계: signal-cli 설치 ​

2단계: Signal 계정 연결 ​

3단계: Clawdbot의 Signal 채널 구성 ​

방법 1: 빠른 구성(단일 계정) ​

방법 2: 다중 계정 구성 ​

방법 3: 외부 데몬 모드 ​

4단계: Gateway 시작 ​

5단계: 첫 번째 메시지 전송 ​

문제 해결 팁 ​

문제 1: signal-cli 시작 실패 ​

문제 2: 페어링 코드 만료 ​

문제 3: 그룹 메시지 응답 없음 ​

문제 4: 미디어 파일 다운로드 실패 ​

문제 5: 긴 메시지 잘림 현상 ​

이 과정 요약 ​

다음 과정 미리보기 ​

부록: 소스 코드 참조 ​

Signal 채널 구성: signal-cli로 개인 AI 어시스턴트 연결 | Clawdbot 튜토리얼

이 과정을 완료하면 할 수 있는 것

현재 직면한 문제

Signal 채널 사용 시기

시작 전 준비

핵심 개념

따라하기

1단계: signal-cli 설치

2단계: Signal 계정 연결

3단계: Clawdbot의 Signal 채널 구성

방법 1: 빠른 구성(단일 계정)

방법 2: 다중 계정 구성

방법 3: 외부 데몬 모드

4단계: Gateway 시작

5단계: 첫 번째 메시지 전송

문제 해결 팁

문제 1: signal-cli 시작 실패

문제 2: 페어링 코드 만료

문제 3: 그룹 메시지 응답 없음

문제 4: 미디어 파일 다운로드 실패

문제 5: 긴 메시지 잘림 현상

이 과정 요약

다음 과정 미리보기

부록: 소스 코드 참조