---

name: "微信公众平台开发" version: "2.0.0" description: "微信公众号/小程序 API 工具与实战避坑手册。Use for: (1) 用附带的零依赖 CLI 直接调公众号 API——取 token、传素材、建草稿、发布文章，(2) 排查 40164/45009 等真实高频错误，(3) 公众号接入/OAuth/JSSDK/支付 V3 开发指导。WeChat Official Account API CLI (zero-dependency) plus a battle-tested pitfall guide for token, media, draft and publishing workflows." tags: ["wechat", "weixin", "official-account", "miniprogram", "api", "cli"] author: "ClawSkills Team" category: "social"

微信公众平台开发 Skill

不止讲"微信开发是什么"——本 skill 附带一个零依赖命令行工具 （scripts/wxoa.py，仅 Python 标准库），让 agent 直接替用户完成 公众号内容发布全链路：取 token → 传封面 → 建草稿 → 发布 → 查发表记录。 另附一份真实生产环境踩坑清单（每一条都来自实际运营公众号的事故复盘）。

快速开始

export WX_APPID=wx开头的AppID
export WX_SECRET=公众号AppSecret

python3 scripts/wxoa.py token                        # 验证凭证
python3 scripts/wxoa.py call /cgi-bin/get_api_domain_ip   # 冒烟测试

脚本行为声明：仅请求 api.weixin.qq.com；本地只写一个 token 缓存文件 （系统临时目录，7000 秒过期），不读写其他文件。

命令手册

发一篇文章的完整流程

python3 scripts/wxoa.py upload-thumb cover.jpg
# → {"media_id": "MEDIA_ID", "url": "..."}
python3 scripts/wxoa.py draft-add "文章标题" article.html MEDIA_ID "作者名" "摘要"
# → {"media_id": "DRAFT_MEDIA_ID"}
python3 scripts/wxoa.py publish DRAFT_MEDIA_ID
# → {"publish_id": "..."}（异步，稍后用 published 查结果）

call 兜底示例（脚本未封装的接口都能调）：

python3 scripts/wxoa.py call /cgi-bin/menu/get
python3 scripts/wxoa.py call /cgi-bin/user/get
python3 scripts/wxoa.py call /cgi-bin/message/template/send '{"touser":"OPENID","template_id":"...","data":{}}'

实战踩坑清单（生产事故复盘）

1. 40164 = IP 不在白名单。公众号后台"IP白名单"只认配置过的服务器 出口 IP。本地开发机直接调 token 必挂——要么把出口 IP 加白名单， 要么经已加白的服务器中转。
2. 45009 = 接口日配额耗尽。draft/freepublish 等接口有每日调用上限， 耗尽后当天无解，次日 0 点重置。批量操作前先估算次数，脚本里 不要对 45009 做无脑重试。
3. access_token 全局唯一。任何一端刷新 token 会使旧 token 失效—— 本脚本做了本地缓存，但若线上服务也在刷 token，两边会互相挤掉线。 生产环境必须中心化缓存（Redis 等），临时脚本操作尽量复用线上缓存。
4. 发表记录里的标题会被截断。用标题反查已发表文章时必须做 子串匹配，完整标题 == 匹配会漏。freepublish/batchget 也只能 拉最近的记录，历史全量要自己本地存档。
5. 推草稿前先去重。同名文章已在草稿箱或已发表时重复 push 会造成 重复群发风险，push 前先查 drafts + published 双向子串匹配。
6. author 字段为空时部分第三方工具会跳过署名，导致历史旧笔名残留。 建草稿时显式传作者名。
7. 平台会判定"低创作度内容"。纯 AI 生成、排比堆砌、无真实锚点的 文章可能被限流。发布前自查：有无真实数据/引用/具体案例。
8. 封面必须独立生成。公众号封面比例 900×383，从 16:9 头图硬裁 必丢内容。

开发知识速查

服务器接入验证

# GET 回调: sha1(sorted([token, timestamp, nonce])) == signature 则原样返回 echostr
tmp = ''.join(sorted([token, timestamp, nonce]))
ok = hashlib.sha1(tmp.encode()).hexdigest() == signature

网页授权 OAuth2.0（三步）

1. 跳 open.weixin.qq.com/connect/oauth2/authorize（scope=snsapi_base 静默拿 openid / snsapi_userinfo 弹窗拿资料）
2. code 换 token：/sns/oauth2/access_token
3. 拉用户信息：/sns/userinfo（此 token 与全局 access_token 是两回事）

小程序登录

wx.login() 取 code → 服务端 /sns/jscode2session 换 openid+session_key → 生成自定义登录态。session_key 绝不下发前端。

JSSDK 签名

sha1("jsapi_ticket=T&noncestr=N&timestamp=TS&url=U")，url 取 # 前部分。 jsapi_ticket 用全局 access_token 换取，同样需要中心化缓存。

支付 V3 要点

• 域名 api.mch.weixin.qq.com，JSON + SHA256withRSA 商户私钥签名
• 回调必须验签 + AES-256-GCM 解密 + 幂等处理（微信会重复通知）
• 商户私钥/APIv3 密钥绝不进版本库

API 域名速查

本 skill 不做什么

• 不提供绕过微信审核、风控或反自动化机制的方法
• 不含个人微信号（非公众平台）自动化——那是封号高危区
• 群发、模板消息等触达用户的写操作，agent 必须先向用户确认再执行
• 企业微信深度集成建议用专门的 wework skill