SosoAPI 設定指南

選擇起點

SosoAPI 為您慣用的 agent 提供一個連接社群帳戶的入口。Agent 協助寫作及檢閱，SosoAPI 處理受支援的帳戶操作、排程與發佈結果。您也可以在 App 檢閱同一批貼文，或從自己的程式碼呼叫 API。

本指南從一位使用者與一個社群帳戶開始，帶您連接本機或託管 MCP 用戶端、選擇權限、核對社群帳戶、準備及核准貼文，再讀取實際結果。進階實作涵蓋 CLI 與 HTTP API。設定本身不需要測試貼文。

• 讓 Claude Code 或 Codex 處理設定：步驟 1
• 自行設定 MCP 用戶端：步驟 3
• 使用終端機或後端：步驟 9
• 修復連線：步驟 10

開始前

您需要支援 MCP 的 AI 用戶端、SosoAPI 帳戶，以及您有權管理的社群帳戶。開啟登入頁面時即可建立 SosoAPI 帳戶。請先想好一份真實內容。

本機 MCP 需要 Node.js 20 或更新版本、npm/npx，以及您選擇的 AI 用戶端。託管 MCP 需要用戶端支援 remote MCP、OAuth 及自動用戶端註冊，不必在本機安裝 Node.js。用戶端功能可能受方案及管理員設定影響。

SosoAPI 可連結 Instagram、Threads、Facebook Pages、YouTube 和 X。請選擇帳戶類型、權限及貼文格式符合任務的帳戶。符合資格的 Threads 帳戶適合用作第一個純文字範例。Instagram 和 YouTube 的受支援發佈格式需要合適的媒體。平台出現在連線選單中，不代表每個帳戶都能執行所有操作。

設定時請檢查個別帳戶的能力。批次排程前，先在 App 查看目前方案與配額；X 另有組織共用的點數額度。某平台的範例不代表其他平台也支援。

• 支援的平台
• 發佈功能與帳戶要求

1. 將設定要求交給 agent

請貼入目前的 Claude Code 或 Codex 對話。

Agent 應先檢查並沿用正常運作的 SosoAPI 連線。若沒有，再依設定指引處理，並告知何時需要瀏覽器登入或重新啟動用戶端。預期結果是目前對話可使用 SosoAPI 工具；只有安裝訊息並不足以證明。請繼續登入及核對帳戶，或依步驟 3 手動設定。

按照 https://sosoapi.ai/setup.md 設定 SosoAPI。保留我目前的內容和任務。我會在需要時登入並核准存取。設定期間不要發布任何內容。

2. 登入並選擇 agent 的存取權限

請使用預期帳戶，選擇透過 Google 繼續，或以電子郵件註冊並完成驗證。完成畫面上的帳戶或工作區設定。若隸屬多個工作區，請選擇預期品牌或專案。核准前檢閱要求的工作區與操作，再返回同一段對話。

請保留 agent 提供的登入連結，讓瀏覽器能返回待核准的授權流程。您可以先從 App 開始，再返回 agent。請勿將待核准連結換成其他登入連結。

工作區角色與平台權限仍然適用：agent 有發佈權限，不會讓檢視者變成編輯者。發佈權限在您授予的範圍內持續有效；SosoAPI 不會強制每篇貼文重新經過瀏覽器核准。請告知 agent 何時暫停供您檢閱內容。一般 OAuth 設定不需要將社群密碼或 API key 貼給 agent。

預期結果：使用正確身分完成登入，agent 能取得您已授權的工作區。如果開啟錯誤的瀏覽器設定檔，請參閱疑難排解。

• 從 SosoAPI App 開始

3. 必要時手動連接 agent

請選擇一種連線方式。如果 agent 已設定好且能正常使用，請略過本節。本機 MCP 請先檢查 Node.js 與 npx；Node.js 必須為 20 或更新版本。

node --version
npx --version

本機 MCP：Claude Code 或 Codex

請只執行所用用戶端對應的指令：第一條適用於 Claude Code，第二條適用於 Codex。core 設定檔涵蓋日常發佈流程。設定檔只改變顯示的工具，不會授予權限；已有正常運作的 full 設定檔連線時請保留。

用戶端要求時請重新連線或重新啟動，再確認目前對話可使用 SosoAPI 工具。需要時，首次認證呼叫會啟動瀏覽器登入。

claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi

其他本機 MCP 用戶端

使用 mcpServers JSON 的用戶端，請將此項目加入既有設定並保留其他伺服器。採用其他設定格式時，請在用戶端的 MCP 設定中提供相同指令、引數及環境變數。

{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}

• 安裝參考與套件選擇

託管 MCP：相容的瀏覽器或遠端用戶端

請在用戶端的自訂連接器或 remote MCP 設定中，使用下方伺服器網址新增名為 SosoAPI 的連線。如有提供，請選擇 OAuth 與自動用戶端註冊。登入 SosoAPI、選擇允許的工作區與操作，再返回對話；用戶端要求時啟用連線，並請 agent 檢查已授權帳戶。

新的託管連線請使用 https://sosoapi.ai。 舊端點 https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp 仍然受支援。請保留正常運作的本機或託管連線，不必只為更換網址而重新設定。

不必貼上 API key、client ID 或 client secret。ChatGPT 自訂 MCP app 取決於用戶端方案、開發者模式及管理員設定。這些步驟說明的是自訂連線，而非應用程式目錄上架。託管 MCP 無法讀取本機檔案；請使用公開網址匯入，或透過本機 MCP 上傳本機檔案。

https://sosoapi.ai

• 自訂 OAuth 用戶端註冊及 token 指引

選用：在終端機檢查登入

本機連線請先執行 auth status，只有在顯示未登入時才執行 auth login。完成瀏覽器流程後再次檢查狀態。系統不會列印 token。這僅檢查本機 CLI 認證，不代表另一個託管連接器的登入狀態。

npx -y sosoapi auth status

npx -y sosoapi auth login

4. 連結社群帳戶

請開啟「連結帳戶」，或使用下方本機指令。視需要將 threads 換成 instagram、facebook、youtube 或 x。這只會開啟連線流程，不會發佈內容。

請核對畫面上的組織與工作區。選擇平台，透過其授權頁面登入，並選取確切的帳戶、Page 或頻道。完成同意授權，返回時完成必要的帳戶選擇確認，再請 agent 重新讀取預期工作區的已連結帳戶。

請沿用健康的既有連線。如果它屬於其他組織或工作區，請在 App 中釐清選擇；一般設定不應將它中斷或移動。預期結果是正確帳戶出現在預期工作區，並顯示目前的連線健康狀態及能力資訊。僅回呼成功無法證明具有發佈權限。

npx -y sosoapi connect threads

• 連結帳戶

5. 不發佈，先驗證存取權限

請將下列內容貼入已連線的 agent 對話。

Agent 可以使用 sosoapi_get_workspace_context 和 sosoapi_list_connected_accounts、沿用已知資訊，並明確傳入所選 workspace_id。帳戶初始化可能建立您的第一個工作區，但這項設定檢查不會建立社群貼文。

繼續之前，請確認工作區與發佈對象、您的角色與 agent 權限，以及目的帳戶是否支援擬用格式。檢查失敗時請參閱疑難排解；重新安裝套件無法補足缺少的平台權限。

請檢查我的 SosoAPI 設定，不要發佈或排程任何內容。
請列出我可使用的工作區，以及我所選工作區中的社群帳戶。
針對我選擇的帳戶，請顯示平台、帳戶名稱、連線健康狀態，以及擬用格式的發佈能力。
如果有多個工作區或帳戶可能符合，請先問我要使用哪一個。
請將內部 ID 留供工具呼叫使用，不要要求我尋找或虛構 ID。

6. 準備並核准第一篇貼文

請從一篇真實貼文與一個發佈對象開始，先替換草稿提示中的方括號欄位。Agent 負責寫作，SosoAPI 提供連線及發佈操作。請自行檢查內容主張、拼字、連結及媒體。

未來貼文請明確指定日期、當地時間及 IANA 時區。如果日光節約時間造成當地時間有歧義，請在提交前選定所指的那一次。此階段的預期結果是提供確切草稿供您檢閱，尚未提交發佈請求。

請用 SosoAPI 協助我準備一篇產品公告。

產品：[public product name]
已核實事實：[what is available today]
目標讀者：[who this helps]
發佈對象：[account label and platform]
語言：[language]
希望的當地日期與時間：[YYYY-MM-DD HH:mm]
時區：[IANA timezone, for example Asia/Hong_Kong]
媒體：[none, a local file, or a public media URL]

請只使用我提供的事實，並檢查發佈對象的格式要求。
請列出確切的草稿、媒體、發佈對象、日期、時間與時區供我檢閱。
請先不要排程或發佈。

核准完整貼文後再排程

所有資料正確後，請使用下方提示明確下達指示。這會建立可能公開發佈的真實排程，請只使用您確實要發佈的內容與帳戶。即時發佈也需要先核對同樣資料，再明確要求執行。

預期結果：Scheduled Post ID、預期發佈對象、受理時間及目前狀態。排程受理不代表平台已經發佈。

請將下方已核准的完整貼文，依指定日期、時間及時區排程至指定帳戶。

[貼上最終內容、媒體、發佈對象、日期、時間與時區。]

請先檢查是否已有相符排程。只提交一次貼文，然後讀回已儲存結果，回報 ID、發佈對象、受理時間及目前狀態。結果不明時，請先檢查既有請求，再採取其他操作。

7. 檢查結果、重新排程或取消

請 agent 使用 sosoapi_get_scheduled_post 讀取同一篇 Scheduled Post。您也可以開啟 https://app.sosoapi.ai/scheduled-posts/<post-id> 並以已授權帳戶登入。當請求包含多個帳戶時，請分別核對每個發佈對象；部分可能成功，其他仍需處理。

請讀取 Scheduled Post [returned ID] 的目前結果。
請列出發佈對象、排程時間、目前狀態及發佈結果。
確認已發佈時，如有公開連結，請一併提供。
請勿重試、重新排程或建立另一篇貼文。

管理待處理貼文，並稍後返回查詢

若要修改待處理貼文，請提供 ID 和新資料。Agent 必須先讀取目前版本及可用操作，才能執行受支援的更新或取消。能否取消取決於傳送階段，開始傳送後可能無法再取消。取消排程不會移除平台上已發佈的貼文。

取得未來排程的已儲存資料後，您可以離開對話，稍後再查同一篇貼文。除非另行設定，關閉的 agent 對話不會保證自行喚醒或通知您。

8. 加入圖片或影片，再重用流程

準備較大批次之前，請先確認單篇貼文流程能正常運作。告知 agent 媒體是本機檔案、公開網址，還是既有的 SosoAPI 素材。

本機檔案可透過本機 MCP 的 sosoapi_upload_asset 上傳。檔案必須位於允許的上傳資料夾；路徑超出範圍時，工具會說明允許的位置。託管 MCP 無法讀取您電腦上的檔案。

公開網址請先使用 sosoapi_import_asset_url，再以 include_asset=true 查詢 sosoapi_get_asset_import_status，等待素材就緒。使用既有素材前，請確認它屬於預期的工作區，並已適用於所選格式。

一般排程請求必須同時使用已註冊的素材 ID 與正式素材 URL，不能以暫時預覽網址或原始外部網址代替。受支援的單張圖片網址流程可用 sosoapi_post_image_url 合併匯入與提交。這是發佈操作，請先核准完整貼文。處理期間請保留已受理的貼文 ID，不要為了繼續而另開匯入。

X 支援不含媒體的原創 TEXT 貼文，或僅含一個已就緒、已註冊 MP4 影片素材的 VIDEO。影片至少須為 0.5 秒，並在 500 MiB 上傳限制內。影片必須具備該帳戶已驗證的 can_publish_video，僅有文字權限並不足夠。舊連線可能需要您核准重新連線以取得影片上傳權限。文字、hashtag 及連結仍須符合 X 的加權字數限制。不支援相片、回覆、引用、轉發及串文發佈。受理上傳或影片處理不等於發佈完成。

提交至 X 前，請以預期 workspace_id 與最終文字讀取 sosoapi_get_x_usage。其額度與成本獨立於一般方案配額。請勿透過重複提交繞過點數限制；發佈結果不明時，請先核實再傳送。

準備待審批次並如實讀取成效

第一篇貼文成功後，可嘗試下方的產品發布提示。核准完整表格後，請依方案限制檢查整批內容。分別回報已受理與遭拒的發佈對象，並保留每篇已受理貼文的識別資訊。

發佈與分析的存取權限可能不同。之後檢視成效時，無法取得的指標應標示為無法取得。不要捏造零值，也不要因為貼文已發佈就推斷所有指標都能讀取。

請沿用相同的已驗證設定，依我提供的公開事實準備七篇產品公告草稿，每天一篇。請用檢閱表逐列列出草稿、發佈對象、媒體、當地日期、時間與時區。在我核准完整表格前，請將七篇全部保留為草稿。

9. CLI 與 API 實作步驟

需要明確的請求檔案或後端整合時，可使用這條選用路線。Agent 使用者可略過。範例使用與 MCP 相同的帳戶、工作區及發佈權限。

請先查閱已安裝套件的說明與內建合約；檢查合約不需要登入。它會列出套件附帶的操作及 schema。請使用其欄位名稱，不要套用其他供應商的請求格式。

npx -y sosoapi --help
npx -y sosoapi api contract --summary
npx -y sosoapi api contract --route /studio-api/scheduled-posts/

CLI：首次讀取已認證的工作區資訊

請先完成 auth login，再使用文字編輯器將下列 JSON 儲存為 workspaces.json，然後執行指令。請透過檔案傳入請求本文，不要將內容直接插入 shell 指令。

CLI 會回傳 schema_version、http_status 及 body。成功回應包含 body.active_workspace_id 和 body.workspaces。請從回應中選擇預期工作區；目前啟用的工作區不會自動決定新任務的對象。新帳戶的首次呼叫可能初始化其第一個工作區。

請檢查 http_status 和 body，而非僅查看 shell 結束碼。即使 API 操作未成功，指令仍可能回傳 HTTP 錯誤封套。

{}

npx -y sosoapi api post /identity-api/workspace/list < workspaces.json

CLI：選取已連結的社群帳戶

請以您帳戶回傳的工作區 ID 儲存 accounts.json，再執行指令。從 body.accounts 選取預期帳戶。排程使用的 social_account_id 是 SosoAPI 帳戶 ID，不能以使用者名稱或平台的 Page ID 代替。

{
  "workspace_id": "<YOUR_WORKSPACE_ID>"
}

npx -y sosoapi api post /identity-api/user/social-accounts/list < accounts.json

CLI：為一篇已核准的 Threads 文字貼文排程

這是請求範本，不是可直接執行的貼文。請使用檔案編輯器儲存 post.json，將每個方括號值換成您已授權的資料。未來的 ISO 時間戳記必須有明確 UTC 偏移，或以 Z 表示 UTC。display_timezone 是顯示用的 IANA 時區，不會自動補全有歧義的當地時間戳記。

請產生唯一的 idempotency_key，例如 UUID，並連同完整請求本文保留。重試相同請求時請使用相同金鑰；回應延遲不是另建金鑰的理由。修改後的貼文屬於另一個請求，請先檢查原始結果，再選用新識別資訊。

確認內容、帳戶、時間、權限及目前配額後，再執行 create 指令。這會建立真實貼文排程。受理後請保留 body.post.id，並讀取 body.post.status、body.post.scheduled_at 及 body.post.destination。body.deduped 表示是否重用了既有請求。受理不等於平台已確認發佈。

{
  "workspace_id": "<YOUR_WORKSPACE_ID>",
  "social_account_id": "<YOUR_THREADS_ACCOUNT_ID>",
  "caption": "<YOUR_APPROVED_POST_TEXT>",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<FUTURE_ISO_8601_TIME_WITH_OFFSET>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<NEW_STABLE_REQUEST_KEY>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/create < post.json

CLI：讀取已儲存貼文及其結果

請以回傳的 ID 儲存 post-status.json，讀取 body.post、body.delivery、body.actions 及 body.outcomes，確認發佈完成後才回報成功。如果 create 回應遺失，請用保留的識別資訊找回原始請求，不要以新金鑰建立另一個排程。

{
  "id": "<RETURNED_POST_ID>"
}

npx -y sosoapi api post /studio-api/scheduled-posts/get < post-status.json

CLI：僅在目前結果允許時取消

如果最新讀取結果允許取消，而且您確實要取消，請將回傳 ID 與目前數值 body.post.version 存入 cancel.json。範例中的 1 僅供說明，請換成剛讀取的版本，再執行指令並確認結果。

版本已變更或無法取消時，請重新讀取同一篇貼文，使用實際可用操作。請勿繞過版本衝突，或將取消誤認為刪除已發佈貼文。

{
  "id": "<RETURNED_POST_ID>",
  "expected_version": 1
}

npx -y sosoapi api post /studio-api/scheduled-posts/cancel < cancel.json

HTTP：從自己的後端呼叫

伺服器端整合請在 Connection → API 建立 API key，並將密鑰儲存在伺服器的機密設定中。目前畫面只要求名稱，沒有工作區或能力選擇器。使用者建立的金鑰預設可在其所有可存取的工作區執行 operate、publish 及 engage。請核對此授權範圍是否適合您的整合。API 合約亦支援明確限制 capabilities 與 workspace_ids 的金鑰。

一般 agent 設定使用 OAuth，不需要這個 API key 步驟。範例中的 SOSOAPI_ACCESS_TOKEN 是您伺服器端用來存放金鑰的示例變數，不是 SosoAPI CLI 設定。CLI 可選的個人存取權杖變數為 VICKY_API_KEY。

請使用上方的 workspaces.json。直接呼叫 HTTP 會回傳端點本文，不含 CLI 的 http_status/body 封套；請讀取實際 HTTP 狀態及 JSON。憑證應留在後端，不要放入瀏覽器程式碼、提示、螢幕擷取畫面或共用請求檔案。

將社群帳戶連線嵌入您提供給客戶的產品，是另一項整合工作。這份單帳戶實作不代表客戶導入流程已準備就緒。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${SOSOAPI_ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @workspaces.json \
  'https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/workspace/list'

• 管理 API key：Connection → API
• API 參考
• API key 建立與明確授權範圍
• 驗證與權限
• CLI 參考

10. 疑難排解

請根據實際錯誤及正在診斷的連線處理。擴大權限或重複提交無法修復所有失敗。

更新、撤銷存取權限或尋求協助

下方第一條指令可在不啟動 MCP 伺服器的情況下查閱最新套件說明。如果用戶端儲存的指令固定了版本，請明確更新該指令。更新另一份全域安裝不會更新用戶端固定使用的版本。

撤銷本機裝置權限時，請使用 Connection → Agent 或下方的 auth logout 指令。託管連接器請在 Connection → Agent 撤銷對應授權。API key 另由 Connection → API 管理。撤銷 agent 存取權限不會取消已受理的排程，請另外管理這些貼文。

需要協助時，請提供用戶端與套件版本、失敗步驟、顯示的錯誤及時間／時區。必要時再私下向支援提供相關請求或貼文 ID。請勿傳送憑證、授權連結，或可能含有 token 的原始記錄。

npx -y sosoapi@latest --help

npx -y sosoapi auth logout

• 管理 agent 用戶端：Connection → Agent
• 管理 API key：Connection → API
• 疑難排解參考
• 聯絡 SosoAPI 支援

設定完成檢查清單

不提交貼文也能完成連線設定。如果您有發佈，請另外檢查結果，確認首次發佈流程已完成。

• 我的用戶端能使用 SosoAPI 工具，或 CLI/API 能執行已授權請求。
• 我已使用預期的帳戶登入，並選取正確工作區。
• 我的社群帳戶已顯示，並具備任務所需能力。
• 我了解 agent 只能準備工作，還是也能排程與發佈。
• 我可以準備草稿，並檢閱確切的發佈對象、內容和時間。
• 如果我已提交貼文，已保留其 ID，並能區分受理與確認發佈。
• 我知道如何檢查失敗原因、管理待處理排程及撤銷存取權限。