wxclawbot-send
이 스킬이 해결하는 문제
WeChat 로봇(iLink Bot)은 사용자 메시지에 수동적으로 응답할 수만 있을 뿐, 대화를 능동적으로 시작할 수 없습니다. 즉, 에이전트가 정기 알림, 알림 푸시, 보고서 전송 등 능동적인 접촉 시나리오를 수행할 수 없습니다.
이 스킬은 wxclawbot CLI를 통해 에이전트가 WeChat 사용자에게 텍스트, 이미지, 비디오, 파일을 포함한 메시지를 능동적으로 푸시할 수 있도록 합니다.
cron과 결합하여 정기 작업을 구현할 수 있습니다.
전제 조건
- Node.js >= 20
npm install -g @claw-lab/wxclawbot-cli- openclaw-weixin이 로그인되어 있어야 함 (자격 증명은
~/.openclaw/openclaw-weixin/accounts/에 있음)
확인: wxclawbot accounts --json
빠른 시작
wxclawbot send --text "메시지 내용" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "확인 바랍니다" --json
언제 무엇을 사용할지
능동적으로 텍스트 메시지 보내기 → wxclawbot send --text "msg" --json
능동적으로 파일/이미지 보내기 → wxclawbot send --file ./path --json
계정 상태 확인 → wxclawbot accounts --json
프로그래밍 방식 호출 → see references/programmatic-api.md
명령어 참조
send
wxclawbot send --text "message" --json
wxclawbot send --to "[email protected]" --text "안녕하세요" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "확인 바랍니다" --json
wxclawbot send --file "https://example.com/img.png" --json
echo "일일 보고서 생성됨" | wxclawbot send --json
wxclawbot send --text "test" --dry-run
| 매개변수 | 설명 |
|---|---|
--text <msg> | 메시지 텍스트. "-"은 stdin을 명시적으로 읽음 |
--file <path> | 로컬 파일 또는 URL (이미지 / 비디오 / 파일) |
--to <userId> | 대상 사용자 ID. 기본값: 계정에 바인딩된 사용자 |
--account <id> | 계정 지정. 기본값: 첫 번째 사용 가능한 계정 |
--json | JSON 형식 출력. 프로그래밍 호출 시 필수 |
--dry-run | 미리보기, 전송하지 않음 |
미디어 유형은 확장자에 따라 자동 식별:
- 이미지: .png .jpg .jpeg .gif .webp .bmp
- 비디오: .mp4 .mov .webm .mkv .avi
- 파일: 기타 모든 것
accounts
wxclawbot accounts --json
반환: [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]
계정 발견 메커니즘
CLI는 ~/.openclaw/openclaw-weixin/accounts/*.json에서 자동으로 계정을 발견합니다.
각 파일에는 token, baseUrl, userId(기본 --to 대상)이 포함됩니다.
- Bot ID는 실행 중인 token에서 추출됩니다 (하드코딩되지 않음)
- 계정 ID는 openclaw-weixin 업그레이드 또는 재등록 후 변경될 수 있습니다
--to의 기본값은 계정 파일의userId(바인딩된 사용자)입니다.WXCLAW_TOKEN환경 변수가 설정되면 파일 발견 메커니즘을 재정의합니다
Context Token (능동 푸시의 핵심)
WeChat은 메시지를 능동적으로 푸시하려면 context_token이 필요합니다. 이것이 없으면 메시지는 서버에 남아 있다가
사용자가 채팅 창을 열어야만 볼 수 있습니다. 이것은 '능동 푸시'라고 할 수 없습니다.
CLI는 자동으로 {accountId}.context-tokens.json(계정 파일과 동일한 디렉토리)을 읽습니다.
이 파일은 openclaw-weixin에 의해 유지 관리되며, 형식은 userId → contextToken 매핑입니다.
수동 구성이 필요하지 않습니다. 사용자가 로봇에게 메시지를 보낸 후 openclaw-weixin이 자동으로 저장합니다.
context_token이 없으면 (새 사용자, 토큰 만료) 메시지는 여전히 성공적으로 전송됩니다
(ok:true), 그러나 알림이 능동적으로 푸시되지는 않습니다.
openclaw-weixin을 업그레이드한 후에는 반드시 wxclawbot accounts --json으로 확인하십시오.
에이전트 통합
프로그래밍 호출 시 반드시 --json을 사용하십시오. JSON을 파싱하여 성공 여부를 판단합니다.
result=$(wxclawbot send --text "작업 완료" --json)
result=$(wxclawbot send --file ./chart.png --text "일일 지표" --json)
- 성공:
{"ok":true,"to":"[email protected]","clientId":"..."} - 실패:
{"ok":false,"error":"..."} - 종료 코드: 0 = CLI 실행 성공, 1 = 실패
참고: exit 0은 CLI가 실행되었음을 의미할 뿐, 메시지가 전달되었음을 의미하지는 않습니다. ok 필드를 확인하십시오.
오류 처리
| 오류 | 의미 | 처리 |
|---|---|---|
ret=-2 | 빈도 제한 (봇당 약 7개 / 5분, 모든 클라이언트 공유) | 60-120초 대기 후 재시도, 빡빡한 루프 피하기 |
ret=-14 | 세션 만료 | openclaw를 통해 다시 로그인 |
| No account found | 자격 증명 누락 | wxclawbot accounts 실행하여 확인 |
| CDN upload error | 파일 업로드 실패 | 파일 크기/형식 확인 후 재시도 |
| Request timeout | 네트워크 문제 (15초 시간 초과) | 재시도 |
빈도 제한은 서버 측에 있으며, 동일한 bot token 아래의 모든 클라이언트가 할당량을 공유합니다.
구조화된 전송 오류 (v0.5.1+)
--json 모드에서 전송 계층 실패는 추가 필드를 포함합니다:
{"ok":false,"error":"send failed: ...","errorKind":"timeout","retryable":true}
errorKind | 의미 | retryable |
|---|---|---|
timeout | 요청이 15초 초과 | true |
dns | DNS 확인 실패 | true |
connection | 연결 재설정 / socket hang up | true |
network | 연결 거부 / 호스트에 연결할 수 없음 / fetch 실패 | true |
tls | 인증서 또는 TLS 오류 | false |
unknown | 분류되지 않은 오류 | false |
retryable 필드를 사용하여 재시도해야 하는지 아니면 바로 실패 처리해야 하는지 판단합니다.
일반적인 함정
- 반드시
--json을 사용할 것 — 없으면 사람이 읽을 수 있는 형식으로 출력되어 구문 분석이 불가능합니다 ok필드를 확인할 것 — exit 0은 CLI가 실행되었음을 의미할 뿐, 메시지가 도착했음을 의미하지 않습니다ret=-2에 대해 빡빡한 루프 재시도 금지 — 최소 5-10초 기다리십시오- 큰 텍스트는 stdin 사용 —
echo "..." | wxclawbot send --json, 쉘 따옴표 문제 방지 - 파일은 암호화되어 WeChat CDN에 업로드됨 — 큰 파일은 시간이 걸릴 수 있습니다
환경 변수
| 변수 | 용도 |
|---|---|
WXCLAW_TOKEN | bot token 재정의 ([email protected]:your-token) |
WXCLAW_BASE_URL | API 엔드포인트 재정의 (기본값: https://ilinkai.weixin.qq.com) |
프로그래밍 인터페이스는 references/programmatic-api.md를 참조하십시오.