md2wechat-skill FAQ

这一页只做一件事：把高频问题按“症状 -> 原因 -> 修复”快速讲清。

如果你还没开始安装，先看主入口：

• md2wechat-skill

症状 1：command not found: md2wechat

原因

skill 安装了，但 CLI 没安装，或者 PATH 没刷新。

修复

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

如果你是通过 install.sh 安装的，再补一条：

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

症状 2：npx skills add 执行成功，但 Agent 还是不能用

原因

npx skills add 只安装 skill，不安装 runtime。

修复

先确认：

command -v md2wechat
md2wechat version --json

如果第一条没输出，说明 CLI 还没真正可用。

症状 3：我没指定模式，为什么默认走了 API

原因

md2wechat convert 的默认模式就是 API。

修复

如果你想强制 AI 模式：

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

症状 4：AI 模式为什么没有直接返回最终 HTML

原因

AI 模式的设计就是返回给第二步模型继续处理的结构化输出，不等于 API 直转 HTML。

修复思路

• 想要稳定直出 HTML，优先走 API 模式
• 想要主题化 AI 工作流，再走 --mode ai

症状 5：Claudian 里找不到命令，但终端里能找到

原因

Obsidian 图形界面进程的 PATH 和终端经常不一样。

修复

在 Claudian：

• Settings
• Environment
• Custom variables

补上 CLI 所在目录，例如：

PATH=/Users/你的用户名/.local/bin:原来的PATH

症状 6：OpenClaw 安装后还是失败

原因

OpenClaw 不是只看 skill 壳，它还要求 CLI 也在 PATH 里。

修复

同时检查：

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

两边必须都正常。

症状 7：Agent 不知道当前支持哪些主题和 provider

原因

运行时没有先做 discovery。

修复

先跑：

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

症状 8：草稿创建失败

常见原因

• 没有微信 AppID
• 没有微信 Secret
• API 模式下没有 md2wechat.cn API Key
• 没有封面图

修复方向

先确认你已经具备：

• 微信 AppID
• 微信 Secret
• API Key
• cover.jpg 或其他可用封面图

还应该去哪看

• 想重新梳理主线：看 md2wechat-skill
• 想看验证和最佳实践：看 md2wechat-skill 使用指南
• 想看环境细分说明：看 Coding Agents 总览、Claudian、OpenClaw