@haoxu/cli（号续 CLI）

通过本机 Agent Bridge 查询号续数据：账号统计、稿件、存稿任务、发表任务、分组、标签、代理 IP、稿件分类、员工（主账号），以及公众号远端草稿箱与发表记录。0.4.0 起支持账号元数据写操作（号主/备注、移组、设标签、分组/标签 CRUD）。0.5.0 起支持代理写操作（代理库 CRUD/绑定/检测/Excel 导入、异步 Job）。0.6.0 起支持统计刷新、账号检测（非代理检测）与未读刷新。0.7.0 起支持本机路径（含 zip）与公众号链接导入稿件。0.8.0 起支持存稿 create/start/cancel/delete 与发表 from-batch-draft / start / start-batch / start-all-pending。0.9.0 起支持单篇稿件设封面（本机路径 / URL / 清除）。1.0.0 起支持公众号面板远端写（删草稿、草稿另存、已发表改私密、素材库 list/上传/删图）。1.4.0 起支持单独导出账号 Cookie（须 cookieExport 权限）。1.5.0 起支持 Cookie 导入添加账号（accounts import-cookie）。

供各类 AI Agent 调用（Cursor、Claude Code、Codex、WorkBuddy、QoderWork、QClaw、OpenClaw、Trae 等；凡能执行终端命令即可）。

前置： 必须安装并运行 号续桌面端（含 Agent Bridge 能力），在设置中启用 Agent Bridge 并生成 API Key。CLI 不能单独访问云端数据。查远端草稿/发表还需目标账号在线且已登录公众平台。稿件路径导入须本机绝对路径，号续与 Agent 同机；不支持飞书。

当前版本：1.5.0

安装

需要 Node.js 18+。

npm install -g @haoxu/[email protected]
# 或
npx @haoxu/[email protected] --help

安装后全局命令为 haoxu。

快速开始

完整小白教程（含让 Agent 代装）：号续仓库 Desktop/docs/agent/haoxu-agent-guide.md §1–§2。

1. （推荐）安装 Agent Skill：npx skills add montisan/skills --skill haoxu-agent -y -g
2. 安装本 CLI：npm install -g @haoxu/[email protected]
3. 打开号续 → 设置 → Agent Bridge → 启用 → 生成并复制 API Key（主账号与子账号均可；Key 本机共用）
4. 配置 CLI：

haoxu auth set-key
haoxu auth status --json

3. 查询示例：

haoxu accounts list --json
haoxu manuscripts list --assigned unassigned --json
haoxu draft-tasks list --status completed --completed today --json
haoxu publish-tasks list --status scheduled --json
haoxu groups list --json
haoxu tags list --json
haoxu ip-proxies list --status healthy --json
haoxu categories list --json
haoxu employees list --json   # 仅主账号

导出账号 Cookie（1.4.0）

accounts list|get 不返回 cookie；需要时用独立命令 accounts cookie，且当前登录用户须有 cookieExport 权限（员工账号看主账号的权限）。无权限返回 403 FORBIDDEN；账号未在号续内登录、取不到 CK 时返回 503 ACCOUNT_NOT_READY。

haoxu accounts cookie <id> --json
# → { "accountId": "...", "wxid": "...", "name": "...", "cookie": "slave_sid=...; ..." }

Cookie 属敏感凭证，取到后请勿写入日志、仓库或转发给第三方。

Cookie 导入添加账号（1.5.0）

与桌面端「添加账号 → Cookie 导入」同一条链路：注入 Cookie → 校验登录态 → 从公众平台拉回 wxid / 名称 / 类型 → 入库并接管登录态延续。wxid、名称、类型无须传入。

# 直连
haoxu accounts import-cookie --cookie-file ./ck.txt --json

# 指定分组 + 代理库节点
haoxu accounts import-cookie --cookie-file ./ck.txt \
  --group <groupId> --mode managed --ip-proxy-id <ipProxyId> --json

# 自定义代理（不入代理库，直接嵌到账号上），--payload-file 内容形如
# { "host": "1.2.3.4", "port": 1080, "type": "SOCKS5", "username": "u", "password": "p" }
haoxu accounts import-cookie --cookie-file ./ck.txt --mode custom --payload-file ./proxy.json --json

| 参数 | 说明 | |------|------| | --cookie-file / --cookie | 二选一。支持标准 Cookie 头、JSON、Netscape 等格式，自动识别。长 Cookie 建议用文件 | | --group | 分组 ID；省略或 ungrouped 表示未分组。员工账号通常必须指定 | | --owner | 号主，可选 | | --mode | direct（默认，本地直连）/ managed（配 --ip-proxy-id）/ custom（配 --payload-file） |

失败返回：账号数超限或未开通会员 403 FORBIDDEN；号续内正在添加账号（添加账号窗口开着 / 扫码未结束）或已有导入在跑 409 CONFLICT；Cookie 失效 401 REMOTE_UNAUTHORIZED。

一次只能导入一个账号，无批量接口；多账号请串行调用，遇 409 稍后重试。

账号元数据写操作（0.4.0）

# 修改号主/备注
haoxu accounts patch <id> --owner 张三 --json

# 移组
haoxu accounts move-group <id> --group <groupId|ungrouped> --json

# 设标签（全量替换）
haoxu accounts set-tags <id> --tags t1,t2 --json

# 分组/标签 CRUD（删除须 --confirm）
haoxu groups create --name 新分组 --json
haoxu groups delete <id> --confirm --json
haoxu tags create --name 新标签 --json
haoxu tags delete <id> --confirm --json

移组、分组 CRUD 仅主账号；员工可改可见账号的号主/备注与标签（须会员额度）。详见包内 Skill 权限表。

代理写操作（0.5.0）

# 代理 CRUD（删除须 --confirm）
haoxu ip-proxies create --host 1.2.3.4 --port 1080 --type socks5 --json
haoxu ip-proxies test <id> --json
haoxu ip-proxies delete <id> --confirm --json

# Excel 导入（异步，返回 jobId）
haoxu ip-proxies import --file ./proxies.xlsx --json
haoxu jobs get <jobId> --json

# 账号绑定 / 代理检测
haoxu accounts bind-proxy --accounts a1 --mode managed --ip-proxy-id <id> --json
haoxu accounts proxy-detect <accountId> --json
haoxu accounts proxy-detect-batch --accounts a1,a2 --poll --json

# 无库连通性 test
haoxu proxy test --host 1.2.3.4 --port 1080 --type socks5 --json

Excel 导入与批量代理检测为异步 Job（内存存储，号续重启后丢失；完成后约 1h TTL）。--poll 自动轮询 Job 至 completed/failed。

统计刷新 / 账号检测 / 未读（0.6.0）

查统计仍用 accounts list|get。账号检测（detect）≠ 代理检测（proxy-detect）。

# 单账号 / 批量统计刷新
haoxu accounts refresh-metrics <id> [--no-force] --json
haoxu accounts refresh-metrics-batch [--accounts a1,a2] [--poll] --json

# 单账号 / 批量账号检测
haoxu accounts detect <id> [--no-force] --json
haoxu accounts detect-batch [--accounts a1,a2] [--poll] --json

# 单账号 / 批量未读刷新
haoxu accounts refresh-unread <id> [--no-force] --json
haoxu accounts refresh-unread-batch [--accounts a1,a2] [--poll] --json

批量省略 --accounts 时处理全部可见可刷新账号。默认 force: true；--no-force 仅刷新符合自动策略的账号。

稿件导入（0.7.0）

路径须为本机绝对路径；号续与 Agent 同机。同步返回 { imported, errors }。不支持飞书。

haoxu manuscripts import-paths --paths /abs/a.docx,/abs/b.zip [--category <id>] [--strip-duplicate-title] --json
haoxu manuscripts import-links --urls https://mp.weixin.qq.com/s/xxx [--category <id>] --json

单篇稿件设封面（0.9.0）

--file / --url / --clear 互斥；本机路径须绝对路径，号续与 Agent 同机可读（与 import-paths 相同约束）。成功返回 { coverUrl: string | null }。

haoxu manuscripts set-cover <id> --file /abs/cover.jpg --json
haoxu manuscripts set-cover <id> --url https://example.com/cover.png --json
haoxu manuscripts set-cover <id> --clear --json

单篇稿件设原文链接（1.2.0）

--url / --clear 互斥。成功返回 { sourceUrl: string | null }。无批量 API，循环调用即可。

haoxu manuscripts set-source-url <id> --url https://example.com/article --json
haoxu manuscripts set-source-url <id> --clear --json
haoxu manuscripts list --source-url unset --json

单篇稿件插入配图（1.3.0）

--position：article_start / article_end / before_paragraph / after_paragraph。--files / --urls / --payload-file 三选一；本机路径须绝对路径且同机可读。成功返回 { contentWordCount: number }。

haoxu manuscripts insert-images <id> --position article_start --files /abs/a.jpg,/abs/b.png --json
haoxu manuscripts insert-images <id> --position before_paragraph --urls https://example.com/a.jpg --json
haoxu manuscripts insert-images <id> --payload-file ./insert-images.json --json

存稿 / 发表写操作（0.8.0）

启动后 fire-and-forget，须轮询 draft-tasks get / publish-tasks get 查看进度。1.1.0 起支持从远端草稿箱创建发表（from-drafts 默认只建、须 --start 开跑；from-first-drafts 创建后自动开跑）。仍不支持飞书 / 删发表任务。

作者/原创等与 UI 同级配置：用 --payload-file，字段在 originalityConfig（禁止顶层 author/isOriginal）。省略则默认未声明原创。完整字段见包内 Skill。

# 默认 --content-mode article（图文）；贴图用 note（亦接受 sticker）
haoxu draft-tasks create --account <id> --manuscripts m1,m2 [--content-mode article|note] [--payload-file ./draft.json] [--start] --json
haoxu draft-tasks create --account <id> --manuscripts m1 --content-mode note --start --json
haoxu draft-tasks start|cancel <id> --json
haoxu draft-tasks delete <id> --confirm --json
haoxu publish-tasks from-batch-draft --tasks d1,d2 [--schedule-date <label> --schedule-hour <h> --schedule-minute <m>] [--start] --json
haoxu publish-tasks from-drafts --drafts '[{"accountId":"a1","platformDraftId":"d1","draftTitle":"标题"}]' [--schedule-date <label> --schedule-hour <h> --schedule-minute <m>] [--start] --json
haoxu publish-tasks from-drafts --drafts-file ./drafts.json [--start] --json
haoxu publish-tasks from-first-drafts --accounts a1,a2 --draft-type article --json
haoxu publish-tasks start <id> --json
haoxu publish-tasks start-batch --ids p1,p2 --json
haoxu publish-tasks start-all-pending --json

公众号远端（0.3.0 读；1.0.0 写）

# 先查在线账号 ID
haoxu accounts list --quick-filter online --json

# 草稿箱关键词搜索
haoxu accounts mp-drafts <账号ID> --q 关键词 --json

# 今天发表记录
haoxu accounts mp-published <账号ID> --date-preset today --json

# 删草稿（须 --confirm）
haoxu accounts mp-drafts-delete <账号ID> <draftId> --confirm --json

# 草稿另存到其他账号（全同步，可能较久）
haoxu accounts mp-drafts-sync <账号ID> <draftId> --targets id1,id2 [--upload-material] --json

# 已发表设/取消仅自己可见
haoxu accounts mp-published-private <账号ID> --items '[{"appmsgid":123,"itemidx":1,"privateType":1}]' --json

# 素材库列表 / 上传 / 删图（上传与删图须本机绝对路径、同机；删图须 --confirm 与 --group-ids）
haoxu accounts mp-images <账号ID> [--group <id>] --json
haoxu accounts mp-images-upload <账号ID> --file /abs/image.jpg --json
haoxu accounts mp-images-delete <账号ID> --ids 1,2 --group-ids 0,0 --confirm --json

带日期筛选时响应可能含 scanExhausted: true（扫描达 10 页上限，结果可能不完整）。

配置写入 ~/.haoxu/config.json（baseUrl 默认 http://127.0.0.1:19321，apiKey）。

列表过滤

• 过滤参数使用英文稳定码，与号续 UI 对齐
• 多选 ID 用逗号分隔（如 --group id1,id2；哨兵 ungrouped / untagged / uncategorized）
• 详见 haoxu --help 或包内 Skill

常用示例：

haoxu accounts list --quick-filter online --group g1,g2 --json
haoxu manuscripts list --cover unset --json
haoxu ip-proxies list --group ungrouped --json

员工列表：仅主账号可访问；员工子账号返回 403。

Agent Skill

推荐从 GitHub skills 仓库全局安装：

npx skills add montisan/skills --skill haoxu-agent -y -g

仓库：https://github.com/montisan/skills

包内亦附带：skills/haoxu-agent/SKILL.md（备选：安装 CLI 后 cp 到 .cursor/skills 或 ~/.claude/skills）。

发布（维护者）

npm 账号 montisan，组织 haoxu（scope @haoxu）：

npm whoami                    # montisan
npm org ls haoxu              # 确认自己在组织内且有 publish 权限
cd packages/haoxu-cli
npm publish --access public

更多

完整教程：号续仓库 Desktop/docs/agent/haoxu-agent-guide.md。