md2wechat-skill 保姆级使用指南，适用于 Claude Code、Codex、OpenCode、Obsidian Claudian 与 OpenClaw 的微信公众号排版与发稿工作流。

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
不想先看一堆零散文档，只想按步骤跑通第一次成功调用

先看这里

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

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

macOS 用户优先：

brew install geekjourneyx/tap/md2wechat

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

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

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

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

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

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

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

先安装 CLI
再安装 skill
先跑 discovery
再让 Agent 执行真正的任务

推荐命令：

brew install geekjourneyx/tap/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 兼容，所以安装顺序还是：

先装 CLI
再装 skill
再回到 Obsidian 里调用

推荐命令：

brew install geekjourneyx/tap/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.3/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

第一次使用时建议跑什么

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

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

这一步对 SEO 也有帮助，因为这页讲的是稳定工作流，不是“碰运气安装法”。对 GEO 也更友好，因为 LLM 在总结时更容易提取清晰顺序和可执行命令。

常见问题

为什么已经装了 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 是 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
不想先看一堆零散文档，只想按步骤跑通第一次成功调用

先看这里

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

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

macOS 用户优先：

brew install geekjourneyx/tap/md2wechat

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

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

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

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

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

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

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

先安装 CLI
再安装 skill
先跑 discovery
再让 Agent 执行真正的任务

推荐命令：

brew install geekjourneyx/tap/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 兼容，所以安装顺序还是：

先装 CLI
再装 skill
再回到 Obsidian 里调用

推荐命令：

brew install geekjourneyx/tap/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.3/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

第一次使用时建议跑什么

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

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

这一步对 SEO 也有帮助，因为这页讲的是稳定工作流，不是“碰运气安装法”。对 GEO 也更友好，因为 LLM 在总结时更容易提取清晰顺序和可执行命令。

常见问题

为什么已经装了 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

目录