微矩阵使用指南

CLI 与 MCP 使用指南

使用 WeMatrix CLI 0.2.0 登录、上传图片、创建草稿、查询数据，并在显式确认和权限允许时提交发布任务。

由微矩阵文档团队维护 · 最后更新：2026 年 8 月 20 日

CLI 定位

微矩阵 WeMatrix CLI 是面向 Agent、CI 和运营脚本的公开客户端。它覆盖公开 Open API 的 Agent Context、账号、样式、图片素材、草稿、流量主数据、发布任务和发布状态，并统一输出机器可读 JSON。

创建草稿不等于发布。正式发布需要 publish:write、符合微信接口资格的已认证公众号和 --confirm-publish；提交成功也只表示微信接收异步任务，必须继续查询状态。

安装

npm install -g wematrix-cli
# 或
pnpm add -g wematrix-cli

wematrix --version

# 临时运行
npm exec --package=wematrix-cli -- wematrix --help
pnpm dlx wematrix-cli --help

运行环境需要 Node.js 18.18 或更高版本。完整中英文说明位于 CLI README。

两种登录方式

浏览器授权（默认）

wematrix login --base-url https://mp.lingxiaoyao.cn

# 无图形界面、SSH 或浏览器无法自动打开
wematrix login --base-url https://mp.lingxiaoyao.cn --no-browser

默认登录会打开需要微矩阵会话的授权页并轮询结果。--no-browser 会输出包含授权网址和用户码的 verification_required JSON；请在已经登录微矩阵的浏览器中打开。授权请求约 10 分钟后过期，只能兑换一次。浏览器签发的 CLI Token 固定包含当前全部 scope，包括 publish:write。

直接 Token 登录

export WEMATRIX_TOKEN="mp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
wematrix login --base-url https://mp.lingxiaoyao.cn

# 或显式传入
wematrix login --base-url https://mp.lingxiaoyao.cn --token "$WEMATRIX_TOKEN"

设置页手动创建的 Token 和浏览器 CLI 授权签发的 Token 默认都包含全部 scope，包括 publish:write。正式发布仍需要显式确认和符合微信接口资格的已认证公众号。详情见 API Token 文档。

配置、安全与 JSON 输出

Token 优先级是 --token、WEMATRIX_TOKEN、本地配置；服务地址优先级是 --base-url、WEMATRIX_BASE_URL、本地配置、http://localhost:3000。高优先级 Token 格式错误时不会静默回退。

本地配置是 ~/.wematrix/config.json，权限为 0600。未设置口令时 Token 存在这个私有文件中；设置 WEMATRIX_CONFIG_PASSPHRASE 时改用 AES-256-GCM 加密。口令不是使用 CLI 的必选项，但加密配置再次使用时必须提供同一口令。

export WEMATRIX_CONFIG_PASSPHRASE="来自密码管理器的口令"
wematrix login --token "$WEMATRIX_TOKEN"
wematrix logout

成功写 JSON 到 stdout，错误写结构化 JSON 到 stderr 并返回非零退出码。--compact 输出单行 JSON；--base-url、--token、--help、--version 是全局参数。Token 会在输出中脱敏。

完整命令参考

命令	Scope	用途
`context / whoami`	`agent:context`	读取能力、Token scopes、账号矩阵和发布策略。
`accounts`	`accounts:read`	读取当前 Token 可访问的公众号。
`styles [--appid]`	`styles:read`	读取单个或全部账号样式。
`draft create`	`drafts:create`	从 Markdown 文件或 stdin 创建草稿。
`image upload`	`drafts:create`	从本地文件或 HTTP(S) URL 上传封面/正文图片。
`publisher summary/settlement/daily`	`publisher:read`	读取流量主累计、区间和每日数据。
`publish submit/status`	`publish:write`	显式确认提交发布任务，并查询异步状态。
`mcp config`	`无需业务 scope`	生成远程 HTTP MCP 配置。

wematrix context
wematrix whoami
wematrix accounts
wematrix styles [--appid APPID]

wematrix publisher summary [--appids wx1,wx2]
wematrix publisher settlement [--appids wx1,wx2] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--group-by appid|total]
wematrix publisher daily [--appids wx1,wx2] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--group-by appid|total]

wematrix mcp config [--base-url URL]

图片与草稿

wematrix image upload ./cover.jpg --appid wx123 --usage cover
wematrix image upload https://cdn.example.com/body.png --appid wx123 --usage content

cover 是默认 usage，返回永久素材 mediaId；content 返回微信正文图片 url。本地文件使用 multipart，HTTP(S) URL 使用 JSON。支持 JPEG、PNG、GIF、WebP，单张最大 10 MiB；远程图片必须能被服务器公开访问并通过 SSRF、超时、类型和大小校验。

wematrix draft create <markdown-file> --title TITLE [--appid APPID]
wematrix draft create --stdin --title TITLE [--appid APPID]

可选参数：
--author TEXT                 --summary TEXT
--article-type news|newspic   --source-url URL
--cover-image-url URL         --cover FILE_OR_URL
--image FILE_OR_URL           --image-media-id MEDIA_ID   # 均可重复
--upload-images
--show-cover-pic | --no-show-cover-pic
--open-comment | --no-open-comment
--fans-only-comment | --no-fans-only-comment
--theme-config JSON_OR_FILE
--cover-info JSON_OR_FILE
--product-info JSON_OR_FILE

--cover 和重复的 --image 接受本地文件或 URL，并先上传成永久素材；--image-media-id 复用已有素材。--upload-images 会上传并改写 Markdown 中的本地相对/绝对图片；相对路径按 Markdown 文件目录解析，stdin 按当前工作目录解析。HTTP(S)、data URL 和已有微信图片域名保持不变。标题最多 64 字符、作者 16、摘要 120、正文 1,000,000 字符、原文 URL 2048 字符。

wematrix draft create post.md   --title "产品周报" --appid wx123   --cover ./cover.jpg --upload-images --open-comment

wematrix draft create gallery.md   --title "图片消息" --appid wx123 --article-type newspic   --image ./one.jpg --image https://cdn.example.com/two.png   --image-media-id EXISTING_MEDIA_ID

正式发布

wematrix publish submit --article-id ARTICLE_ID --confirm-publish
# 或
wematrix publish submit --media-id MEDIA_ID --appid wx123 --confirm-publish

wematrix publish status --appid wx123 --publish-id PUBLISH_ID

两个提交选择器只能选一个，--confirm-publish 必填。提交只创建微信异步任务；请用返回的 publishId 查询状态，不能把提交成功表述成文章已经上线。

MCP 配置

wematrix mcp config --base-url https://mp.lingxiaoyao.cn

{
  "mcpServers": {
    "wematrix": {
      "type": "http",
      "url": "https://mp.lingxiaoyao.cn/api/mcp",
      "headers": { "Authorization": "Bearer ${WEMATRIX_TOKEN}" }
    }
  }
}

保留环境变量占位符，不要把真实 Token 写进共享配置。接口详情见 Open API 指南和 OpenAPI JSON。

排查建议

TOKEN_MISSING / TOKEN_INVALID_FORMAT：设置 Token 或登录；格式必须是 mp_ 加 48 个十六进制字符。

CONFIG_PASSPHRASE_MISSING：本地配置已加密，提供保存时相同的口令。

FORBIDDEN：先运行 wematrix context 检查实际 scopes、账号和额度范围。

浏览器未打开：使用 wematrix login --no-browser，在已登录网站的浏览器中打开输出网址。

图片失败：检查格式、10 MiB 限制、远程公开可访问性、防盗链和公众号权限。

发布失败：检查 publish:write、显式确认、公众号认证，并读取异步状态。