Orshot-HQ/orshot-openclaw

Orshot 社群媒體排程器：渲染、發布、排程、學習

Orshot 可從模板渲染一張圖片、輪播或影片，並在一次請求中發布到 13 個以上的平台。它還管理草稿、排程、編輯和報告分析數據，讓代理無需使用第二個工具即可運行整個內容日曆。貼文也可以附加任何公開的媒體 URL，因此也適用於在其他地方製作的圖片。

平台：X (Twitter)、Instagram、Facebook、LinkedIn（個人檔案和粉絲專頁）、TikTok、YouTube、Pinterest、Reddit、Bluesky、Threads、Telegram、Snapchat、Google Business。

步驟 1：連接 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。

步驟 2：檢查已連接的帳戶

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
一次渲染並發布	orshot_render_template 搭配 publish
發布媒體 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，這是 orshot_render_template 並帶入相同的 publish 物件。

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: "Ship day", stat: "2,000 renders" },
    response: { type: "url", format: "png" },
    publish: {
      accounts: [1, 3],
      content: "Caption up to 5000 chars",
      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": "Six things nobody tells you",
    "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@ 鍵和 publish 渲染一個 5 到 10 頁的模板。Orshot 會上傳每一頁，並在 Instagram、LinkedIn、TikTok（圖片模式）、Threads 和 Bluesky 上發布為輪播。orshot-carousel 技能提供了 6 張幻燈片的公式。

模式 5：從結果中學習

每日：使用 source: "orshot" 呼叫 orshot_get_social_analytics，按互動率排序，保留前 25% 的貼文鉤子風格，丟棄後 25%，然後撰寫下週的草稿。記錄下變更的內容，以便使用者可以閱讀日誌。

模式 6：復原失敗

partial 或 failed 並帶有 action: "reconnect"：告訴使用者需要在儀表板（工作區 > 社群 > 帳戶）中重新連接哪個帳戶，將貼文保留為草稿，並在使用者確認後使用 orshot_publish_social_draft 重試。對於任何其他 error：如實顯示錯誤訊息；不要盲目重試。

安全規則

• 在沒有獲得該貼文明確許可的情況下，絕不發布。「準備」、「草稿」、「讓我看」意味著使用 status: "draft"。
• 在發送前，務必向使用者複述確切的帳戶（平台和使用者名稱）、標題和時間。
• 不要捨棄使用者未要求捨棄的貼文。
• 在建議使用者連接更多帳戶之前，先提及每個帳戶每月 12 美元的附加元件費用一次。
• 透過 REST API 時，將 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 技能中。