OpenClaw Signal 채널
메시징
어려움
signal-cli를 사용하여 OpenClaw를 Signal에 연결합니다. signal-cli는 Signal 프로토콜을 위한 서드파티 오픈소스 커맨드라인 인터페이스입니다. 이 통합은 완전한 종단간 암호화를 갖춘 프라이버시 우선 AI 메시징을 제공합니다. OpenClaw는 HTTP JSON-RPC 및 Server-Sent Events를 통해 signal-cli 데몬과 통신하여 AI 어시스턴트가 Signal에서 메시지를 주고받을 수 있도록 합니다. 봇 계정에는 전용 전화번호가 필요합니다.
기본 정보
난이도어려움
카테고리메시징
지원 기능 수4 / 6
Signal 지원 기능
텍스트 메시지
지원
미디어 및 파일
지원
리액션
지원
스레드
미지원
음성 메시지
미지원
그룹 채팅
지원
Signal 사전 요구사항
- Signal 봇 계정용 전용 전화번호 (개인 번호와 분리)
- 서버에 Java Runtime Environment (JRE 25+) 설치
- signal-cli 설치 및 PATH에 등록
- OpenClaw Gateway 실행 및 구성 완료
- 봇을 연결할 기존 Signal 계정 (또는 새 등록)
Signal 빠른 설정
1
signal-cli 설치
공식 GitHub 저장소에서 signal-cli를 다운로드하여 설치합니다. Java 25 이상이 필요합니다. 터미널에서 'signal-cli --version'을 실행하여 설치를 확인하세요.
2
Signal 계정 연결 또는 등록
'signal-cli link -n "OpenClaw"'를 실행하여 기존 Signal 계정에 연결하고 다른 기기에서 QR 코드를 스캔합니다. 또는 'signal-cli -a +15551234567 register'로 새 계정을 등록할 수 있습니다. 전용 번호를 사용하세요 — 개인 계정에서 실행하면 자체 메시지 루프가 발생합니다.
3
Signal 채널 구성 추가
~/.openclaw/openclaw.json에 Signal 채널 구성을 추가합니다. 'account' 필드를 봇의 E.164 형식 전화번호로 설정하고 dmPolicy(pairing, allowlist 또는 open)를 구성하여 어시스턴트에게 메시지를 보낼 수 있는 사용자를 제어합니다.
4
Gateway 시작 및 테스트 메시지 전송
Gateway 프로세스를 시작합니다. OpenClaw가 자동으로 signal-cli 데몬을 시작합니다. 다른 Signal 계정에서 봇 번호로 메시지를 보냅니다. 기본 pairing 정책을 사용하는 경우 'openclaw pairing approve signal <code>'로 발신자를 승인하세요.
Signal 구성 예시
config.json
{
"channels": {
"signal": {
"enabled": true,
"account": "+15551234567",
"dmPolicy": "pairing"
}
}
}Signal 상세 문서
아키텍처 개요
OpenClaw는 signal-cli를 통해 Signal에 연결됩니다. signal-cli는 Signal 프로토콜을 구현하는 Java 기반 커맨드라인 클라이언트입니다. 이 아키텍처는 실시간 메시지 전달을 위해 HTTP JSON-RPC 인터페이스와 Server-Sent Events (SSE)를 사용합니다.
기본적으로 OpenClaw는 Gateway 시작 시 signal-cli 데몬 프로세스를 자동으로 생성합니다. 데몬은 모든 Signal 프로토콜 작업(암호화, 키 교환, 메시지 송수신)을 처리하며, OpenClaw는 로컬 HTTP API를 통해 데몬과 통신합니다. 이를 통해 Signal 프로토콜 계층이 AI 로직과 완전히 분리됩니다.
또는 signal-cli를 외부 데몬으로 실행하고 httpUrl 구성을 통해 OpenClaw를 연결할 수 있습니다. 이는 signal-cli를 독립적으로 관리하거나 다른 호스트에서 실행할 때 유용합니다.
자동 시작 데몬은 기본적으로 127.0.0.1:8080에 바인딩됩니다. 다른 주소가 필요하면 httpHost와 httpPort를 변경하세요.
signal-cli를 외부에서 실행하면 업데이트 및 라이프사이클 관리를 더 자유롭게 제어할 수 있습니다. 자동 시작을 비활성화하려면 httpUrl을 전체 데몬 URL로 설정하세요.
Signal 계정 설정
봇에는 전용 Signal 계정이 필요합니다. 개인 번호를 사용하지 마세요 — Signal은 자체 전송 메시지를 무시하며, 같은 번호에서 개인 계정과 봇 계정을 동시에 실행하면 라우팅 충돌이 발생합니다.
계정 설정에는 두 가지 옵션이 있습니다:
• 기존 기기 연결 — 'signal-cli link -n "OpenClaw"'를 실행하여 기기 연결 URI를 생성합니다. 기본 Signal 앱에서 QR 코드를 스캔합니다. 가장 간단한 방법이므로 권장됩니다.
• 새 등록 — 'signal-cli -a +15551234567 register'를 실행하여 새 Signal 계정을 직접 등록합니다. SMS 또는 음성 통화로 번호를 인증해야 합니다.
연결 또는 등록이 완료되면 signal-cli는 인증 정보와 키를 로컬에 저장합니다. 이 정보는 재시작 후에도 유지됩니다.
openclaw.json
{
"channels": {
"signal": {
"account": "+15551234567",
"cliPath": "/usr/local/bin/signal-cli"
}
}
}개인 Signal 번호로 봇을 실행하지 마세요. Signal의 자체 메시지 보호 기능이 자신에게 보낸 메시지를 무시하여 봇이 정상적으로 작동하지 않습니다.
외부 데몬 모드
고급 배포의 경우 signal-cli를 OpenClaw 외부에서 독립 실행형 데몬 프로세스로 실행할 수 있습니다. signal-cli 업데이트를 독립적으로 관리하거나, 별도의 머신에서 실행하거나, 여러 서비스 간에 단일 데몬을 공유할 때 유용합니다.
데몬을 수동으로 시작합니다:
signal-cli -a +15551234567 daemon --http=127.0.0.1:8080
그런 다음 httpUrl을 설정하여 OpenClaw를 연결합니다. httpUrl이 구성되면 OpenClaw는 데몬 자동 시작을 건너뛰고 기존 프로세스에 연결합니다.
openclaw.json
{
"channels": {
"signal": {
"account": "+15551234567",
"httpUrl": "http://127.0.0.1:8080/api/v1/rpc"
}
}
}외부 데몬을 사용할 때는 Gateway보다 먼저 데몬을 시작하세요. OpenClaw는 데몬이 사용 가능해질 때까지 최대 startupTimeoutMs(최대 120초)까지 대기합니다.
DM 정책
DM(다이렉트 메시지) 정책은 개인 채팅에서 AI 어시스턴트와 상호작용할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다:
• pairing (기본값) — 새로운 연락처가 봇에 처음 메시지를 보내면 무작위 페어링 코드를 받습니다. 코드는 1시간 후 만료됩니다. 터미널에서 'openclaw pairing approve signal <code>'로 승인합니다. 승인 후 자유롭게 채팅할 수 있습니다.
• allowlist — allowFrom에 나열된 전화번호 또는 UUID만 봇에 메시지를 보낼 수 있습니다. 나머지는 무시됩니다. 전화번호는 E.164 형식을, UUID 전용 연락처는 'uuid:<id>'를 사용합니다.
• open — 봇에 메시지를 보내는 모든 사람이 응답을 받습니다. 안전 확인으로 allowFrom 목록에 '*'를 추가해야 합니다. 주의하여 사용하세요.
• disabled — DM 기능이 완전히 비활성화됩니다.
openclaw.json
{
"channels": {
"signal": {
"dmPolicy": "allowlist",
"allowFrom": ["+15551234567", "uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}
}
}전화번호를 공유하지 않고 Signal에 등록한 연락처는 allowFrom 목록에 'uuid:<id>'로 표시됩니다. UUID를 확인하려면 Gateway 로그를 확인하세요.
연락처별 기록 제한은 dms["<phone_or_uuid>"].historyLimit을 통해 설정하여 전역 dmHistoryLimit을 재정의할 수 있습니다.
그룹 채팅 관리
OpenClaw는 구성 가능한 접근 제어를 통해 Signal 그룹 채팅을 지원합니다:
• open — 모든 그룹 멤버의 메시지 수신
• allowlist — 승인된 발신자(groupAllowFrom을 통해)만 봇을 트리거 가능
• disabled — 모든 그룹 메시지 무시
그룹 대화는 DM과 완전히 분리됩니다. 메시지는 'agent:<agentId>:signal:group:<groupId>'로 태그되어 그룹별로 별도의 컨텍스트와 기록을 유지합니다.
그룹별로 historyLimit을 구성하여 AI 컨텍스트에 포함할 메시지 수를 제어할 수 있습니다(기본값 50, 0으로 설정하면 기록 비활성화).
openclaw.json
{
"channels": {
"signal": {
"groupPolicy": "open",
"historyLimit": 50
}
}
}프라이버시 및 종단간 암호화
Signal은 프라이빗 메시징의 최고 표준입니다. 봇과 연락처 간의 모든 메시지는 Signal 프로토콜(Double Ratchet 알고리즘 + X3DH 키 합의)을 사용하여 종단간 암호화됩니다. OpenClaw는 전송 중인 평문 메시지를 볼 수 없습니다 — 복호화는 서버의 signal-cli 프로세스 내부에서 로컬로 이루어집니다.
주요 프라이버시 특성:
• 메시지는 클라이언트 간 암호화 — Signal 서버도 읽을 수 없습니다
• signal-cli는 암호화 키를 서버에 로컬로 저장합니다
• Anthropic, OpenAI 또는 기타 서드파티 AI 제공업체의 인프라를 통해 데이터가 전달되지 않습니다 (메시지는 로컬에서 복호화되고, 자체 호스팅된 Gateway에서 처리되며, 대화 컨텍스트만 구성된 AI 제공업체로 전송됩니다)
• ignoreStories: true로 스토리 이벤트를 완전히 무시할 수 있습니다
최대한의 프라이버시를 위해 Signal과 로컬 호스팅 LLM 제공업체(예: Ollama)를 결합하여 모든 데이터를 자체 인프라에 유지하세요.
리액션
OpenClaw는 Signal 메시지에 대한 이모지 리액션 전송 및 수신을 지원합니다. 리액션은 확인(사용자에게 메시지가 수신되었음을 표시) 및 대화형 에이전트 동작에 유용합니다.
리액션 구문은 E.164 형식, UUID 형식 또는 그룹 형식의 대상과 함께 메시지 도구를 사용합니다:
• DM 리액션: target=+15551234567 또는 target=uuid:<id>
• 그룹 리액션: target=signal:group:<groupId> 및 targetAuthor=uuid:<sender>
리액션 동작을 전역 또는 계정별로 구성합니다:
• actions.reactions — 리액션 기능 활성화/비활성화 (기본값 true)
• reactionLevel — off/ack (비활성화) 또는 minimal/extensive (가이드와 함께 활성화)
openclaw.json
{
"channels": {
"signal": {
"reactionLevel": "minimal"
}
}
}미디어 및 첨부파일
OpenClaw는 이미지, 문서, 오디오, 비디오를 포함한 Signal의 미디어 파일을 처리합니다. 미디어는 signal-cli를 통해 base64 인코딩 데이터로 전송됩니다.
수신 미디어는 ignoreAttachments가 true로 설정되지 않는 한 자동으로 다운로드되어 처리됩니다. 발신 미디어는 전송 전에 signal-cli에서 base64로 가져옵니다.
기본 파일 크기 제한은 8 MB(mediaMaxMb)입니다. Signal 자체는 더 큰 파일을 지원하지만, base64 인코딩 오버헤드와 처리 시간을 고려하면 8 MB가 실용적인 기본값입니다.
openclaw.json
{
"channels": {
"signal": {
"mediaMaxMb": 8,
"ignoreAttachments": false
}
}
}타이핑 표시기 및 읽음 확인
OpenClaw는 AI 응답을 생성하는 동안 자연스러운 대화 느낌을 유지하기 위해 타이핑 표시기를 전송합니다. Gateway는 signal-cli의 sendTyping 엔드포인트를 호출하고 응답 생성 중에 주기적으로 표시기를 갱신합니다.
sendReadReceipts가 활성화되면 승인된 DM 연락처에 대해 읽음 확인을 전달할 수 있습니다. 이를 통해 발신자가 자신의 메시지가 처리되었음을 알 수 있습니다.
참고: 그룹 읽음 확인은 signal-cli에서 지원되지 않습니다.
openclaw.json
{
"channels": {
"signal": {
"sendReadReceipts": true
}
}
}텍스트 청킹 및 전달
긴 AI 응답의 경우 OpenClaw는 자동으로 텍스트를 여러 메시지로 분할합니다. 기본 청크 크기는 메시지당 4,000자입니다.
두 가지 청킹 모드를 사용할 수 있습니다:
• length (기본값) — 문자 제한에서 강제 분할
• newline — 먼저 단락 경계에서 분할한 다음 문자 제한 적용
전달 대상은 E.164 전화번호, UUID 또는 그룹 ID를 사용합니다:
• DM: signal:+15551234567 또는 E.164 번호
• UUID DM: uuid:<id> 또는 UUID
• 그룹: signal:group:<groupId>
openclaw.json
{
"channels": {
"signal": {
"textChunkLimit": 4000,
"chunkMode": "newline"
}
}
}Signal 구성 참조
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Signal 채널 활성화 또는 비활성화 |
| account | string | "" | E.164 형식의 봇 전화번호 (예: +15551234567). 필수 |
| cliPath | string | "signal-cli" | signal-cli 실행 파일 경로 |
| httpUrl | string | "" | 외부 signal-cli 데몬의 전체 URL. 설정 시 자동 시작 비활성화 |
| httpHost | string | "127.0.0.1" | 자동 시작 signal-cli 데몬이 바인딩할 호스트 주소 |
| httpPort | number | 8080 | 자동 시작 signal-cli 데몬이 바인딩할 포트 |
| autoStart | boolean | true | Gateway 시작 시 signal-cli 데몬 자동 생성 여부 |
| startupTimeoutMs | number | 30000 | signal-cli 데몬이 사용 가능해질 때까지 대기하는 최대 시간(ms). 최대 120000 |
| dmPolicy | string | "pairing" | 봇에 DM을 보낼 수 있는 사용자 제어. 옵션: pairing, allowlist, open, disabled |
| allowFrom | string[] | [] | 봇에 메시지를 보낼 수 있는 전화번호(E.164) 또는 uuid:<id> 식별자 |
| dmHistoryLimit | number | 50 | 대화별 AI 컨텍스트에 포함할 최근 DM 메시지 수 |
| groupPolicy | string | "disabled" | 그룹 채팅 정책. 옵션: disabled, allowlist, open |
| groupAllowFrom | string[] | [] | 그룹에서 봇을 트리거할 수 있는 전화번호 또는 UUID (groupPolicy가 allowlist일 때) |
| historyLimit | number | 50 | AI 컨텍스트에 포함할 최대 그룹 메시지 수. 0으로 설정하면 비활성화 |
| sendReadReceipts | boolean | false | 승인된 DM 연락처에 대해 읽음 확인 신호 전달 여부 |
| textChunkLimit | number | 4000 | 청킹 전 발신 메시지당 최대 문자 수 |
| chunkMode | string | "length" | 텍스트 청킹 모드. 옵션: length (강제 분할), newline (단락 인식) |
| mediaMaxMb | number | 8 | 수신/발신 첨부파일의 최대 미디어 파일 크기(MB) |
| ignoreAttachments | boolean | false | 수신 미디어 첨부파일 다운로드 건너뛰기 |
| ignoreStories | boolean | false | Signal 스토리 이벤트 완전 무시 |
| receiveMode | string | "" | 메시지 수신 모드. 옵션: on-start (시작 시 가져오기), manual |
| configWrites | boolean | true | 런타임에 /config 명령으로 채널 설정 수정 허용 |
| reactionLevel | string | "ack" | 봇 리액션 기능. 옵션: off, ack, minimal, extensive |
enabled
Type: booleanDefault: true
Signal 채널 활성화 또는 비활성화
account
Type: stringDefault: ""
E.164 형식의 봇 전화번호 (예: +15551234567). 필수
cliPath
Type: stringDefault: "signal-cli"
signal-cli 실행 파일 경로
httpUrl
Type: stringDefault: ""
외부 signal-cli 데몬의 전체 URL. 설정 시 자동 시작 비활성화
httpHost
Type: stringDefault: "127.0.0.1"
자동 시작 signal-cli 데몬이 바인딩할 호스트 주소
httpPort
Type: numberDefault: 8080
자동 시작 signal-cli 데몬이 바인딩할 포트
autoStart
Type: booleanDefault: true
Gateway 시작 시 signal-cli 데몬 자동 생성 여부
startupTimeoutMs
Type: numberDefault: 30000
signal-cli 데몬이 사용 가능해질 때까지 대기하는 최대 시간(ms). 최대 120000
dmPolicy
Type: stringDefault: "pairing"
봇에 DM을 보낼 수 있는 사용자 제어. 옵션: pairing, allowlist, open, disabled
allowFrom
Type: string[]Default: []
봇에 메시지를 보낼 수 있는 전화번호(E.164) 또는 uuid:<id> 식별자
dmHistoryLimit
Type: numberDefault: 50
대화별 AI 컨텍스트에 포함할 최근 DM 메시지 수
groupPolicy
Type: stringDefault: "disabled"
그룹 채팅 정책. 옵션: disabled, allowlist, open
groupAllowFrom
Type: string[]Default: []
그룹에서 봇을 트리거할 수 있는 전화번호 또는 UUID (groupPolicy가 allowlist일 때)
historyLimit
Type: numberDefault: 50
AI 컨텍스트에 포함할 최대 그룹 메시지 수. 0으로 설정하면 비활성화
sendReadReceipts
Type: booleanDefault: false
승인된 DM 연락처에 대해 읽음 확인 신호 전달 여부
textChunkLimit
Type: numberDefault: 4000
청킹 전 발신 메시지당 최대 문자 수
chunkMode
Type: stringDefault: "length"
텍스트 청킹 모드. 옵션: length (강제 분할), newline (단락 인식)
mediaMaxMb
Type: numberDefault: 8
수신/발신 첨부파일의 최대 미디어 파일 크기(MB)
ignoreAttachments
Type: booleanDefault: false
수신 미디어 첨부파일 다운로드 건너뛰기
ignoreStories
Type: booleanDefault: false
Signal 스토리 이벤트 완전 무시
receiveMode
Type: stringDefault: ""
메시지 수신 모드. 옵션: on-start (시작 시 가져오기), manual
configWrites
Type: booleanDefault: true
런타임에 /config 명령으로 채널 설정 수정 허용
reactionLevel
Type: stringDefault: "ack"
봇 리액션 기능. 옵션: off, ack, minimal, extensive
Signal 자주 묻는 질문
Signal 문제 해결
signal-cli가 Java 오류로 시작되지 않음
Java가 설치되지 않았거나 설치된 버전이 너무 오래되었습니다. signal-cli는 Java 25 이상이 필요합니다.
서버에 OpenJDK 25+를 설치하세요. 'java --version'으로 확인합니다. 여러 Java 버전이 설치된 경우 올바른 버전이 PATH에 있는지 확인하거나 JAVA_HOME을 설정하세요. 또한 'signal-cli --version'을 실행하여 signal-cli가 올바르게 설치되었는지 확인하세요.
봇이 어떤 메시지에도 응답하지 않음
account 필드가 올바르지 않거나, signal-cli 데몬이 실행되지 않거나, 발신자가 페어링을 통해 승인되지 않았을 수 있습니다.
account 번호가 등록된 signal-cli 계정(국가 코드 포함 E.164 형식)과 일치하는지 확인합니다. 'openclaw status' 및 'openclaw gateway status'를 실행하여 데몬이 실행 중인지 확인합니다. pairing 정책을 사용하는 경우 'openclaw pairing list signal'로 대기 중인 페어링을 확인하고 발신자를 승인하세요.
승인 후에도 DM이 무시됨
발신자가 allowFrom 목록에 없거나(allowlist 정책 사용 시) 발신자의 식별자 형식이 일치하지 않을 수 있습니다.
Gateway 로그에서 발신자의 식별자를 확인하세요. 일부 Signal 사용자는 전화번호를 공유하지 않고 등록하여 전화번호 대신 'uuid:<id>'로 표시됩니다. 올바른 식별자를 allowFrom에 추가하세요. 자세한 채널 진단을 위해 'openclaw channels status --probe'를 실행하세요.
그룹 메시지가 수신되지 않음
groupPolicy가 'disabled'(기본값)로 설정되어 있거나 그룹이 허용 목록에 없습니다.
모든 그룹 메시지를 수신하려면 groupPolicy를 'open'으로 설정하거나, 'allowlist'를 사용하고 그룹 ID를 groupAllowFrom에 추가하세요. 그룹 메시지가 수신될 때 Gateway 로그에서 그룹 ID를 확인하세요.
외부 데몬 연결 실패 (httpUrl에 접근 불가)
signal-cli 데몬이 실행되지 않거나, URL이 올바르지 않거나, 방화벽이 연결을 차단하고 있습니다.
데몬이 실행 중이고 예상 host:port에서 수신 대기 중인지 확인하세요. 'curl http://127.0.0.1:8080/api/v1/rpc'로 연결을 테스트하세요. 여러 머신에서 실행하는 경우 방화벽 규칙을 확인하세요. 데몬이 httpUrl 구성과 일치하는 올바른 --http 플래그로 시작되었는지 확인하세요.