WeChat RPA Bot Skill

This skill allows any Agent (like OpenClaw) to act as a WeChat assistant by hooking into the YokoWebot RPA backend. It provides autonomous installation, startup, activation, initialization, and API-based control over WeChat Desktop.

1. Installation & Setup (For the Agent)

If the user wants to install this skill or hasn't set it up yet:

1. Ensure the user is on Windows and has WeChat Desktop 4.1.7 installed (not newer, not older).
   • Version check: open WeChat → Help (帮助) → About (关于) → confirm version is 4.1.7
   • If wrong version, download from: https://n2b8xxdgjx.feishu.cn/wiki/Nbauw9HWsihsQ7kgjYPcfZSCnKb
2. Download the core binary

   service.exe

   from the GitHub Releases page and place it in the root directory of this skill.

   curl -L -o service.exe https://github.com/LeoMusk/wechat-rpa-bot-skill/releases/download/v1.7.0/service.exe
   

3. Install Python dependencies (if running from source):

   pip install psutil requests
   

4. The project uses an Activation Code system — no

   .env

   file needed. Activation codes are obtained from: www.yokoagi.com

2. Service Lifecycle

2.1 Starting the RPA Service

Architecture Note — Sandbox Isolation: If you are running inside a restricted sandbox (e.g., QClaw), you cannot access the user's interactive desktop (Session 1). Spawning

service.exe

The correct SOP (Standard Operating Procedure) is:

Step 1 — Check if already running: Always ping

http://127.0.0.1:9922/docs

Step 2 — Generate desktop launcher scripts: If the service is not running, generate both

启动微信RPA.bat

停止微信RPA.bat

IMPORTANT: Only GENERATE these files — do NOT execute them yourself.

Python code to generate both scripts (run this code, do not execute the bat files):

import os

desktop = os.path.join(os.path.expanduser("~"), "Desktop")
skill_dir = os.path.abspath(".")  # adjust to the actual skill directory path

# --- Start bat ---
start_bat = os.path.join(desktop, "启动微信RPA.bat")
if not os.path.exists(start_bat):
    with open(start_bat, "w", encoding="gbk") as f:
        f.write(
            "@echo off\n"
            "chcp 65001\n"
            "echo 正在清理旧的 RPA 进程...\n"
            f"cd /d {skill_dir}\n"
            "python scripts\\stop_server.py\n"
            "echo 正在启动微信 RPA 服务，请稍候...\n"
            "set WEBOT_BACKEND_MODE=1\n"
            "set HEADLESS_MODE=1\n"
            "set DISABLE_WEBVIEW=1\n"
            "set NO_BROWSER=1\n"
            "python scripts\\start_server.py\n"
            "pause\n"
        )
    print(f"Created: {start_bat}")

# --- Stop bat ---
stop_bat = os.path.join(desktop, "停止微信RPA.bat")
if not os.path.exists(stop_bat):
    with open(stop_bat, "w", encoding="gbk") as f:
        f.write(
            "@echo off\n"
            "chcp 65001\n"
            "echo 正在停止微信 RPA 服务...\n"
            f"cd /d {skill_dir}\n"
            "python scripts\\stop_server.py\n"
            "echo 服务已停止！\n"
            "pause\n"
        )
    print(f"Created: {stop_bat}")

Step 3 — Prompt the user:

"由于沙箱隔离限制，我已在您的桌面生成了两个脚本：

• 启动微信RPA.bat

  — 启动服务（已内置自动清理旧进程逻辑）

• 停止微信RPA.bat

  — 服务使用完毕后关闭

请先双击桌面上的

启动微信RPA.bat

来启动服务，启动成功后请回复我"已启动"。"

Step 4 — Verify and proceed: After the user confirms, ping

http://127.0.0.1:9922/docs

2.2 WeChat Initialization (Two-Step SOP)

CRITICAL RULES — read carefully:

• auto_config

  is a destructive operation (it kills WeChat and restarts it). NEVER call

  POST /api/system/wechat41/auto_config

  unless Step 1 below explicitly returns

  ENV_NOT_CONFIGURED

  .
• Always call

  POST /api/init/multi

  without auto_config first (Step 1).

Standard initialization flow:

Step 1: POST /api/init/multi
        Headers: X-API-Key: yoko_test
        Body: {}

        → success (instances returned)       → Done. WeChat is initialized.
        → error_code: UNAUTHORIZED           → Go to Section 3 (Activation).
        → code: ENV_NOT_CONFIGURED           → Go to Step 2 below.
        → other error                        → Report to user, suggest restarting service.

Step 2: (Only if ENV_NOT_CONFIGURED)
        Ask user: "微信环境尚未配置，我需要短暂关闭并重启您的微信来完成配置，是否继续？"
        
        If user agrees:
          a. POST /api/system/wechat41/auto_config
             (WeChat will be killed and restarted — this is expected)
          b. Wait 5 seconds for WeChat to restart
          c. Warn the user:
             "配置过程中 Windows 讲述人（屏幕阅读器）可能会短暂启动并发出声音，
              这是正常现象。配置完成后如果仍有声音，请告诉我"关闭讲述人"，
              我会帮您关闭。"
          d. POST /api/init/multi again → should return success now.

2.3 Stopping the Service

The RPA service runs as a background daemon — it keeps running even after the Agent conversation ends or the browser UI is closed. This is by design, but you should help the user stop it when appropriate.

When to suggest stopping the service:

• The user explicitly says they're done with WeChat / don't need it anymore.
• The user says the service is using too much memory or wants to free up resources.
• Before a planned system shutdown or restart.

⚠️ Sandbox Cannot Kill User-Session Processes — CRITICAL

If you are running inside a sandbox (e.g., QClaw), you CANNOT kill

service.exe

.bat

This is a Windows Session Isolation security boundary:

• Desktop

  .bat

  →

  service.exe

  runs in Session 1 (user's interactive desktop)
• Sandbox agent → runs in Session 0 or a restricted session

• taskkill /F /PID <pid>

  across sessions = Access Denied — this will ALWAYS fail silently

Therefore:

• NEVER attempt to kill

  service.exe

  using

  taskkill

  ,

  stop_server.py

  , or PowerShell

  Stop-Process

  from within the sandbox. It will fail and waste time.
• The only reliable way to stop the service is to ask the user to run

  停止微信RPA.bat

  on their desktop (which runs in Session 1 and has the correct permissions).

How to guide the user when stop is needed:

"由于沙箱权限限制，我无法直接关闭在您桌面上启动的 RPA 服务。请双击桌面上的

停止微信RPA.bat

来安全关闭服务，完成后请告诉我。"

If the stop bat doesn't exist on the desktop (e.g., first time), regenerate it using the Python code in Section 2.1 Step 2.

Avoid Running Two Instances

Two

service.exe

service.exe

启动微信RPA.bat

If the user is experiencing port 9922 occupied on next startup: The start bat already handles this — it calls

stop_server.py

启动微信RPA.bat

3. Activation

If

POST /api/init/multi

UNAUTHORIZED

1. Call

   GET /api/license/machine-code

   to retrieve the device's machine code.
2. Tell the user:

   "软件尚未激活。请前往 www.yokoagi.com 获取激活码，获取后告诉我，我将为您完成自动激活。"

3. After the user provides the Activation Code, call

   POST /api/license/activate

   with:

   { "activation_code": "<user_provided>", "machine_code": "<from_step_1>" }
   

4. On success, call

   POST /api/init/multi

   again to complete initialization.

4. Opening the Frontend UI

The skill includes a pre-built frontend UI served at

http://127.0.0.1:9922/

Open UI only after WeChat is successfully initialized (Section 2.2 must return success first). Before initialization, the UI shows "微信掉线" and is non-functional.

When the user asks to open the UI:

import webbrowser
webbrowser.open('http://127.0.0.1:9922/')

Always also provide a fallback link in the response:

"可视化控制台已为您准备好：👉 打开微信 RPA 控制台 若浏览器未自动弹出，请手动点击上方链接。"

Handling "Close Narrator" (关闭讲述人)

When the user reports hearing Narrator (屏幕阅读器) sounds and wants it closed:

taskkill /F /IM Narrator.exe /T

5. API Usage

Once initialized, control WeChat via HTTP REST APIs.

• Base URL:

  http://127.0.0.1:9922

• Auth Header:

  X-API-Key: yoko_test

  (required on all requests)
• API Reference: See

  references/openapi.json

  for all endpoints.

Bypass System Proxy for localhost

If the user has a system proxy (VPN on port 33210, 7890, etc.), localhost calls may be intercepted. Always disable proxy when calling

127.0.0.1

Chinese Encoding in API Requests

Recommended — Python requests (auto UTF-8, proxy disabled):

python -c "import requests; requests.post('http://127.0.0.1:9922/api/chat/send_message', headers={'X-API-Key':'yoko_test'}, json={'user':'联系人昵称','message':'消息内容'}, proxies={'http': None, 'https': None})"

Alternative — curl.exe:

chcp 65001
curl.exe --noproxy "*" -X POST http://127.0.0.1:9922/api/chat/send_message -H "Content-Type: application/json" -H "X-API-Key: yoko_test" -d "{\"user\":\"联系人昵称\",\"message\":\"消息内容\"}"

Avoid PowerShell

Invoke-RestMethod

Send Message Best Practices

⚠️ CRITICAL: 发送消息时直接使用用户提供的联系人名称（备注名、昵称或微信号），无需提前查询联系人或获取wxid。RPA服务会自动在通讯录中查找匹配的好友。

正确做法：

• 用户说"给Charlie发消息" → 直接使用

  "user": "Charlie"

  调用发送接口
• 用户说"给张三发消息" → 直接使用

  "user": "张三"

  调用发送接口

常见错误（务必避免）：

• ❌ 不要先调用任何接口查询联系人列表来获取wxid
• ❌ 不要因为没有完全匹配的名称就使用相似名称替代（如把"Charlie"换成"charry"）
• ❌ 不要假设必须知道微信号才能发送消息

RPA的

send_message

Long-Running Tasks & API Blocking — CRITICAL

The RPA service runs all automation tasks on the main thread. This means the HTTP server is completely unresponsive while a task is executing. This is NORMAL, not a bug.

Two very different states that look similar:

Connection refused

port not listening

Request hangs / times out

How to distinguish them in Python:

import socket, requests

def service_state():
    """Returns 'down', 'busy', or 'ready'."""
    s = socket.socket()
    s.settimeout(2)
    try:
        s.connect(('127.0.0.1', 9922))
        s.close()
    except ConnectionRefusedError:
        return 'down'   # Port not listening → service truly crashed
    except Exception:
        return 'down'
    finally:
        s.close()
    # Port is open, now try a quick HTTP check
    try:
        r = requests.get('http://127.0.0.1:9922/docs',
                         timeout=5, proxies={'http': None, 'https': None})
        return 'ready'
    except requests.exceptions.Timeout:
        return 'busy'   # Port open but HTTP hung → task in progress
    except Exception:
        return 'busy'

Expected wait times for common tasks (do NOT interrupt):

auto_config

Rules:

• NEVER kill or restart the service solely because an API call hangs or times out. Check the port first.
• Only restart if

  service_state()

  returns

  'down'

  (connection refused).
• If

  'busy'

  , wait and retry after the expected duration has passed. Inform the user that a task is in progress.
• If a task has been running longer than 15 minutes and the port is still open, only then should you ask the user whether to force-stop.

Error Handling

If an API returns

WECHAT_NOT_LOGGED_IN

http://127.0.0.1:9922/

6. Progressive Documentation (Agent Knowledge Base)

For complex tasks (auto-add friends, mass sending, moment posting, config schemas):

• Read

  docs/index.md

  first to discover available SOPs.
• Follow the specific

  docs/*.md

  file before calling related APIs.