WeChat IP Whitelist

When it is required

Only WeChat side-effect APIs (material upload, draft creation, image posts) check the caller IP against the platform whitelist. The Convert API is not a WeChat side effect and never needs a whitelist.

The typical error

ip xxx.xxx.xxx.xxx not in whitelist

Add your egress IP

1. Find the egress IP of the machine that runs the CLI:

curl ifconfig.me

2. Add that IP in the WeChat MP platform under 开发接口管理 → IP 白名单.
3. Wait 1-5 minutes for the change to take effect.

Dynamic IPs and CI

• Home and office broadband often rotate public IPs; an entry that works today may fail tomorrow.
• CI runners (for example GitHub Actions) get a new egress range per run and cannot rely on a static whitelist entry.

Fixed egress proxy (paid)

Configure a fixed egress so every WeChat side-effect call leaves from one stable IP:

wechat:
  proxy_url: http://user:pass@host:port

• Also settable as WECHAT_PROXY_URL; only http/https schemes, port 1-65535.
• The proxy applies only to WeChat side effects (upload, draft add, newspic). It does not affect the Convert API, image providers, discovery, or preview.
• Proxy mode requires a valid MD2WECHAT_API_KEY, validated via HEAD /api/auth/validate before any side effect.
• md2wechat config show always masks the proxy password.

Related

• Auth
• Publishing API
• Multi-Account Publishing