Orshot-HQ/orshot-openclaw

Orshot 社交媒体调度器：渲染、发布、调度、学习

Orshot 通过一个请求即可从模板渲染图像、轮播或视频，并将其发布到 13 个以上平台。它还管理草稿、调度、编辑和报告分析数据，因此代理无需借助第二个工具就能运行整个内容日历。帖子也可以附加任何公开的媒体 URL，因此它可以与其他工具生成的图像配合使用。

支持的平台：X (Twitter)、Instagram、Facebook、LinkedIn（个人主页和公司页面）、TikTok、YouTube、Pinterest、Reddit、Bluesky、Threads、Telegram、Snapchat、Google Business。

第一步：连接 Orshot MCP 服务器

在此之前什么都不会工作。MCP 路由无需粘贴密钥，将每个帖子显示为可视化卡片，是代理应使用的路由。

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth
openclaw mcp login orshot

Claude Code：claude mcp add --transport http orshot https://mcp.orshot.com/mcp。其他 MCP 客户端使用相同的 URL。

仅用于无头任务（cron、n8n、服务器脚本）：export ORSHOT_API_KEY=... 并使用 Authorization: Bearer $ORSHOT_API_KEY 调用 REST API。

第二步：检查已连接的账户

orshot_list_social_accounts            # MCP
GET /v1/social/accounts?include_health=true   # REST
# [{ "id": 1, "platform": "linkedin", "account_name": "Acme", "account_username": "acme", "health": { "status": "ok" } }]

返回包含账户的列表意味着你可以发布帖子。注意每个账户的数值 id 和任何表示需要重新连接的 health 标志。

空列表意味着用户仍需手动连接账户。 API 无法自行连接账户。引导用户前往其 Orshot 控制面板：工作区 > 社交 > 账户（https://orshot.com/dashboard，然后点击工作区的社交部分），每个平台通过其自己的 OAuth 登录进行连接。社交发布是付费计划上的附加功能，每个已连接账户每月 12 美元，发布帖子不额外消耗配额；免费计划无法连接账户。计划及附加功能详见 https://orshot.com/pricing。请直白说明一次，然后等待用户返回；下一次调用 orshot_list_social_accounts 将显示新账户。

核心工作流

1. 连接并列出账户（如上所述）。
2. 确定媒体内容。 从模板渲染（templateId + modifications）或使用已有的 media_url。
3. 先创建草稿。 除非用户明确说明要立即发布，否则以 status: "draft" 创建帖子。
4. 向用户展示预览、标题、账户和时间。通过 MCP 的 orshot_get_social_post 渲染一个可视化卡片。
5. 编辑用户修改的内容（orshot_update_social_post），然后发布（orshot_publish_social_draft）或调度（status: "scheduled" + scheduled_for）。
6. 检查状态在异步平台（Instagram、TikTok）完成后：processing 变为 published 或 failed。
7. 阅读分析数据一天后，以及下次调度前的最佳发布时间洞察。

MCP 工具映射

任务	工具
列出账户	orshot_list_social_accounts
一次性渲染并发布	带 publish 参数的 orshot_render_template
发布媒体 URL	orshot_publish_social_post
列出/读取帖子	orshot_list_social_posts, orshot_get_social_post（可视化卡片）
编辑/发送/丢弃	orshot_update_social_post, orshot_publish_social_draft, orshot_discard_social_post
分析数据	orshot_get_social_analytics, orshot_get_social_analytics_daily, orshot_get_social_followers, orshot_get_social_post_analytics
最佳发布时间	orshot_get_best_time_to_post

MCP 服务器默认使用 status: "draft"，除非用户明确要求发布。请保持此设置。

关键调用

一次性渲染并发布（或草稿，或调度）

通过 MCP，这由带相同 publish 对象的 orshot_render_template 实现。

await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    templateId: 123,
    modifications: { headline: "发布日", stat: "2,000 次渲染" },
    response: { type: "url", format: "png" },
    publish: {
      accounts: [1, 3],
      content: "最长 5000 个字符的标题",
      status: "scheduled",               // published | draft | scheduled
      scheduled_for: "2026-11-01T14:00:00Z",
      timezone: "America/New_York",
      platformOptions: {
        "3": { firstComment: "https://orshot.com", disableLinkPreview: true }, // LinkedIn
      },
    },
  }),
});

多页模板在支持轮播的平台上以轮播形式发布。响应包含 data.content（渲染结果）和 publish[]（每个账户对应一个条目）。

发布已拥有的媒体

使用 orshot_publish_social_post，或：

curl -s -X POST https://api.orshot.com/v1/social/publish \
  -H "Authorization: Bearer $ORSHOT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "accounts": [2],
    "content": "没人告诉你的六件事",
    "media_urls": ["https://.../1.png", "https://.../2.png", "https://.../3.png"],
    "status": "draft",
    "tiktokSettings": { "autoAddMusic": true }
  }'

字段	说明
accounts	必填，数值 ID
content	标题，最多 5000 个字符
media_url / media_urls	一个或多个公开 URL；多个 URL 表示轮播
status	published（REST 默认值）、draft、scheduled
scheduled_for	ISO 8601 格式，至少提前 60 秒，仅在 scheduled 状态下有效
timezone	IANA 时区名称
platformOptions	按账户 ID 设置：LinkedIn 的 firstComment、disableLinkPreview；Pinterest 的 title、link
tiktokSettings.autoAddMusic	根级别，TikTok 照片轮播

响应：{ post_id, status, platforms: [{ account_id, platform, status, url, error, action }] }。status 可为 published、scheduled、drafted、partial、processing 或 failed。action: "reconnect" 表示用户必须在控制面板中重新连接该账户。

管理已保存的帖子

GET    /v1/social/posts?status=draft&limit=25        # 也可使用 scheduled | published | processing | partial | failed，以及 platform=、account_id=、cursor=
GET    /v1/social/posts/:id
PATCH  /v1/social/posts/:id                          # content、media_urls、accounts、status (draft|scheduled)、scheduled_for、timezone、platformOptions
POST   /v1/social/posts/:id/publish                  # 立即发送已保存的帖子
POST   /v1/social/posts/:id/sync                     # 刷新提供商状态
DELETE /v1/social/posts/:id                          # 丢弃；一旦任何账户已发布则拒绝

每个帖子上的 is_editable 和 is_discardable 告诉你哪些操作仍然允许。编辑不会重新渲染且不产生费用。

分析数据

GET /v1/social/analytics?platform=linkedin&source=orshot      # 每篇帖子：展示次数、互动、点击、互动率；每个账户的粉丝数
GET /v1/social/analytics/daily?from=2026-10-01&to=2026-10-21  # 逐日数据
GET /v1/social/analytics/accounts?from=2026-09-01             # 每个账户的粉丝历史与增长
GET /v1/social/analytics/insights?platform=instagram          # 最佳日期与小时时段 (UTC)、发布频率与互动率、衰减

source 可为 all、orshot 或 external（从平台同步的帖子，因此存有历史数据）。refresh=1 可绕过缓存。预算：每分钟 10 次分析请求。洞察功能需要发布历史记录，因此新账户会返回空时段。

常见模式

模式 1：每周内容日历（草稿形式）

使用不同的 modifications 从一个模板渲染七篇帖子，每篇以 status: "draft" 创建，通过 orshot_list_social_posts 为用户列出，然后发布或调度已批准的帖子。每次更改标题或时间只需一次更新。

模式 2：在最佳时间调度

为平台调用 orshot_get_best_time_to_post，获取排名最高的时段（UTC），转换为用户的时区，然后作为 scheduled_for 传入。如果时段为空，询问用户的时间，而不是自行编造。

模式 3：跨平台发布，所有平台，特定平台附加功能

一个包含所有 ID 的 accounts 数组。将链接放入 platformOptions[<linkedin id>].firstComment，为 Pinterest 放入 title 和 link，为 TikTok 照片帖子放入 tiktokSettings.autoAddMusic。确保 content 不超过目标平台中最短的限制（X 的限制最严格）。

模式 4：多页模板轮播

使用 pageN@ 键渲染一个 5 到 10 页的模板，并添加 publish 参数。Orshot 会上传每一页，并在 Instagram、LinkedIn、TikTok（照片模式）、Threads 和 Bluesky 上以轮播形式发布。orshot-carousel 技能包含 6 张幻灯片的公式。

模式 5：从结果中学习

每日：使用 source: "orshot" 调用 orshot_get_social_analytics，按互动率排序，保留排名前四分之一的钩子风格，丢弃排名后四分之一，撰写下一周的草稿。记录所做的更改，以便用户查看日志。

模式 6：恢复失败

partial 或 failed 且带 action: "reconnect"：告诉用户在控制面板（工作区 > 社交 > 账户）中重新连接哪个账户，将帖子保留为草稿，在用户确认后使用 orshot_publish_social_draft 重试。任何其他 error：逐字显示；不要盲目重试。

安全规则

• 在未获得用户对该帖子的明确许可前，绝不发布。"准备"、"草稿"、"向我展示" 意味着 status: "draft"。
• 在发送前，复述精确的账户（平台和用户名）、标题和时间。
• 不要丢弃用户未要求你丢弃的帖子。
• 在建议用户连接更多账户前，提及每个账户每月 12 美元的附加功能费用一次。
• 在 REST 使用中，将 API 密钥保存在环境中。切勿回显它。

常见陷阱

1. 账户 ID 是数值且每个账户独立。 两个 LinkedIn 账户有两个不同的 ID。通过 ID 发布，切勿通过平台名称发布。
2. PDF 无法在任何平台发布。 渲染为 png、jpg 或 webp（视频平台用 mp4）。
3. TikTok 和 YouTube 需要视频，不接受单张图片。 TikTok 接受照片轮播（多张图片）。Google Business 只接受图片。
4. scheduled_for 提前不足 60 秒会被拒绝，并且与 draft 或 published 状态不兼容。
5. Instagram 和 TikTok 异步发布。 processing 不是失败。在报告前，请同步或重新读取帖子。
6. 发布失败绝不意味着渲染失败。 即使渲染成功，也要读取 publish[]。
7. 媒体 URL 必须公开可访问。 Orshot 渲染 URL 是公开的。签名 URL 或 localhost URL 不是。
8. 超过 5000 个字符的标题会被拒绝。 平台限制更短；X 是最短的。
9. 分析请求上限为每分钟 10 次，涵盖所有分析端点。
10. 免费计划工作区无法连接账户。 在 /social/* 上返回 403 并附带计划相关消息是计费状态问题，而非认证错误。请引导用户访问 https://orshot.com/pricing。

快速参考

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth && openclaw mcp login orshot

GET    /v1/social/accounts?include_health=true   # orshot_list_social_accounts
POST   /v1/studio/render            # + publish: { accounts, content, status, scheduled_for, timezone, platformOptions, tiktokSettings }   orshot_render_template
POST   /v1/social/publish           # { accounts, content, media_url | media_urls, status, scheduled_for, timezone, platformOptions, tiktokSettings }   orshot_publish_social_post
GET    /v1/social/posts?status=draft             # orshot_list_social_posts
GET    /v1/social/posts/:id                      # orshot_get_social_post
PATCH  /v1/social/posts/:id                      # orshot_update_social_post
POST   /v1/social/posts/:id/publish              # orshot_publish_social_draft
POST   /v1/social/posts/:id/sync
DELETE /v1/social/posts/:id                      # orshot_discard_social_post
GET    /v1/social/analytics                      # orshot_get_social_analytics
GET    /v1/social/analytics/daily?from=&to=      # orshot_get_social_analytics_daily
GET    /v1/social/analytics/accounts?from=       # orshot_get_social_followers
GET    /v1/social/analytics/insights?platform=   # orshot_get_best_time_to_post

文档：https://orshot.com/docs/publish/introduction.md，https://orshot.com/docs/api-reference/social-publish.md，https://orshot.com/docs/api-reference/social-posts-list.md。渲染详情见 orshot 技能。