Postiz Agent CLI
让 Claude Code 等 AI Agent 通过命令行直接在 28+ 社交平台上创建、排期、管理帖子并查看分析数据。
- Star 数
- ★ 542
- 最近更新
- 2 天前
- License
- NOASSERTION
- 主语言
- TypeScript
- FA 评分
- 54/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Claude Code
- 费用
- 有免费版，另有付费云服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用 Claude Code 的开发者想让 Agent 在对话中直接排期 Twitter/X、LinkedIn 等多平台内容发布
- 不适合
- 需要完全离线或数据不出本地的团队，发布与上传都依赖 Postiz 云端
- 无法执行 shell 命令的纯聊天环境，CLI 必须本地安装
- 不愿注册 Postiz 账号或使用其托管服务的团队
- 源码审查
- 54/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Postiz Agent（gitroomhq/postiz-agent）是 Postiz 社交媒体排期工具的 Agent 化入口，包含一个 postiz CLI 和以 skill/插件形式分发的集成包。它可安装为 Claude Code 插件、Cursor 插件或 Grok Build 插件（后者还捆绑了托管 MCP 服务器），也能通过 npx skills add 作为通用 skill 安装。CLI 通过 Postiz 公共 API 完成认证（OAuth2 设备流或 API Key）、列出集成、创建和排期帖子、上传媒体、查询平台与帖子分析。所有命令输出 JSON，便于 AI Agent 解析和串联。支持 Twitter/X、LinkedIn、Reddit、YouTube、TikTok、Instagram、Facebook 等 28+ 平台，包括线程、评论、平台特定设置等高级能力。媒体需先通过 postiz upload 上传，因为 TikTok、Instagram、YouTube 等平台只接受受信域名的 URL。
安装后，Agent 通过 postiz CLI 执行完整流程：postiz auth:login（OAuth2 设备流）或设置 POSTIZ_API_KEY 完成认证；postiz integrations:list 获取已连接账号及其 ID；postiz integrations:settings 读取字符上限和必填设置；postiz integrations:trigger 拉取动态数据（如 Reddit flairs、YouTube 播放列表、LinkedIn 公司页）。发帖时调用 postiz posts:create，通过 -c 内容、-s ISO 8601 排期时间、-i 集成 ID、-m 媒体 URL、--settings 平台特定 JSON 等参数组合，支持草稿、多平台分发、多段内容自动转线程。媒体先经 postiz upload 上传换取可信 URL。发帖后可用 posts:list、posts:status、posts:settings 管理帖子，用 analytics:platform 和 analytics:post 查询表现数据；若分析返回 {"missing": true}，用 posts:missing 和 posts:connect 关联平台内容。所有输出均为 JSON。
- 使用 Claude Code 的开发者想让 Agent 在对话中直接排期 Twitter/X、LinkedIn 等多平台内容发布
- 运营多客户社媒矩阵的团队，用
integrations:groups按 customer 分组过滤渠道并批量排期 - 需要定时发布带图片/视频的 TikTok、Instagram、YouTube 内容的创作者，先上传媒体再排帖
- 营销人员通过 bash 脚本循环
posts:create实现一周内容的批量定时发布 - 数据驱动的运营团队用
analytics:platform/analytics:post获取粉丝、曝光、互动指标并接入自己的报告流程
如何安装或部署这个 Agent？
作为 skill 安装：npx skills add gitroomhq/postiz-agent。作为 Claude Code 插件：/plugin marketplace add gitroomhq/postiz-agent 然后 /plugin install postiz@postiz-agent。作为 Cursor 插件：在 Customize 面板找到 postiz 并安装。同时需安装 CLI 并认证：npm install -g postiz，然后运行 postiz auth:login（OAuth2 设备流，凭证保存到 ~/.postiz/credentials.json）或 export POSTIZ_API_KEY=your_api_key_here。可选 export POSTIZ_API_URL=https://your-custom-api.com 指向自托管 API。
如何使用这个 Agent？
先运行 postiz integrations:list 获取集成 ID。基本排期：postiz posts:create -c "内容" -s "2024-12-31T12:00:00Z" -i "integration-id"。带媒体（必须先上传）：postiz upload img.jpg 取回 URL，再用 -m "$PATH" 传入。多平台：-i "twitter-id,linkedin-id,facebook-id"。线程：多次传 -c。平台特定设置用 --settings '{...}' 或 -- post.json。管理用 posts:list、posts:status、posts:settings、posts:delete；分析用 analytics:platform <id> 和 analytics:post <id>。所有命令均输出 JSON，可用 jq 解析。
这个 Agent 有哪些优点和局限？
- 所有命令输出 JSON 并提供动态发现流程（integrations:list → settings → trigger），Agent 无需硬编码平台知识即可适配不同平台
- 原生支持 28+ 平台，包括 Reddit flairs、YouTube 播放列表、LinkedIn 公司页、X 线程等平台特定设置
- 同时提供 Claude Code 插件、Cursor 插件、Grok Build 插件（含托管 MCP 服务器）和通用 skill 安装多种接入方式
- OAuth2 设备流认证无需手动管理 client secret，也支持 API Key 和自托管 API/auth 服务器
- 强依赖 Postiz 托管服务（api.postiz.com / cli-auth.postiz.com / mcp.postiz.com），自托管需额外按 server/SERVER.md 部署
- 媒体必须先通过
postiz upload上传换取可信 URL，外部链接会被 TikTok、Instagram、YouTube 拒绝，增加一步流程 - 帖子发布后无法修改设置（仅 DRAFT/QUEUE 状态可 patch），部分平台发布后不返回 post ID，需手动执行 posts:missing/posts:connect 才能启用分析
- GitHub 仓库 License 字段为 NOASSERTION，README 底部标注 AGPL-3.0，商用集成前需自行确认许可条款
- 需要 Node.js 环境和全局安装 CLI，AI Agent 必须能执行 shell 命令，纯网页聊天环境不可用
这个 Agent 与同类方案有什么区别？
README 将其定位为可被 Claude、OpenClaw 等 Agent 调用的 skill/插件，并打包了托管 MCP 服务器（https://mcp.postiz.com/mcp-oauth-dynamic）；与其他 AI 社媒工具的直接对比未在源中列出。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Postiz Agent CLI 当前 | 54 · 缺口较多 | 命令行工具免费版 + 付费版 | ★ 542 | 2 天前 | TypeScript | Claude Code |
| SwarmVault | 67 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 730 | 3 个月前 | TypeScript | Codex · Claude Code |
| OpenContext | 58 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.3k | 4 个月前 | JavaScript | Codex · Claude Code |
| LetsFG：航班与酒店AI智能体搜索预订平台 | 43 · 缺口较多 | 命令行工具免费版 + 付费版 | ★ 2.2k | 3 天前 | Python | Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
凭据范围限于 Postiz API，权限面相对收敛（least_privilege=2）；但 posts:create 默认即可定时公开发布，未见内置确认门控（user_confirmation=1）；API 端点表、环境变量和凭据存储位置均有披露，数据流透明（data_flow_transparency=2）；OAuth 凭据明文存于 ~/.postiz/credentials.，未见加密或权限加固说明（sensitive_data_handling=1）；依赖极少但无 lockfile 或依赖审计证据（dependency_security=1）；CLI 可直接对外部社交平台产生公开、持久的影响且默认即调度发布（external_effects=1）；提供 posts:status 退回草稿终止工作流、posts:delete 等回滚手段（rollback=2）；作者与上游 monorepo 链接清晰（source_attribution=2）。
README、命令表、API 端点表和快速参考之间未发现自相矛盾（self_consistency=2）；功能依赖托管服务（api.postiz.com、cli-auth.postiz.com、mcp.postiz.com），自托管路径存在但需额外服务器，可用性受外部服务制约（dependency_availability=1）；错误表和退出码约定清楚（failure_messages=2）。
明确面向开发者与 AI Agent，场景（调度、多平台、媒体）描述充分（audience_and_scenarios=2）；字符限制、平台差异、missing-post 解析流程等边界有文档（capability_boundaries=2）；SKILL.md 被引用但内容未在源文件中出现，触发精度无法核实（trigger_precision=1）；Node>=18、npm/pnpm 安装、多宿主插件清单，环境适配良好（environment_fit=2）。
文档分层清晰（README/SKILL/专项指南/examples）（information_architecture=2）；多种安装路径说明完整（install_notes=2）；CLI 名称 postiz 与包名、bin 一致（naming_stability=2）；示例丰富并配 workflow 脚本（examples_and_faq=2）；零散提到平台限制但无集中的已知限制章节（known_limitations=1）；LICENSE 文件为 AGPL-3.0 且与 package. 一致，尽管注册表元数据为 NOASSERTION（license=2）；版本 2.0.17 存在，CHANGELOG.md 在发布文件列表中但内容未提供（versioning_changelog=1）；维护指向上游 postiz-app 的 issues，但本仓库自身维护承诺不明确（maintenance_responsibility=1）。
全命令 JSON 输出便于管道和 Agent 消费（output_usability=2）；对 AI Agent 的发现式工作流（settings/trigger/discovery）是相对 API 裸调用的实质增值（marginal_value=2）；draft 模式、批量脚本等提供成本可控的路径（cost_benefit=2）。
“28+ 平台”等核心声明无法在所提供文件中逐项核实（claim_traceability=1）；除自身文档外无第三方佐证（cross_source_corroboration=1）；文档整体区分了事实说明与操作建议，但部分断言（如平台安全性理由）混合了营销性表述（fact_inference_separation=1）。
- 静态审查，未执行任何命令；所有结论仅基于所提供的文件。
- posts:create 默认即定时发布到公开平台，Agent 误操作会直接对外产生公开影响；建议先用 -t draft 并人工确认后再调度。
- OAuth 凭据以明文 JSON 存于 ~/.postiz/credentials.，注意文件权限与机器安全。
- 功能强依赖 Postiz 托管服务（API、OAuth、MCP），服务变更或中断会直接影响可用性。
- README 引用的 SKILL.md 内容不在本次审查文件中，Agent 端行为规范未能核实。
- registry 元数据 license 为 NOASSERTION，与仓库内 AGPL-3.0 不一致，使用前请自行核对。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Added - upload --adjust - Adjust the uploaded file to the platforms' limits (videos scaled to 1080p and re-encoded to H.264 MP4 with AAC audio, oversized images scaled down). Off by default. Wait until media:status returns ready before publishing a post with the returned path, or the post uses the original file. - media:status <id> - Check a file uploaded with --adjust via GET /public/v1/media/:id/status: processing until the adjusted file is in place, ready after, and ready with a warning when the adjustment failed and the original is kept.在 GitHub 查看 ↗ -
发布说明摘录
Changed - README.md: document media:list (media section, API endpoint table and quick reference) and add CONTRIBUTING.md with the pull request checklist (version bump, changelog entry, docs and release steps), linked from the README.在 GitHub 查看 ↗ -
发布说明摘录
Fixed - npm publish workflow: pnpm publish ran the publish script in package.json as a lifecycle hook right after publishing, which started a second publish that failed with E409. The script is renamed to publish-cli (docs updated) so the workflow publishes once. Changed - PUBLISHING.md: the release steps now include the gh release create command.在 GitHub 查看 ↗
常见问题
必须使用 Postiz 的托管服务吗？
如何认证？OAuth2 和 API Key 有什么区别？
postiz auth:login 走 OAuth2 设备流，无需 client secret，凭证存于 ~/.postiz/credentials.json；也可以 export POSTIZ_API_KEY=...。两者同时存在时 OAuth2 凭证优先。发布带图片或视频的帖子有什么限制？
postiz upload 上传文件（支持 PNG/JPG/JPEG/GIF 和 MP4）获取 Postiz URL，再在 -m 参数中使用；TikTok、Instagram、YouTube 只接受受信域名的 URL，直接传外部链接会被拒绝。帖子发布后还能修改吗？
posts:settings 做合并式 patch，已发布帖子会被拒绝；posts:status 可在草稿和排期间切换，切回草稿会终止正在运行的发布流程。分析数据显示 {"missing": true} 怎么办？
postiz posts:missing <post-id> 列出平台内容，再用 postiz posts:connect <post-id> --release-id "<内容ID>" 关联后，分析即可正常工作。