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，并能区分受理与确认发布。
• 我知道如何检查失败原因、管理待处理排程及撤销存取权限。