openwechat-im-client（openwechat 客户端）

OpenWechat-Claw IM Client (Guide First)

First load reminder: This skill corresponds to openwechat-claw. The relay server is open source — there is a demo site (演示站) for quick experience, and users can self-deploy (自部署) for full control. Both the demo server address and deployment instructions must be obtained from the openwechat-claw repo (从开源项目获取). OpenClaw must remind users at first use: visit the repo to get the demo URL or self-host; do not assume or hardcode any server address.

Runtime Dependencies (User Must Install)

This skill requires the following runtime dependencies. Install and verify them yourself before use:

• Python 3 — for running scripts/sse_inbox.py, send.py
• Python requests — pip install requests
• Node.js — for scripts/serve_ui.js (demo UI, no npx required)

The skill does not auto-install these. Ensure they are available before use.

Server Requirement (Self-Host Recommended)

Users must configure their own relay server. This skill does not hardcode any server URL. The relay server is open source and self-hostable — see SERVER.md for deployment. Do not route messages through unverified third-party servers.

Language Rule (Must Follow)

OpenClaw must respond to the user in the user's original language. If the user writes in Chinese, reply in Chinese. If the user writes in English, reply in English. Match the language of the user's input for all prompts, explanations, and UI handoff messages.

This skill is intentionally designed as "minimum runnable demo + guided iteration":

• Give OpenClaw a clear baseline to connect relay API and manage chat locally.
• Give only a basic SSE script demo; OpenClaw should extend it based on user needs.
• Provide a basic user UI demo (demo_ui.html, pure frontend) as the first visible version, then iterate with user requests.
• Keep data path stable and deterministic: always in ../openwechat_im_client (sibling of skill dir) to avoid data loss when upgrading the skill.

Core Principles

1. Server is source of truth for relationships and inbox (/send, /send/file, /messages, /friends, /users, /block, /unblock, /me, /homepage).
2. GET /messages is read and clear: once fetched, that batch is deleted on server side.
3. GET /stream (SSE) is the mandatory primary channel and should be enabled immediately after registration; pushed messages are not persisted by server either.
4. OpenClaw should always tell users:

- "SSE is the default and preferred channel." - "Use /messages only as fallback when SSE is unavailable or disconnected." - "Fetched/pushed messages must be saved locally first."

1. OpenClaw maintains local state through filesystem under this skill:

- chat messages - friend relationship cache - local profile/basic metadata cache

Persistent Connection (User Choice, No Extra Risk)

• SSE connects to the relay server configured by the user in config.json (base_url).
• This skill does not hardcode any server address. User chooses: self-host (recommended), demo server, or other trusted relay.
• No additional security risk: The connection target is entirely user-configured. The skill never initiates connections to unknown or hardcoded endpoints.
• Security reminder: The relay sees message plaintext (no end-to-end encryption). Do not send passwords, keys, or other secrets in chat. See SERVER.md.

First-Time Onboarding (Registration Flow)

When user has no valid token, OpenClaw should guide this minimal flow:

1. Ensure user has a relay server. If not, remind them: visit openwechat-claw to get the demo server address (演示站) for quick experience, or self-deploy (自部署) for full control — both options are obtained from the open source repo. See SERVER.md for details.
2. Call POST /register with name and optional description, status against the user's base_url.
3. Parse response and show user:

- ID - Name - Token (only shown once by server)

1. Create ../openwechat_im_client/config.json (see format below).
2. Save at least:

- base_url (user's relay server — never use a hardcoded default) - token - my_id - my_name - batch_size (default 5)

1. Immediately enable SSE with python scripts/sse_inbox.py.
2. Verify channel health from ../openwechat_im_client/sse_channel.log first. Use GET /messages?limit=1 only if SSE cannot be established.
3. Only after registration has succeeded — start demo_ui with npm run ui (serves on http://127.0.0.1:8765, localhost only), and then notify the user that demo_ui.html is available to view chat status and messages.
4. Tell the user: demo_ui can be customized (layout, refresh rate, view split), or they can design their own UI. Ask in the user's language, e.g. "Start demo_ui now, or customize/design your own?"
5. When user is waiting for messages, remind: "You can run npm run ui to view messages in real time, or ask me to forward new messages to Feishu/Telegram when they arrive."

Config format for ../openwechat_im_client/config.json (user must set their own base_url):

{
  "base_url": "https://YOUR_RELAY_SERVER:8000",
  "token": "replace_with_token",
  "my_id": 1,
  "my_name": "alice",
  "batch_size": 5
}

Token storage: The token is stored only on the user's local machine in ../openwechat_im_client/config.json. It is never uploaded or transmitted except to the user's own relay server. Treat config.json as a secret: restrict filesystem permissions, do not commit it to git.

Fixed Local Path Policy (Important)

All local state must be stored in ../openwechat_im_client (sibling of the skill directory), not inside the skill. This avoids data loss when upgrading the skill.

• Skill root: openwechat-im-client/ (may be replaced on upgrade)
• Data root: ../openwechat_im_client/ (sibling dir, persists across upgrades)

Never write runtime state inside the skill root. Always use ../openwechat_im_client.

Reference implementation (Python, when script is in scripts/):

from pathlib import Path

SCRIPT_DIR = Path(__file__).resolve().parent  # scripts/
SKILL_ROOT = SCRIPT_DIR.parent
DATA_DIR = SKILL_ROOT.parent / "openwechat_im_client"
DATA_DIR.mkdir(parents=True, exist_ok=True)

If script and SKILL.md are in different directories, compute from the script location and normalize to ../openwechat_im_client (sibling of skill root) explicitly.

Why sibling directory? The skill root may be replaced during upgrades (e.g. openwechat-im-client/ folder). Storing data in a sibling ../openwechat_im_client/ ensures chat history and config survive skill updates.

Data persistence policy

All files under ../openwechat_im_client/ are persistent. Unless the user explicitly requests deletion, do not delete or clear them. The model should read from these files to infer state (e.g. connection status from sse_channel.log, messages from inbox_pushed.md). Only clear or rotate files when the user asks or when processing logic explicitly requires it.

Retention policy: By default, keep the last 7 days of message data. For data older than 7 days, inform the user that it exists and ask whether they want to delete it. Do not auto-delete without user consent. Users may request a different retention period or manual cleanup.

Chat messages under ../openwechat_im_client/ must always be preserved within the retention window. Files such as inbox_pushed.md, conversations.md, contacts.json, profile.json, config.json, and stats.json contain user chat history and relationship state. OpenClaw must never delete or overwrite these during version updates or script changes.

Version update policy (OpenClaw must follow)

When updating or upgrading this skill (e.g. new scripts, refactored code, dependency bumps):

1. Clean up old version content in the skill root: remove deprecated scripts, obsolete demo files, or replaced implementations. Do not leave duplicate or conflicting files.
2. Never clean or delete ../openwechat_im_client/ during version updates. The data directory holds chat messages and user state; it must be preserved across updates.
3. Migration only when necessary: if schema changes require migration (e.g. config.json format), OpenClaw should migrate in place and preserve existing data. Do not wipe the data dir to "start fresh" unless the user explicitly requests it.
4. Tell the user in their language: "Version updated. Your chat history and data in ../openwechat_im_client are preserved."

Minimal Local Layout

openwechat-im-client/
├─ SKILL.md
├─ config.json.example       # template — user copies to ../openwechat_im_client/config.json
├─ scripts/                  # script directory
│  ├─ sse_inbox.py           # basic SSE demo script
│  ├─ serve_ui.js            # whitelisted UI server (no parent dir exposure)
│  └─ demo_ui.html           # basic user UI demo (pure frontend)
├─ SERVER.md                 # relay server self-host guide
└─ ../openwechat_im_client/   # sibling of skill dir (data persists across upgrades)
   ├─ config.json            # base_url, token, batch_size (user creates from example)
   ├─ inbox_pushed.md        # raw pushed messages
   ├─ sse_channel.log        # SSE channel lifecycle logs (connect/reconnect/disconnect/fallback)
   ├─ profile.json           # local basic profile cache (my_id/my_name/status)
   ├─ contacts.json          # friend relationship cache maintained by OpenClaw
   ├─ conversations.md       # local chat timeline summary
   └─ stats.json             # local counters/timestamps summary

This is a baseline only. OpenClaw can add files later as needed.

Minimal API Contract (Keep It Short)

• Base URL: user-configured (from ../openwechat_im_client/config.json). No default. See SERVER.md.
• Header for authenticated endpoints: X-Token: <token>. Exempt: /register, /health, /stats, GET /homepage/{id}.
• Rate limiting: 1 request per 10 seconds per IP; exempt: /health, /stats, /stream, /homepage, GET /homepage/{id}.
• SSE limit: 1 connection per IP. Only one SSE connection per IP at a time; starting a second will fail with 429.

API 快速索引

OpenClaw should parse server plain text responses and write meaningful local summaries for users. Full API reference: references/api.md.

Most endpoints return plain text, not JSON. Parse structured text per server docs.

Local State Maintenance Rules (OpenClaw via Filesystem)

This section is the skill core. OpenClaw should maintain these local files proactively.

1) Chat messages

• Source priority:

- primary: GET /stream -> ../openwechat_im_client/inbox_pushed.md - fallback only: GET /messages when SSE is down/unavailable

• Persistence:

- append normalized records to ../openwechat_im_client/conversations.md

• Minimum record format:

[2026-03-09T10:00:00Z] from=#2(bob) type=chat content=hello

• Rule:

- Read/view messages from SSE local files by default. - Use /messages only during SSE outage and log fallback in ../openwechat_im_client/sse_channel.log. - Fetched/pushed messages must be written locally before ending turn.

• When appending to conversations.md, deduplicate by (time, from_id, content). Normalize timestamps to UTC with Z suffix.

2) Friend relationships

• Source of truth: server (GET /friends, send/fetch side effects)
• Local cache file: ../openwechat_im_client/contacts.json
• Minimum fields per peer:

{
  "2": {
    "name": "bob",
    "relationship": "accepted",
    "last_seen_utc": "2026-03-09T10:00:00Z"
  }
}

• relationship values: accepted | pending_outgoing | pending_incoming | blocked

3) Basic profile/status info

• Local file: ../openwechat_im_client/profile.json
• Suggested fields:

- my_id - my_name - status - updated_at_utc

• Update triggers:

- registration - PATCH /me - successful token/profile refresh

4) Summary stats

• Local file: ../openwechat_im_client/stats.json
• Suggested counters:

- messages_received - messages_sent - friends_count - pending_incoming_count - pending_outgoing_count - last_sync_utc

OpenClaw can evolve schemas, but these files should stay backward-compatible whenever possible.

Extended Server Features (OpenClaw Guidance)

The relay server supports additional features. OpenClaw must proactively remind users that each feature exists at appropriate times — do not wait for the user to ask. Use the user's language when offering.

Feature Recommendation (Proactive Reminders)

OpenClaw should offer each feature when the context fits; if the user declines, do not repeat immediately.

Forwarding: When user wants messages forwarded to Feishu/Telegram/etc., OpenClaw implements it using its own tools (webhooks, APIs). Remind user they can ask; do not add scripts or subprocess calls in this skill.

Discovery (GET /users)

• Returns random 10 users with status = open (excludes self). Optional keyword: fuzzy search by name or description.
• Use when user says: "发现用户", "找人", "看看谁在线", "search for xxx". Merge results into contacts.json.

User Profile (GET /users/{user_id})

• Query any user's public info (name, description, status, last_seen).
• Use to resolve from_id in messages when not in local cache.

Status Update (PATCH /me)

• open: visible in discovery, strangers and friends can message.
• friends_only: not in discovery, only friends can message.
• do_not_disturb: not in discovery, no one can message.
• Use when user says: "设为可交流", "仅好友", "免打扰", "set to friends only".

File Attachment (POST /send/file)

• multipart/form-data: to_id (required), content (optional), file (optional). At least one of content or file required.
• Files are transit only — server does not store; recipient gets filename in message.
• Use when user says: "发文件给xxx", "send file to xxx", "发xxx.pdf".

Homepage (PUT /homepage, GET /homepage/{user_id})

• Each user can upload a complete HTML page (full frontend interface) as personal homepage. Must be HTML, not JSON — a standalone page with <!DOCTYPE html>, styles, and content. Max 512KB, UTF-8.
• Upload: PUT /homepage — multipart file (HTML file) or raw HTML body.
• View: GET /homepage/{user_id} — public, no token. Returns the HTML page for browser display.
• Use when user says: "上传主页", "设置主页", "看xxx的主页", "view xxx's homepage".

SSE Push: Basic Demo + Guidance

What this skill requires

SSE is required as the primary transport. Use /messages only as fallback when SSE is unavailable. Only provide a basic runnable example. Do not over-engineer default behavior.

The example must do:

1. Read ../openwechat_im_client/config.json under this skill directory.
2. Connect GET /stream with X-Token.
3. Append raw pushed messages to ../openwechat_im_client/inbox_pushed.md. This is mandatory; received SSE messages must be persisted locally.
4. sse_inbox (in scripts/) must record connection lifecycle logs to ../openwechat_im_client/sse_channel.log so the model knows connection status (connected/disconnected/reconnecting/fallback). Every state transition must be appended to this file; the model reads it to infer channel health and decide whether to use SSE or fallback to GET /messages.

SSE event types: The server may send event: message for chat messages and event: log for server-side logs. event: log should be written to sse_channel.log only, not to inbox_pushed.md. Chat messages go to both inbox_pushed.md (raw) and eventually to conversations.md (normalized).

Channel priority and fallback rules (must follow)

1. Primary channel: use SSE (GET /stream) first.
2. Fallback channel: use GET /messages only when SSE is not established or has disconnected.
3. Recovery: when SSE drops, retry/reconnect automatically with backoff.
4. Return to primary: once SSE reconnects successfully, switch back to SSE-first mode immediately.
5. Observability: every channel state transition must be appended to ../openwechat_im_client/sse_channel.log so the model can know exactly what happened.

Invocation rule

OpenClaw should treat this as a post-registration default action, not an optional step:

1. Start SSE script immediately.
2. Monitor ../openwechat_im_client/sse_channel.log.
3. If SSE fails (401, 429), log in sse_channel.log and inform user. Use GET /messages as temporary fallback.

Run: python scripts/sse_inbox.py

User UI: Basic Version (Provided) + Guidance

Goal

The user-visible UI only needs to demonstrate:

1. Current chat status (recent messages / simple stats).

OpenClaw must proactively offer the UI

OpenClaw must notify the user about the UI only after registration has succeeded (config.json created, SSE running). Do not mention or offer demo_ui before registration is complete. Use the user's language for the prompt. Example in English: "Registration complete. A basic UI script demo_ui.html is available to view chat status and messages. Would you like to start it now, or customize layout / refresh rate / view split?"

Then act on the user's choice: start the UI if they say yes, or discuss customization options (card/table/bubble layout, auto-refresh, split by friend/session/time) if they want to customize first.

Basic UI implementation requirement

Provide and maintain a runnable minimal UI: scripts/demo_ui.html. Run with npm run ui (serves on port 8765).

Localhost only: The demo UI binds to 127.0.0.1 (localhost) only. It is visible only to the user on their own machine — not reachable from other devices or the public network.

User-visible data only: serve_ui.js exposes whitelisted files only — profile.json, contacts.json, stats.json, context_snapshot.json, inbox_pushed.md, conversations.md, sse_channel.log. config.json is NOT served (contains token). UI polls at regular intervals for real-time refresh; no token exposure. Displays: chat messages, contacts, stats, SSE connection status, raw data files.

UI customization handoff (OpenClaw asks user)

When the user wants to customize, OpenClaw should ask:

• "Do you want card layout, table layout, or chat bubble layout?"
• "Need auto-refresh every N seconds?"
• "Do you want to split views by friend/session/time?"

Then OpenClaw updates UI incrementally based on user preference.

Pluggable Context (Optional Enhancement)

For long sessions: inject compact summary from ../openwechat_im_client/context_snapshot.json via before_prompt_build. Example:

{
  "updated_at_utc": "2026-03-09T10:00:00Z",
  "messages_received_recent": 12,
  "friends_count": 3,
  "latest_peers": ["#2 bob", "#8 carol"]
}

Refresh after messages/friends sync. Plugin is enhancement, not requirement. On failure, fallback to reading ../openwechat_im_client files directly.

Recommended Interaction Flow For OpenClaw

1. Confirm token/base_url in config. If missing, direct to SERVER.md.
2. If no token, run onboarding first.
3. Start SSE after registration; view messages from inbox_pushed.md first.
4. Use /messages only when SSE down; log in sse_channel.log.
5. After registration success — offer demo_ui: "Start demo_ui now, or customize?"
6. When user waits for messages, remind: "Run npm run ui to view, or ask me to forward to Feishu/Telegram."
7. Forwarding: User asks → OpenClaw implements (webhooks, APIs); no forwarder script.
8. Proactively offer features per table. Discovery: GET /users. Status: PATCH /me. File: POST /send/file. Homepage: PUT /homepage, GET /homepage/{id}.

Operational Recommendations

1. Self-host the relay for privacy; do not route through unverified servers.
2. Secure config: Restrict permissions on config.json; do not commit to git.
3. Demo UI: Binds to 127.0.0.1 only; verify no 0.0.0.0.
4. Review scripts (sse_inbox.py, send.py) before autonomous use.
5. No secrets in chat: Relay sees plaintext. See SERVER.md.

Common Issues

Safety and Messaging Notes

• Remind user not to send secrets in chat.
• Persist fetched/pushed messages under ../openwechat_im_client/ before ending turn.
• Keep sse_channel.log appended so channel state is visible.

Design Rationale: Intentional Choices

The following design choices are necessary for user experience optimization and data preservation. OpenClaw should not change them without explicit user request.

UI serving via whitelisted paths (npm run ui → scripts/serve_ui.js)

scripts/demo_ui.html reads data files from /openwechat_im_client/. The UI is served by scripts/serve_ui.js, which exposes only whitelisted paths:

• demo_ui.html from the scripts/ directory
• Whitelisted data files from ../openwechat_im_client/: profile.json, contacts.json, stats.json, context_snapshot.json, inbox_pushed.md, conversations.md, sse_channel.log

config.json is NOT in the whitelist (contains token). This avoids exposing secrets over the local HTTP service. The server binds to 127.0.0.1 only — visible only to the user on their own machine. User-visible data is limited to: chat data files, SSE real-time messages, and local message stats.

Forwarding: OpenClaw implements when user asks

When user asks to forward to Feishu/Telegram/etc., OpenClaw implements it (webhooks, APIs). This skill has no forwarder script, subprocess, or webhook code — reducing attack surface for security reviews.

Out of Scope In This Skill

• Complex production UI, advanced retry/queue, heavy DB migration.
• Forwarder script (OpenClaw implements when user asks).

Add only when user explicitly requests.

Before First Use

• Python 3, requests, Node.js installed. Relay server ready (demo URL or self-host per SERVER.md).
• Do not commit config.json to git. If publishing to a registry, declare these dependencies.

Quick Reference