跳到主要内容
在线编辑器申请接入

FAQ / 排障 / FIELD NOTES

md2wechat FAQ：新手最常见问题、排查顺序与最短解决路径

这篇 FAQ 不讲泛泛概念，只讲新手最容易卡住的地方，以及每个问题最短应该先执行哪几条命令。

极客杰尼12 分钟阅读

这篇 FAQ 只做一件事：

帮你用最快路径排掉新手最常见的问题。

它提炼 md2wechat-skill 仓库里最常见、最值得先看的核心问题，方便你在博客里快速定位。

如果你需要完整原文和所有细节，建议直接去：

同时建议优先配合这些官方文档一起看：

  • /docs/md2wechat
  • /docs/md2wechat.md
  • /docs/md2wechat/skill.md
  • README.md
  • docs/CONFIG-WALKTHROUGH.md
  • docs/WECHAT-CREDENTIALS.md

一、安装与启动：最常见的 4 个问题

Q1：提示 command not found: md2wechat

这几乎是新手第一高频问题，本质上只有一个原因：

CLI 不在 PATH 里，或者根本没装好。

先别猜路径，先跑：

command -v md2wechat
md2wechat --help

如果 command -v 没输出，说明系统当前找不到它。

推荐处理顺序

方案 A：通过 npm 重新安装

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

如果 npm 使用了公司镜像或本地镜像，遇到 404 时先切回官方源：

npm install -g @geekjourneyx/md2wechat --registry=https://registry.npmjs.org/

安装细节以 GitHub README 为准。站内手册只推荐 npm 这一条主路径，避免新手在多种安装方式之间来回切换。

方案 B：确认 npm 全局 bin 在 PATH 里

npm bin -g
command -v md2wechat

如果 npm bin -g 所在目录不在 PATH 里，把它加进去后再验证：

md2wechat version --json

如果你根本不确定装到了哪里，最稳的方法是直接重新走安装流程。

Q2：OpenClaw / Claude Code 装了 skill，但命令还是跑不起来

这里最容易误解的一点是：

装 skill 不等于装 CLI。

你要先分清两条路径：

  • skills/md2wechat/：给 Claude Code / Codex / OpenCode 的 coding-agent skill
  • platforms/openclaw/md2wechat/：给 OpenClaw / ClawHub 的专用 skill

无论哪条路径，如果 PATH 里没有 md2wechat，skill 本身也没法凭空执行命令。

Claude Code / Codex 路径建议

先装 md2wechat，再装 skill：

npm install -g @geekjourneyx/md2wechat
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat
md2wechat version --json
md2wechat capabilities --json

OpenClaw 路径建议

如果你走 OpenClaw，也先确认本机 md2wechat 命令可用，再安装 OpenClaw 专用 skill：

npm install -g @geekjourneyx/md2wechat
md2wechat version --json
md2wechat config init
md2wechat config validate
md2wechat capabilities --json

一个判断标准

如果下面这条命令不通：

command -v md2wechat

那问题优先一定在 CLI，不在 skill。

Q3：在 Obsidian 的 Claudian 里怎么用 /md2wechat？

这件事的顺序也不要搞反，先保证终端里能跑通：

npm install -g @geekjourneyx/md2wechat
md2wechat version --json
npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

然后再回到 Claudian：

  • 直接输入 /md2wechat
  • 或让 Agent 调用 md2wechat skill

如果终端里能跑，但 Claudian 里还是找不到，优先去：

  • Settings -> Environment -> Custom variables

补上你的 CLI 路径，例如：

PATH=~/.local/bin:原来的PATH

Q4：macOS 提示“无法打开，因为无法验证开发者”

这是 macOS 的系统安全提示，不是 md2wechat 独有问题。

可先试：

sudo xattr -cr /Applications/md2wechat

或者到系统设置里手动允许打开。

二、配置与默认行为：最容易搞混的 5 件事

Q5：配置文件到底在哪？

主路径是：

~/.config/md2wechat/config.yaml

先跑：

md2wechat config init
md2wechat config show --format json

第二条命令很关键，因为它会直接告诉你：

  • 当前实际生效的是哪份配置
  • 当前基础地址是什么
  • 默认 provider / convert mode 是什么

Q6：提示 WECHAT_APPID is required

这通常说明两件事之一：

  1. 你还没配微信凭证
  2. 你以为配置了，但当前生效文件里没有

最稳做法：

md2wechat config init
md2wechat config validate
md2wechat config show --format json

然后确认配置里至少有：

wechat:
  appid: "你的公众号 AppID"
  secret: "你的公众号 AppSecret"

Q7：不传 --mode，默认到底走 API 还是 AI？

默认一定是 API。

也就是说：

md2wechat convert article.md

等价于：

md2wechat convert article.md --mode api

只有显式传：

md2wechat convert article.md --mode ai

才会进入 AI 模式。

Q8：改了配置，但感觉没生效

最常见原因有三个：

  1. 改的不是当前生效文件
  2. 环境变量覆盖了配置
  3. 误以为某个配置项会覆盖 convert 的默认行为

先执行：

md2wechat config show --format json

优先看这些字段：

  • config_file
  • md2wechat_base_url
  • image_provider
  • default_convert_mode

Q9：API 模式提示需要 API Key

这是正常前置条件。

如果你没配置 API Key，有两条路：

方案 A：配 API Key

export MD2WECHAT_API_KEY="your_key"

方案 B：明确改走 AI 模式

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

三、转换与排版：不要靠猜，先 discovery

Q10：AI 模式为什么没有直接产出最终 HTML？

这是当前 CLI 的设计。

convert --mode ai 当前更像：

  • 生成 AI request / prompt
  • 返回 status=action_required
  • 写出 *.prompt.txt

如果你要稳定、直接的 HTML 输出，优先：

md2wechat convert article.md --mode api

Q11：转换结果为空、乱码或者很奇怪

优先排两件事：

  1. 文件编码是不是 UTF-8
  2. Markdown 本身结构是否异常

先试：

file article.md

如果不是 UTF-8，可转码：

iconv -f GBK -t UTF-8 article.md > article-utf8.md

Q12：我想知道支持哪些主题、provider、prompt，不想靠文档猜

不要猜，直接 discovery：

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

要看具体资源，再执行：

md2wechat providers show openrouter --json
md2wechat themes show autumn-warm --json
md2wechat prompts show cover-default --kind image --json

如果你不想自己写图片 prompt，也可以直接用内置 preset：

md2wechat generate_cover --article article.md
md2wechat generate_infographic --article article.md --preset infographic-comparison
md2wechat generate_infographic --article article.md --preset infographic-dark-ticket-cn --aspect 21:9

四、图片与素材：最容易忽略的是“素材本身有问题”

Q13：图片上传失败 upload material failed

按这个顺序排最稳：

  1. 图片格式是否支持
  2. 图片是否尺寸过小或异常
  3. 微信凭证是否有效
  4. IP 白名单是否配置好

支持的常见格式：

  • jpg
  • png
  • gif
  • bmp
  • webp

一个很关键的细节是：

极小测试图，例如 1x1 PNG，可能被微信拒绝。

调试时别用极小占位图，直接换成正常尺寸图片。

Q14：为什么图片链接没有被替换成微信素材地址？

通常是因为你没走上传链。

例如：

md2wechat convert article.md --upload -o output.html

如果你只是：

md2wechat convert article.md -o output.html

那它不会自动上传，也不会帮你替换成微信素材地址。

Q15：AI 生成图片失败

最常见原因：

  1. IMAGE_API_KEY 没配
  2. provider 配置不完整
  3. 模型或 base URL 不对

建议最短排查顺序：

md2wechat providers list --json
md2wechat config show --format json
md2wechat generate_image "test prompt"

五、微信与草稿：最多问题都不是“代码 bug”

Q16：第一次调用微信接口就报 ip not in whitelist

这是微信接口的前置限制，不是代码 bug。

最短处理步骤：

  1. 在实际执行机器上查公网 IP
  2. 去微信开发者平台的开发接口管理
  3. 把这个公网 IP 加进白名单
  4. 等几分钟再重试

如果你在 CI 或动态出口环境里执行，这个问题会更高频。

Q17：草稿创建失败 create draft failed

先别直接跑完整链，按这个顺序最稳：

md2wechat config validate
md2wechat upload_image cover.png --json
md2wechat test-draft --json draft.html cover.png
md2wechat convert article.md --upload --draft --cover cover.png --json

最常见原因通常是：

  1. 公众号权限不足
  2. 白名单没配
  3. 封面图上传失败
  4. 内容包含敏感词

Q18：access_token expired 是不是凭证坏了？

不一定。

微信的 access_token 本来就会过期，很多场景程序会自动刷新。

如果你持续失败，再排：

  1. AppID / AppSecret 是否真的填对
  2. 是否刚重置过 AppSecret
  3. 当前生效配置是否就是你以为那份

先看：

md2wechat config show --format json

六、Agent 与自动化：推荐先看什么、先跑什么？

Q19：Agent 应该先看哪份配置、先跑哪些命令？

默认先看：

~/.config/md2wechat/config.yaml

然后推荐按这个顺序探测：

md2wechat config show --format json
md2wechat capabilities --json
md2wechat providers list --json
md2wechat themes list --json
md2wechat prompts list --json

这样 Agent 才知道：

  • 当前用了哪份配置
  • 默认 provider 是什么
  • 哪些 theme / prompt 真实可用

Q20：CI / GitHub Actions 里能直接调微信吗？

可以，但真正的门槛通常不在代码，而在：

白名单和固定出口 IP。

如果你的运行环境公网 IP 会频繁变化，微信白名单就是最大不稳定因素。

所以正式链路更推荐：

  • 固定公网 IP 的服务器
  • 或固定出口网关

减少对动态 IP CI 环境的依赖。

七、最稳的总排查顺序

如果你现在已经遇到问题，又不确定该从哪一步开始，直接照这个顺序走：

md2wechat config validate --json
md2wechat config show --format json
md2wechat upload_image --json cover.png
md2wechat test-draft --json draft.html cover.png
md2wechat convert article.md --mode api --upload --draft --cover cover.png --json

如果你还要测 AI，再补一条：

md2wechat convert article.md --mode ai --json

这个顺序的价值在于：

  1. 先排配置
  2. 再排图片
  3. 再排草稿
  4. 最后再测完整链路

八、遇到问题时，提 Issue 前请带上这些信息

1. 版本信息

md2wechat --version
go version

2. 当前配置摘要

md2wechat config show --format json

3. 失败命令和完整错误输出

md2wechat convert article.md 2>&1

4. 系统信息

uname -a

Windows 用户则提供：

systeminfo

原始 FAQ 和官方入口

如果你需要更完整的上下文、更多边界情况和后续更新，建议直接看 md2wechat-skill 官方仓库文档：

这篇博客 FAQ 的定位是：

先帮你快速定位核心问题，再把你引到官方文档和仓库继续深入。

继续阅读

md2wechat API 常见错误排查：401、400、主题无效、试用 key 过期怎么处理

如果你已经开始调接口，但总是遇到 401、400 或主题错误，这篇文章会按真实排查顺序告诉你先查什么、后查什么，不让你盲猜。

md2wechat 3.6.0：把 Markdown 保存为知乎、CSDN、头条草稿

公众号排版之外，新增三平台未发布草稿流程。先准备普通 Markdown，再逐平台保存并核对。

MD2WeChat Publisher 2.0：在 Obsidian 预览排版、确认公众号草稿

文章仍在笔记库里写，排版在笔记旁检查。2.0 把预览、刷新和草稿确认放进同一套 Obsidian 操作流程。

YOUR NEXT ARTICLE

让下一篇文章，从清楚的排版开始。

先看效果，再把稳定的排版能力接入你的工作流。

申请 API 接入先看接入步骤
md2wechat FAQ：新手最常见问题、排查顺序与最短解决路径