md2wechat-skill

md2wechat-skill 是 md2wechat 在 Agent 运行时里的官方 Skill 入口，适合这些环境：

• Claude Code
• Codex
• OpenCode
• Obsidian 的 Claudian
• OpenClaw

如果你是第一次接触它，先记住一句话：

先安装 md2wechat CLI，再安装 md2wechat skill。

仓库地址：

https://github.com/geekjourneyx/md2wechat-skill

这页适合谁

这页适合下面几类用户：

• 已经在 Claude Code、Codex、OpenCode 里工作，想直接把 Markdown 转成微信公众号排版
• 想在 Obsidian 的 Claudian 里直接调用 md2wechat
• 想在 OpenClaw 里安装并验证 md2wechat
• 不想先看一堆零散文档，只想按步骤跑通第一次成功调用

先看这里

在你开始安装之前，先记住这 7 件事：

• 如果你已经有 Node 和 npm，2.0.7 之后优先走 npm 安装 CLI
• npx skills add ... 只安装 skill，不会帮你安装 md2wechat CLI
• md2wechat convert 在不传 --mode 时默认走 API 模式
• 如果你想走 AI 模式，要显式传 --mode ai
• 不要靠猜当前支持哪些 theme、provider、prompt，先跑 discovery 命令
• OpenClaw 是独立路径，不和 Claude Code / Codex / OpenCode 共用同一套 skill 包
• 想发草稿或上传素材，除了 CLI 和 skill，你还需要微信凭证；API 模式通常还需要 md2wechat.cn 的 API Key

5 分钟快速开始

如果你只想尽快跑通，按这个顺序执行。

第一步：安装 CLI

如果你已经有 Node 和 npm，优先走这条：

npm install -g @geekjourneyx/md2wechat

macOS 用户如果更习惯 Homebrew，也可以继续用：

brew install geekjourneyx/tap/md2wechat

如果你已经有稳定的 Go 环境：

go install github.com/geekjourneyx/md2wechat-skill/cmd/md2wechat@v2.0.7

如果以上都不适合，再用固定版本安装器：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install.sh | bash

npm 这条路径有两个你真正会关心的点：

• 它不会在你本地重新编译 Go 项目
• 它会下载与当前版本同号的 GitHub Release 二进制，并校验同一个 checksums.txt

也就是说，npm、Homebrew 和固定版本安装脚本，最终复用的是同一套发布产物。

当前 npm 安装覆盖这些目标：

• macOS：amd64 / arm64
• Linux：amd64 / arm64
• Windows：amd64

如果你刚发版后遇到 npm 镜像还没同步，先改用官方源安装：

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

如果你走的是安装器路径，再补一条：

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

第二步：安装 skill

Claude Code、Codex、OpenCode、Claudian 共用这条安装命令：

npx skills add https://github.com/geekjourneyx/md2wechat-skill --skill md2wechat

第三步：验证安装

md2wechat version --json
md2wechat config init
md2wechat capabilities --json

第四步：跑第一次成功任务

md2wechat convert article.md --preview

如果这一步成功，说明你的 CLI 主路径已经打通。

按环境选择安装方式

Claude Code / Codex / OpenCode

这三个环境最稳的理解方式是一样的：

1. 先安装 CLI
2. 再安装 skill
3. 先跑 discovery
4. 再让 Agent 执行真正的任务

推荐命令：

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

建议直接发给 Agent 的提示词：

请先安装 md2wechat CLI，再安装 md2wechat skill，验证 version 和 capabilities，所有命令成功后再结束。

Obsidian / Claudian

Claudian 的 skill 路径和 Claude Code 兼容，所以安装顺序还是：

1. 先装 CLI
2. 再装 skill
3. 再回到 Obsidian 里调用

推荐命令：

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

回到 Claudian 后，你可以直接输入：

/md2wechat

或者直接发：

请用 md2wechat 把当前 Markdown 笔记转成公众号 HTML，先给我一个预览版本。

如果终端里能找到 md2wechat，但 Claudian 里找不到，优先检查 GUI 的 PATH。去：

• Settings
• Environment
• Custom variables

补一条类似：

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

OpenClaw

OpenClaw 是单独一条安装路径。你要同时满足两件事：

• ~/.openclaw/skills/md2wechat/ 下有 OpenClaw 的 skill 壳
• PATH 里有可执行的 md2wechat CLI

最快的完整安装方式：

curl -fsSL https://github.com/geekjourneyx/md2wechat-skill/releases/download/v2.0.7/install-openclaw.sh | bash
export PATH="$HOME/.local/bin:$PATH"

安装后验证：

md2wechat version --json
md2wechat config init
md2wechat config validate
md2wechat capabilities --json
ls ~/.openclaw/skills/md2wechat/

如果你已经在用 ClawHub，也可以先装 skill 壳：

npx clawhub@latest install md2wechat

但这通常只保证装好了 OpenClaw 的 shell，不保证 CLI 也已经可用。装完后请立刻检查：

command -v md2wechat

如果你本机已经有 Node 和 npm，也可以先单独装 CLI：

npm install -g @geekjourneyx/md2wechat

但这一步不会自动写入 ~/.openclaw/skills/md2wechat/，所以它不能替代 OpenClaw 的 skill 安装。

第一次使用时建议跑什么

不要一上来就直接发草稿。最稳的顺序是先从简单到复杂。

1. 预览转换结果

md2wechat convert article.md --preview

2. 用 AI 模式生成结构化结果

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

这里要注意：

• 这不是直接生成最终 HTML 的 API 转换
• 这一步返回的是给第二步模型继续处理的结构化输出

3. 创建微信草稿

md2wechat convert article.md --draft --cover cover.jpg

这一步通常还要求：

• 微信 AppID
• 微信 Secret
• API 模式下通常还要 md2wechat.cn API Key
• 一张可用的封面图

为什么一定要先做 discovery

md2wechat-skill 面向的是 Agent 工作流，而 Agent 最容易犯的错误，就是没确认当前运行时能力就先开始猜。

正式执行前，先跑这些命令：

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

这样你能提前知道：

• 当前默认模式是什么
• 当前哪些图片 provider 已配置
• 当前有哪些主题
• 当前有哪些封面图 / 信息图 prompt preset

常见问题

为什么已经装了 skill，还是提示 command not found: md2wechat？

因为你装的是 skill，不是 CLI runtime。

先补装 CLI：

brew install geekjourneyx/tap/md2wechat

然后验证：

md2wechat version --json

为什么 Agent 没写 --mode，却默认走了 API 模式？

因为 md2wechat convert 在不传 --mode 时默认就是 API 模式。

如果你想显式使用 AI 模式：

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

为什么 AI 模式没有直接返回最终 HTML？

因为 AI 模式的设计就是先输出结构化请求，再交给外部模型继续处理。它不是“更漂亮的 API 模式”，而是另一条多步骤工作流。

为什么终端里能找到工具，Claudian 里却找不到？

因为 Obsidian 图形界面进程的 PATH 往往和终端不同。优先去 Claudian 的 Settings -> Environment -> Custom variables 补 PATH。

为什么 OpenClaw 装完 skill 还是失败？

因为 OpenClaw 需要同时满足：

• ~/.openclaw/skills/md2wechat/ 下有 shell
• PATH 里有 md2wechat CLI

只满足其中一个，工作流仍然是坏的。

为什么我应该先跑 capabilities --json？

因为这能避免 Agent 误判当前支持什么。它比“记忆中的功能列表”更可靠，是当前运行时的真实能力快照。

接下来该看哪里

如果你已经跑通主路径，接下来按需求继续看：

• md2wechat-skill 使用指南
• md2wechat-skill FAQ
• Coding Agents 总览
• Claude Code
• Codex
• OpenCode
• Claudian
• OpenClaw