Setup and Troubleshooting

The easiest way to waste time on a first md2wechat setup is not hard commands. It is a messy order.

This page does one thing:

it puts installation, validation, discovery, and troubleshooting into one clean path.

Step 1: get the CLI installed first

The order is straightforward:

1. use Homebrew first on macOS
2. use npm if you already live in Node/npm
3. use go install if you already live in Go
4. use the fixed release installer otherwise

Start with:

• Quickstart
• md2wechat-skill Guide

Step 2: do not stop at version

Do not stop after version.

A safer validation sequence is:

md2wechat version --json
md2wechat config init
md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json

This reveals early:

• whether the CLI actually runs
• whether config can be initialized
• whether the runtime is exposing the key capabilities

Step 3: start with preview only

Do not start with draft creation.

Start with:

md2wechat inspect article.md
md2wechat preview article.md
md2wechat convert article.md --preview

Get the conversion path working first. Only then move to images, drafts, and WeChat credentials.

Step 4: troubleshoot by layer

Command not found

Check:

command -v md2wechat

Runtime feels incomplete

Check:

md2wechat capabilities --json

Image-related failures

Check:

md2wechat providers list --json
md2wechat providers show volcengine --json

Advanced layout does not render

Check:

md2wechat layout list --json
md2wechat layout validate --file article.md --json

Draft creation fails

Go back to WeChat credentials, cover image, and the current mode choice.

Step 5: use the environment page when the problem is environment-specific

If you already know the problem belongs to one runtime, do not stay in the general docs:

• Claude Code
• Codex
• OpenCode
• Claudian
• OpenClaw

The shortest troubleshooting order

If you only remember one thing, remember this:

1. confirm the command exists
2. confirm the capability surface is exposed
3. confirm the current provider, theme, or layout object exists
4. only then blame the body content, prompt, or endpoint

Continue with

• md2wechat-skill FAQ
• Discovery-First Workflow
• Advanced Layout Mistakes