OpenClaw WeChat Article Workflow

This skill turns raw material into a WeChat Official Account draft. It is designed for agents that must execute the whole pipeline with minimal setup.

Required Inputs

Ask for missing items only when they cannot be inferred:

• Article material: topic, links, notes, transcript, PDF, GitHub repo, product brief, or existing draft.
• Intended output: draft only, final Markdown only, or both.
• WeChat account credentials, supplied through environment variables or a local .env file.
• Confirmation that the API-observed public IPv4 is in the WeChat Official Account IP allowlist if publishing to draft.
• Desired writing depth: direct/practical, normal commentary, or deep reflective essay. Default to direct/practical for tool/project recommendation articles unless the user explicitly asks for deeper analysis.

First-Time Publishing Setup

When this skill is used for publishing and no valid .env exists, run this setup flow before draft publication:

1. Ask the user for:
   - WECHAT_APP_ID
   - WECHAT_APP_SECRET, also called "开发密钥 / AppSecret" in the WeChat backend. Some users may call this the "password"; treat it as a secret.
   - WECHAT_AUTHOR, optional.
2. Show the current public IPv4 to the user:

curl -4 ifconfig.me

3. Tell the user to add that IP to the WeChat Official Account IP allowlist. If WeChat later returns 40164, use the IP shown in WeChat's error message as the authoritative API-observed IP; it can differ from generic IP lookup results because of proxy, carrier, VPN, NAT, or platform routing. Use these current navigation steps:
   - Open https://developers.weixin.qq.com/platform and scan to log in.
   - Go to 我的业务与服务 -> 公众号 / 服务号, then choose the target account.
   - Find 基础信息 -> 开发密钥.
   - Enable / reset / freeze AppSecret as needed.
   - Add the public IPv4 shown by the agent to the IP allowlist.
4. Create .env in WECHAT_ARTICLE_DIR using .env.example.
5. Run a small dry-run before attempting draft publication:

python3 /path/to/openclaw-wechat-article-workflow/scripts/publish_wechat_draft.py \
  --markdown article.md \
  --meta article.meta.json \
  --env .env \
  --dry-run

Dry-run validates local files only. The real API check happens during publish. Use scripts/publish_wechat_draft.py as the source of truth because it fetches access tokens with the stable cgi-bin/stable_token endpoint first, then falls back to old cgi-bin/token only when appropriate. If publication returns 40164, add the IP shown in WeChat's error message and retry with the same script before asking for new credentials.

Minimal Configuration

Use .env.example as the template. Do not hardcode secrets in the skill or article files.

Required for draft publication:

WECHAT_APP_ID=...
WECHAT_APP_SECRET=...
WECHAT_AUTHOR=...
WECHAT_ARTICLE_DIR=/root/.openclaw/workspace/wechat-articles
WECHAT_DEFAULT_COVER=cover.png

Before publishing, verify the server's public IPv4:

curl -4 ifconfig.me

That IP must be added in:

微信公众平台 -> 设置与开发 -> 基本配置 -> IP 白名单

If the API returns 40164, treat the IP in the WeChat error message as authoritative. Do not keep retrying the old token endpoint manually; the bundled script uses cgi-bin/stable_token first.

Deliverables

For every article task, produce these artifacts in WECHAT_ARTICLE_DIR:

• article.md: final Markdown, with relative image paths only.
• imgs/: local images used by the article.
• article.meta.json: title, digest, author, cover image, source URLs, and publish status.
• quality-report.md: writing and publication checks.
• If publishing succeeds, record the draft media_id in article.meta.json.

End-to-End Procedure

1. Intake

Identify the article type and source material.

Supported inputs:

• Topic or rough idea.
• Links, news, GitHub repo, product page, PDF, transcript, screenshots.
• Existing draft for rewriting or continuation.

If material is too thin, ask for:

• Main point the user wants to express.
• Personal experience or emotional reaction.
• Intended article type: investigation, product experience, phenomenon analysis, tool sharing, or methodology.

2. Topic Judgment

Score the topic with HKR:

• H, Happy: curiosity, tension, or click appeal.
• K, Knowledge: new information or useful insight.
• R, Resonance: emotional recognition.

If fewer than two dimensions are strong, propose a sharper angle before drafting.

3. Research And Fact Checking

Verify concrete facts before writing.

For GitHub projects, use GitHub API for stars, forks, repo metadata, and images. Do not rely on rendered GitHub pages for counts.

curl -s "https://api.github.com/repos/USER/REPO" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('stars:', d['stargazers_count'], 'forks:', d['forks_count'])"

For current products, model names, prices, dates, or policies, verify from primary sources where possible. Mark uncertainty instead of inventing.

4. Choose Article Archetype

Pick one primary archetype:

• Investigation: the author personally tries something and reports the process.
• Product experience: the author uses a product with the reader.
• Phenomenon analysis: a concrete phenomenon leads to layered interpretation.
• Tool sharing: a useful tool is wrapped in a personal discovery story.
• Methodology: accumulated experience becomes actionable steps.

The archetype determines the structure and what evidence is needed.

5. Draft In Khazix Style

Write as "a knowledgeable ordinary person seriously talking about something that moved him."

Before drafting, choose the depth:

• Direct/practical: state the core point quickly, then explain what it does, who should use it, how to use it, and what to watch out for. Do not add philosophy, industry reflection, or broad cultural interpretation.
• Normal commentary: add light judgment and context, but keep the article anchored to the practical topic.
• Deep reflective essay: use cultural, historical, philosophical, or industry extension only when the user asks for it or the topic clearly needs it.

For GitHub tool/project recommendations, default to direct/practical unless the user asks for a deeper essay. Example: if the core point is "视频号终于能在 PC 端直接点击下载了", keep the article centered on that claim.

Core rules:

• Start from a concrete event, scene, strange fact, or curiosity.
• Avoid grand opening claims.
• Use short paragraphs and alternating sentence lengths.
• Use conversational transitions.
• Use real details, people, scenes, and personal judgment.
• Avoid unnecessary Markdown headings unless the article is explicitly a numbered methodology.
• Avoid report-like bullet lists in the main article.

Hard avoids:

• Empty phrases such as "本质上", "不可否认", "综上所述", "首先/其次/最后".
• Title emoji.
• Citation dump at the end.
• Fake first-person experience.

See references/writing-style.md for the full writing checklist.

6. Plan And Insert Images

Images are planned during writing, not pasted at the end.

Create:

mkdir -p "$WECHAT_ARTICLE_DIR/imgs"

Use relative paths only:

![image description](imgs/example.png)

Placement rules:

• Overview screenshot after the introduction of the product/project.
• Feature screenshot near the feature paragraph.
• Data screenshot near the data paragraph.
• Configuration screenshot near setup instructions.
• CLI screenshot near command explanation.

Do not use absolute paths in Markdown.

7. Render And Publish Draft

Use scripts/publish_wechat_draft.py from this skill.

Recommended command:

cd "$WECHAT_ARTICLE_DIR"
python3 /path/to/openclaw-wechat-article-workflow/scripts/publish_wechat_draft.py \
  --markdown article.md \
  --meta article.meta.json \
  --env .env

The script performs:

• Load config from env and .env.
• Fetch WeChat access_token with stable cgi-bin/stable_token first, falling back to old cgi-bin/token only when the stable endpoint fails for a non-IP reason.
• Convert Markdown to HTML.
• Upload local body images with media/uploadimg.
• Replace local image paths with mmbiz.qpic.cn URLs.
• Upload cover with permanent material API to get fresh thumb_media_id.
• Call draft/add.
• Write the resulting draft media_id to metadata.

If wenyan or another renderer is available and required by the local publishing style, render Markdown to HTML before calling the script with --html.

8. Quality Gate

Before reporting completion, run these checks:

• article.md exists.
• Every image path is relative and points to an existing file.
• No body image URL is non-WeChat after publication.
• Cover image exists and was freshly uploaded.
• article.meta.json contains title, digest, author, cover, and draft media_id if published.
• GitHub or product facts were verified.
• Writing passed the four-layer quality check in references/quality-gate.md.

9. Troubleshooting

Use references/troubleshooting.md for API failures. Common causes:

• 40164: API-observed public IP is not in the WeChat IP allowlist, or the old token endpoint is being used. Use the bundled script, which prefers cgi-bin/stable_token, and add the IP from WeChat's error message.
• 40013: invalid AppID.
• 40001 / token error: wrong AppSecret, stale credential, or account mismatch.
• 40007: stale or invalid thumb_media_id; upload a fresh cover.
• Body images blank after publication: used media/upload or external URLs instead of media/uploadimg.
• Wrong article published: --markdown, MD_FILE, or metadata points to an old article.

Migration Notes

For a new VPS:

1. Install OpenClaw and Python dependencies.
2. Restore memory, skills, workspace files, and channel config.
3. Place this skill directory under the agent's skills directory.
4. Copy .env.example to .env in WECHAT_ARTICLE_DIR and fill credentials.
5. Add the new VPS public IPv4 to WeChat IP allowlist.
6. Run the script with a small test article and check WeChat draft box.

When moving between machines, repeat the IP allowlist step. The AppID/AppSecret can stay the same, but the allowed public IP must match the machine that calls WeChat APIs.