# SosoAPI 設定指南

標準 URL： https://sosoapi.ai/zh-tw/docs/setup-guide

連接您的 AI agent、連結社群帳戶，並準備第一篇貼文。

<a id="choose-your-starting-point"></a>

## 選擇起點

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

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

- [讓 Claude Code 或 Codex 處理設定：步驟 1](#1-give-your-agent-the-setup-request)

- [自行設定 MCP 用戶端：步驟 3](#3-connect-your-agent-manually-if-needed)

- [使用終端機或後端：步驟 9](#9-cli-and-api-walkthrough)

- [修復連線：步驟 10](#10-troubleshooting)

<a id="before-you-start"></a>

## 開始前

您需要支援 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 另有組織共用的點數額度。某平台的範例不代表其他平台也支援。

- [支援的平台](https://sosoapi.ai/zh-tw/docs/supported-platforms)

- [發佈功能與帳戶要求](https://sosoapi.ai/zh-tw/docs/publishing-capabilities)

<a id="1-give-your-agent-the-setup-request"></a>

## 1. 將設定要求交給 agent

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

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

> 請依下列指引設定 SosoAPI： https://sosoapi.ai/setup.md. 請保留我目前的內容與任務。需要時我會登入並核准授權。設定期間請勿發佈任何內容。

<a id="2-sign-in-and-choose-your-agents-access"></a>

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

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

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

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

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

依任務選擇存取權限

| 權限選擇 | 用途 |

| --- | --- |

| 讀取、建立及編輯 | 讀取可用帳戶資訊並準備工作。 |

| 排程與發佈 | 在所選範圍內提交及管理發佈工作。 |

| 額外權限 | 僅在有特定需求時啟用。一般發文不需要 API key 管理權限。 |

- [從 SosoAPI App 開始](https://app.sosoapi.ai/start?lang=zh-Hant)

<a id="3-connect-your-agent-manually-if-needed"></a>

## 3. 必要時手動連接 agent

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

```
node --version
npx --version
```

<a id="local-mcp-claude-code-or-codex"></a>

## 本機 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
```

<a id="other-local-mcp-clients"></a>

## 其他本機 MCP 用戶端

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

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

- [安裝參考與套件選擇](https://sosoapi.ai/zh-tw/docs/installation)

<a id="hosted-mcp"></a>

## 託管 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 指引](https://sosoapi.ai/auth.md)

<a id="check-local-sign-in"></a>

## 選用：在終端機檢查登入

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

```
npx -y sosoapi auth status
```

```
npx -y sosoapi auth login
```

<a id="4-connect-your-social-account"></a>

## 4. 連結社群帳戶

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

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

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

核對預期的發佈對象

| 目標 | 檢查項目 |

| --- | --- |

| Threads | 預期的個人檔案，以及指定文字或媒體格式所需的權限。 |

| Instagram | 受支援的專業帳戶設定，以及指定格式的發佈權限。 |

| Facebook | 您管理的 Page，以及該 Page 所需的權限。 |

| YouTube | 預期的頻道，尤其在一個 Google 帳戶管理多個頻道時。 |

| X | 帳戶的文字或影片能力，以及組織剩餘的 X 點數。 |

```
npx -y sosoapi connect threads
```

- [連結帳戶](https://app.sosoapi.ai/connect?lang=zh-Hant)

<a id="5-verify-access-without-publishing"></a>

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

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

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

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

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

<a id="6-prepare-and-approve-your-first-post"></a>

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

<a id="approve-and-schedule"></a>

## 核准完整貼文後再排程

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

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

> 請將下方已核准的完整貼文，依指定日期、時間及時區排程至指定帳戶。
> 
> [貼上最終內容、媒體、發佈對象、日期、時間與時區。]
> 
> 請先檢查是否已有相符排程。只提交一次貼文，然後讀回已儲存結果，回報 ID、發佈對象、受理時間及目前狀態。結果不明時，請先檢查既有請求，再採取其他操作。

<a id="7-check-the-result-reschedule-or-cancel"></a>

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

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

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

了解已儲存的結果

| 結果 | 意義 | 下一步 |

| --- | --- | --- |

| 已排程 | 已受理並預定於未來時間執行。 | 請保留 ID，並在到期時間後檢查。 |

| 準備中、發佈中或核實中 | 工作進行中，或平台最終結果仍未知。 | 請稍後讀取同一篇貼文，避免再次提交。 |

| 已發布 | 平台證據確認已發佈。 | 如有回傳永久連結，請開啟核對。 |

| 失敗或需要處理 | 需要特定修正或允許的後續操作。 | 請讀取原因及可用操作。 |

| 需要重新排程或已過期 | 原始排程無法依要求繼續執行。 | 請檢閱說明，並選擇可用操作。 |

| 已取消 | 已確認取消。 | 請勿預期此排程會發佈。 |

<a id="manage-a-pending-post"></a>

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

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

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

<a id="8-add-images-or-video-then-reuse-the-workflow"></a>

## 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。其額度與成本獨立於一般方案配額。請勿透過重複提交繞過點數限制；發佈結果不明時，請先核實再傳送。

<a id="reuse-the-workflow"></a>

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

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

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

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

<a id="9-cli-and-api-walkthrough"></a>

## 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/
```

<a id="api-workspace-context"></a>

## 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
```

<a id="api-connected-accounts"></a>

## 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
```

<a id="api-create-schedule"></a>

## 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
```

<a id="api-read-result"></a>

## 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
```

<a id="api-cancel-schedule"></a>

## 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
```

<a id="http-from-your-backend"></a>

## 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](https://app.sosoapi.ai/connection/api?lang=zh-Hant)

- [API 參考](https://sosoapi.ai/zh-tw/docs/api)

- [API key 建立與明確授權範圍](https://sosoapi.ai/zh-tw/docs/api/identity-api-api-keys-create)

- [驗證與權限](https://sosoapi.ai/zh-tw/docs/authentication)

- [CLI 參考](https://sosoapi.ai/zh-tw/docs/cli-reference)

<a id="10-troubleshooting"></a>

## 10. 疑難排解

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

保留原始請求並進行復原

| 症狀 | 檢查項目或處理方式 |

| --- | --- |

| 無法使用 node 或 npx | 請為本機 MCP 安裝受支援的 Node.js 執行環境，或使用相容的託管 MCP。 |

| npx sosoapi 似乎一直等待 | 未指定指令時會啟動 stdio MCP 伺服器並等待用戶端。請用 --help 查看終端機操作說明。 |

| 已安裝，但對話中沒有工具 | 請重新連線或重新啟動實際使用的用戶端，並在目前對話啟用 SosoAPI。 |

| 登入開啟了錯誤的瀏覽器設定檔 | 請先停止您自己待處理的本機登入。使用 --help 確認支援 --no-open，再執行 npx -y sosoapi auth login --no-open。以預期設定檔開啟新連結，核對身分後再同意授權。請勿讓兩個設定檔同時使用同一連結。 |

| 連接埠 8789 已被占用 | 請使用 lsof -nP -iTCP:8789 -sTCP:LISTEN 檢查。只有確認是您自己的待登入程序時，才停止該監聽程序。 |

| 電子郵件驗證或登入失敗 | 請讀取實際錯誤，並使用提供的重試操作。電子郵件登入使用背景驗證，不需要尋找 CAPTCHA 核取方塊。也可以選擇 Continue with Google。 |

| 401 回應 | 請檢查此連線的登入及憑證有效性。本機 auth status 不會檢查託管連接器。 |

| 403 或缺少發佈操作 | 請核對所選工作區、角色及已授權能力，必要時向擁有者申請所需權限。 |

| 找不到預期的社群帳戶 | 請核對身分、工作區及平台帳戶選擇，並完成待處理的連線確認。 |

| 已連線，但無法發佈 | 請讀取該帳戶的能力及平台要求。只有確實需要取得新的平台同意時才重新連線；影片權限可能與文字權限不同。 |

| 上傳路徑超出允許資料夾 | 請使用允許的資料夾，或明確在本機 MCP 環境中設定 SOSOAPI_UPLOAD_ROOTS。 |

| 媒體匯入持續待處理 | 請檢查既有匯入與工作 ID，回報執行或設定錯誤，而非重複建立匯入。 |

| 配額或 X 點數已用盡 | 請讀取相關額度，並選擇允許的排程或方案操作。重複提交不會解除限制。 |

| 建立請求逾時 | 請保留請求金鑰，以及已知的受理貼文 ID。重試前先讀取或找回原始請求；完全相同的重試必須沿用原金鑰。 |

| 更新或取消時發生版本衝突 | 請重新讀取同一篇貼文、檢查可用操作，並僅為預期操作使用目前版本。 |

| Schema 或版本不相容錯誤 | 請更新 MCP 用戶端實際執行的套件，重新連線並檢查合約。增加權限無法修復 schema 不相容。 |

<a id="updates-and-revocation"></a>

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

下方第一條指令可在不啟動 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](https://app.sosoapi.ai/connection/agent?lang=zh-Hant)

- [管理 API key：Connection → API](https://app.sosoapi.ai/connection/api?lang=zh-Hant)

- [疑難排解參考](https://sosoapi.ai/zh-tw/docs/troubleshooting)

- [聯絡 SosoAPI 支援](mailto:vickyai.tech@gmail.com)

<a id="setup-completion-checklist"></a>

## 設定完成檢查清單

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

- 我的用戶端能使用 SosoAPI 工具，或 CLI/API 能執行已授權請求。

- 我已使用預期的帳戶登入，並選取正確工作區。

- 我的社群帳戶已顯示，並具備任務所需能力。

- 我了解 agent 只能準備工作，還是也能排程與發佈。

- 我可以準備草稿，並檢閱確切的發佈對象、內容和時間。

- 如果我已提交貼文，已保留其 ID，並能區分受理與確認發佈。

- 我知道如何檢查失敗原因、管理待處理排程及撤銷存取權限。