md2wechat-skill FAQ

This page does one thing only: it explains the most common issues in a fast symptom -> cause -> fix format.

If you have not started installation yet, begin with:

Symptom 1: command not found: md2wechat

Cause

The skill was installed, but the CLI was not, or PATH was not refreshed.

Fix

npm install -g @geekjourneyx/md2wechat
md2wechat version --json

If you prefer Homebrew, you can also use:

brew install geekjourneyx/tap/md2wechat
md2wechat version --json

If you installed through install.sh, also run:

export PATH="$HOME/.local/bin:$PATH"

Symptom 2: npx skills add succeeded, but the agent still cannot use the tool

Cause

npx skills add installs only the skill, not the runtime.

Fix

Check:

command -v md2wechat
md2wechat version --json

If the first command prints nothing, the CLI is still not available.

Symptom 3: why did it default to API mode?

Cause

Because md2wechat convert defaults to API mode.

Fix

If you want AI mode explicitly:

md2wechat convert article.md --mode ai --theme autumn-warm

Symptom 4: why did AI mode not return final HTML?

Cause

AI mode is designed to return structured output for a second model step. It is not the same as direct API-to-HTML conversion.

Fix strategy

• use API mode when you want stable direct HTML output
• use --mode ai when you want the themed AI workflow

Symptom 5: Claudian cannot find the command, but Terminal can

Cause

Obsidian GUI processes often inherit a different PATH than Terminal.

Fix

In Claudian:

• Settings
• Environment
• Custom variables

Add the CLI directory, for example:

PATH=/Users/your-name/.local/bin:existing-path

Symptom 6: OpenClaw still fails after installation

Cause

OpenClaw requires both the skill shell and the CLI in PATH.

Fix

Check both:

ls ~/.openclaw/skills/md2wechat/
command -v md2wechat

Both sides must be healthy.

Symptom 7: the agent does not know which themes or providers are available

Cause

Discovery was skipped.

Fix

Run:

md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --kind image --json

Symptom 8: draft creation fails

Common causes

• missing WeChat AppID
• missing WeChat Secret
• missing md2wechat.cn API key for API mode
• missing cover image

Fix direction

Confirm that you already have:

• WeChat AppID
• WeChat Secret
• API key
• a valid cover image such as cover.jpg

Symptom 9: Volcengine returns ModelNotOpen

Cause

The account has not enabled the required Seedream model. This is usually not a prompt problem.

Fix

Start here:

• Volcengine Doubao

Then:

1. open the console
2. go to the enablement area
3. enable Seedream

Then retry with:

md2wechat providers show volcengine --json
md2wechat generate_image --size 2K "clean editorial cover, 16:9 landscape"

Symptom 10: I do not know which models Volcengine supports

Cause

The model name was guessed from memory instead of checked through provider discovery.

Fix

Run:

md2wechat providers show volcengine --json

If you also want to confirm the current config has switched to the domestic model path, add:

md2wechat config show --format json

Where should you go next?

• for the main onboarding path: md2wechat-skill
• for validation order and best practices: md2wechat-skill Guide
• for runtime-specific pages: Coding Agents, Claudian, OpenClaw