Communitygithub.com

lroolle/wxclawbot-cli

Weixin ClawBot CLI - OpenClaw 에이전트를 위한 능동 메시징 도구

wxclawbot-cli란 무엇인가요?

이 스킬은 WeChat(微信) 봇에게 능동적인 메시지 전송 기능을 제공하는 `wxclawbot` CLI 도구입니다. 기존의 iLink Bot은 사용자 메시지에만 수동적으로 응답할 수 있었지만, 이 CLI를 통해 에이전트는 정해진 시간에 알림, 보고서, 파일 등을 사용자에게 직접 푸시할 수 있습니다. 텍스트, 이미지, 동영상, 파일 등 다양한 미디어 유형을 지원하며, cron과 결합하여 정기적인 작업을 자동화할 수 있습니다. 주로 Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 통합되어 사용되며, `--json` 플래그를 통해 프로그래밍 방식의 호출이 가능합니다. CLI는 자동으로 WeChat 계정 파일을 발견하고, context token을 활용하여 메시지가 사용자에게 즉시 전달되도록 보장합니다. 또한 주파수 제한, 세션 만료, CDN 업로드 오류 등 다양한 오류 처리 메커니즘을 제공하여 안정적인 통신을 보장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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>계정 지정. 기본값: 첫 번째 사용 가능한 계정
--jsonJSON 형식 출력. 프로그래밍 호출 시 필수
--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
dnsDNS 확인 실패true
connection연결 재설정 / socket hang uptrue
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_TOKENbot token 재정의 ([email protected]:your-token)
WXCLAW_BASE_URLAPI 엔드포인트 재정의 (기본값: https://ilinkai.weixin.qq.com)

프로그래밍 인터페이스는 references/programmatic-api.md를 참조하십시오.

관련 스킬