md2wechat这篇文章只做一件事：带你走完第一次上手。
目标是让你真的跑通下面这条链路：
- 安装 md2wechat。
- 初始化配置。
- 把 Markdown 预览成微信 HTML。
- 再把文章送进草稿箱。
第一步：先准备好三类信息
1. 文章文件
先准备一个 article.md，内容不用复杂，能跑通就行。
# 我的第一篇公众号文章
大家好，这是我第一次用 md2wechat 发布内容。
## 今天想说什么
- 我用 Markdown 写正文
- 我希望自动排版
- 我希望直接进入微信草稿箱
2. API Key
如果你走 API 模式，需要 API Key。入口在：
3. 微信公众号配置
如果你后面要发草稿，还需要：
- AppID
- AppSecret
- IP 白名单
没有这些信息也没关系，你可以先把“转换预览”跑通，再补草稿链路。
第二步：安装 md2wechat
最稳妥的方式是去 Releases 页面拿当前版本：
README 已经给了完整的多平台安装说明。这里给你保留最常用的 macOS / Linux 路径。
macOS Apple Silicon
mkdir -p ~/.local/bin
curl -Lo ~/.local/bin/md2wechat https://github.com/geekjourneyx/md2wechat-skill/releases/latest/download/md2wechat-darwin-arm64
chmod +x ~/.local/bin/md2wechat
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
md2wechat --help
Linux x86_64
mkdir -p ~/.local/bin
curl -Lo ~/.local/bin/md2wechat https://github.com/geekjourneyx/md2wechat-skill/releases/latest/download/md2wechat-linux-amd64
chmod +x ~/.local/bin/md2wechat
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
md2wechat --help
Windows 用户
直接从 Releases 页面下载 .exe，然后在 PowerShell 里执行：
md2wechat --help
如果这一步跑不通，不要继续往后走，先解决 PATH 或二进制权限问题。
第三步：初始化配置
第一次建议直接执行：
md2wechat config init
执行后，你会得到配置文件路径。根据当前 skill 约定，优先检查这些位置：
~/.config/md2wechat/config.yaml- 环境变量，比如
MD2WECHAT_BASE_URL - 项目本地
md2wechat.yaml/md2wechat.yml/md2wechat.json
如果你需要切换接口域名，可以改：
api.md2wechat_base_url- 或环境变量
MD2WECHAT_BASE_URL
默认域名：
https://www.md2wechat.cn
备用域名：
https://md2wechat.app
第四步：先跑最安全的一步，预览转换结果
先别急着发草稿，先把 HTML 预览跑起来。
md2wechat convert article.md --preview
这一步的价值很大：
- 能先确认命令可用。
- 能先确认 Markdown 是否正常读取。
- 能先看主题是否适合。
- 出问题也不会直接打到公众号后台。
第五步：再试 AI 模式
如果你想要更风格化的排版，可以再试 AI 模式：
md2wechat convert article.md --mode ai --theme autumn-warm --preview
这里要注意一件事：
- API 模式更稳、更快，适合正式发布。
- AI 模式更有风格感，适合追求视觉表达。
第一次上手建议两种模式都各跑一次，你会很快知道自己后面更常用哪条路径。
第六步：确认微信配置后，再发草稿
真正发稿前，你至少要确认：
- AppID / AppSecret 是当前公众号的。
- IP 白名单已经配好。
- 封面图是可访问的。
确认后再执行：
md2wechat convert article.md --draft --cover cover.jpg
如果你走的是 API 文档里对外开放的 Convert API，当前只需要记住一个稳定接口：
POST /api/convert
这个接口负责把 Markdown 转成微信公众号可粘贴的 HTML。标题建议、图片计划、多账号和固定出口这类工作流能力，优先从 md2wechat 命令和 Skill 手册里看。
新手最常踩的坑
坑 1：一上来就发草稿
最稳的顺序是：
convert --preview- 看效果
- 再发草稿
坑 2：把 AI 模式当默认
很多人觉得 AI 模式听起来更高级，就默认走 AI。其实第一次上手更建议先走 API 模式，因为更容易排查问题。
坑 3：把转换 API 当成发布接口
/api/convert 只负责 Markdown 转 HTML，不需要微信后台配置。真正进入公众号发布链路时，再按手册检查：
- AppID
- AppSecret
- IP 白名单
坑 4：把配置写散
建议先把稳定配置放在：
~/.config/md2wechat/config.yaml
这样不管你是本地终端、Coding Agent 还是其他工作流，都能复用。
跑通第一次之后，接下来该学什么？
建议顺序是：
- 先读 命令大全
- 再读 Coding Agent 接入指南
- 如果你用 OpenClaw，继续读 OpenClaw 接入指南
- 如果你在 Obsidian 写作，继续读 Obsidian 接入指南
如果你只记住一句话：
第一次上手，先把“安装 → 配置 → 预览”跑通，再进入发布工作流。