md2wechat先确认失败发生在安装、文章检查、转换预览、图片上传还是草稿创建。先做本地检查，再尝试对应操作；上传图片、生成并上传素材、创建草稿会产生外部结果，不应作为通用排障起手式。
本文按 CLI v3.8.0 核对，执行协议和配置文档说明当前边界。本地检查通过，只证明具备尝试条件，不代表远程认证成功。
命令找不到，或装了 Skill 仍然不能运行
安装 Skill 和安装 CLI 是两件事。先在 Agent 实际执行命令的环境中检查：
md2wechat version --json
md2wechat --help
找不到命令时，确认 Node.js 和 npm 可用，再安装：
node --version
npm --version
npm install -g @geekjourneyx/md2wechat
macOS / Linux 可检查命令位置和 npm 的全局安装前缀：
command -v md2wechat
npm prefix -g
通常可执行文件位于该前缀下的 bin 目录；按自己的 Node.js 安装方式核对 PATH。Windows 在 PowerShell 使用：
Get-Command md2wechat
npm prefix -g
Windows 全局可执行文件通常位于 npm 全局前缀目录中。远程 Agent、终端和桌面应用可能读取不同的环境变量，终端里能找到命令不代表另一个宿主也能找到。修正后在原来失败的宿主重新检查版本。
公司镜像返回包不存在时，可确认是否允许使用官方 npm 源，再按 v3.8.0 安装说明中的镜像排障处理。不要反复初始化或覆盖已有配置。
不确定是哪份配置生效
执行以下本地检查，不上传素材、不创建草稿：
md2wechat version --json
md2wechat config show --format json
md2wechat doctor --json
md2wechat inspect article.md --json
查看本机版本、当前生效配置和文章的 data.readiness.targets / data.readiness.blockers。只处理当前目标对应的阻碍项。配置中的转换 API Key、微信凭证和图片提供商密钥不能互相替代。
排障资料分享前人工检查并脱敏。即使命令对已知密钥做了隐藏，也不要默认整个输出都适合公开。
转换预览失败
默认 API 模式需要转换服务的有效 API Key。先核对文件存在、编码为 UTF-8、主题可用于当前模式，再按错误类型处理：
| 现象 | 检查什么 | 下一步 |
|---|---|---|
| 401 / 认证失败 | API Key 是否提供、有效或已过期 | 按 API 错误说明检查认证；不改微信凭证试错 |
| 400 / 参数错误 | Markdown、主题名称、字号与请求体 | 用最小文章和默认主题复现，再逐项添加参数 |
| 网络超时或服务不可达 | 实际执行环境的网络与服务地址 | 保留错误状态，确认服务可达后再试 |
显示 action_required |
是否选择了 AI 模式 | 读取返回提示词，由 Agent 完成后续工作 |
| 找到旧 HTML，但本次预览失败 | 本次状态和 data.output_file |
旧文件不能证明本次成功；失败时不把它当成新预览 |
需要重新验证预览时，使用新的输出文件名：
md2wechat preview article.md --output article-check.html --json
只有成功返回的文件才用于检查。PREVIEW_ACTION_REQUIRED 或 PREVIEW_FAILED 不会创建或覆盖 HTML。API 响应中的排版内容在 data.html；CLI 预览文件路径在 data.output_file，两者不要混用。
主题或高级排版不符合预期
先确认实际主题，而不是凭显示名称猜 ID：
md2wechat themes list --json
md2wechat themes show default --json
md2wechat layout validate --file article.md --json
API 模式选择 type: api 且 selectable: true 的主题；AI 模式按本机发现结果选择对应主题。模块校验通过说明语法符合规则，不代表微信里所有效果都已验证。核对预览和手机显示后再决定是否继续。
图片上传或草稿创建失败
先运行上面的本地检查，再确认目标公众号、AppID / AppSecret、接口权限、实际公网出口与适用的 IP 白名单。封面和正文图片分别准备，检查文件能否读取、格式和尺寸是否符合微信要求。
本节不提供连续上传、测试草稿或重新创建草稿的通用命令。用户确认账号、文章、素材和操作后，按草稿工作流执行需要的动作。
超时后先检查草稿箱，核对工具返回的草稿结果；可能已创建的草稿不要盲目重试。草稿成功仍需到后台核对标题、正文、图片和封面，不能据此认定正式发布或群发完成。
AI 图片或多平台草稿失败
图片计划只准备提示词；真实图片生成涉及提供商调用及适用的素材上传。先查命令与能力大全和本机 providers show，确认密钥、模型与结果去向，再决定是否执行会调用外部服务的命令。
知乎、CSDN、头条和腾讯云开发者社区草稿使用独立浏览器流程。SYNC_PREPARED / action_required 表示本地准备完成，还没有证明目标平台保存成功。按多平台草稿教程检查登录、输入限制和草稿重开结果；中断后恢复同一草稿，避免重复创建。
终端能运行，Claudian 里却找不到命令
先分别确认 CLI 和 Skill 已安装。终端能找到 CLI，但 Obsidian 的 Claudian 找不到时，核对插件的 Settings → Environment → Custom variables：PATH 是否包含 CLI 的实际目录，原有目录是否保留。调整后在 Claudian 内重新检查版本；不要照抄其他人的安装目录。
具体入口见 v3.8.0 FAQ 的 Claudian 问题。这不是本轮宿主验收结果。
macOS 提示无法验证开发者
先核对下载是否来自官方 Release、系统和处理器是否对应，以及校验文件是否一致。来源确认后，按 Apple 的安全打开说明处理具体提示；受公司管理的设备联系管理员。不要把清除安全属性的命令作为通用安装步骤。
预览中的图片为什么没有换成微信地址
inspect、preview 和普通 convert 不会上传图片，也不会把文内图片替换成微信素材地址；这不表示预览失败。确实需要上传时，先确认素材、目标公众号和凭证，再按草稿工作流执行已授权的操作。机制见 v3.8.0 FAQ 的图片链接说明。
access_token expired 是否说明凭证失效
不一定。微信的访问凭证会过期，程序通常会刷新；一次过期不能证明 AppSecret 已失效。持续失败时，核对当前账号的 AppID / AppSecret 是否正确、是否刚重置，以及实际生效配置。保留错误，先查已有草稿，不用重复创建来验证凭证。
依据见 v3.8.0 FAQ 的访问凭证说明。
提交问题时带哪些资料
提供系统、宿主名称、CLI 版本、失败步骤、原始错误状态，以及经过脱敏的最小文章。说明是否产生了 HTML、图片上传结果或草稿，便于区分失败位置；不要附完整密钥、密码或未获授权的文章。