> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 外掛

> 為 Claude Code 安裝 Ayrshare 外掛，直接在編輯器中發布、排程並分析社群貼文 —— 支援發布前驗證、發布前確認提示、品牌語調草擬以及分析資料回讀。

Ayrshare 的 Claude Code 外掛已內建 [MCP Server](/additional/mcp-action-server) 設定、初始化指令、代理程式、技能以及安全 hook。安裝後，你可以直接在 Claude Code 中發布貼文、取得歷史與分析資料、管理設定檔等。任何內容上線前，代理程式都會先依照目標平台的規則對每則貼文進行驗證，並徵求你的確認，從而事前避免可預見的退件。歷史貼文可用於比對品牌語調，分析資料也可以回讀以指引下一則貼文。

本外掛為開源專案。存放庫位址：[ayrshare/ayrshare-social-media-api-claude-plugin](https://github.com/ayrshare/ayrshare-social-media-api-claude-plugin)。

## 安裝

<Steps>
  <Step title="新增 marketplace（僅需一次）">
    ```bash theme={"system"}
    claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
    ```
  </Step>

  <Step title="安裝外掛">
    ```bash theme={"system"}
    claude plugin install ayrshare@ayrshare
    ```
  </Step>
</Steps>

### 安裝範圍

| 範圍                | 適用範圍            |
| ----------------- | --------------- |
| Global（預設）        | 本機上的所有專案。       |
| `--scope local`   | 目前專案，不會提交到 git。 |
| `--scope project` | 目前專案，會提交並與團隊共用。 |

<Note>
  在 Claude Code CLI 中，全域範圍被稱為 `--scope user`。
</Note>

## 憑證

可透過以下任一方式提供 Ayrshare API 金鑰：

<ul class="custom-bullets">
  <li>執行 `/ayrshare:setup` 來設定或輪替金鑰。</li>
  <li>設定 `AYRSHARE_API_KEY` 環境變數。</li>
</ul>

外掛內建的 `.mcp.json` 已宣告 `Authorization` 標頭，以及選用的 `Profile-Key` 與 X BYOK 標頭，每一項都帶有空的預設值（`${VAR:-}`），因此只要設定相對應的環境變數就能啟用該標頭（Claude Code 會在啟動時替換這些值）。若要讓每次呼叫都以某個子設定檔為目標，請設定 `AYRSHARE_PROFILE_KEY`（透過 `/ayrshare:setup` 或 `settings.json` 的 `env` 區塊），然後重新啟動 Claude Code；內建的 `Profile-Key` 標頭會帶上該值，未設定時則維持為空（視為未提供）。若只想讓某一次呼叫以子設定檔為目標，則在工具呼叫中傳入 `profileKey` 參數（不需修改設定）。你不需要編輯內建的 `.mcp.json`，也不應該編輯，因為 `claude plugin update` 會覆寫它。

<Warning>
  MCP 伺服器會在工作階段啟動時初始化。安裝外掛或變更金鑰後，請 **重新啟動 Claude Code**。
</Warning>

### X/Twitter 自帶（BYO）憑證

發布到 X/Twitter 需要你自己的 X 開發者應用程式憑證（X BYO-key 強制規定，自 2026 年 3 月 31 日起生效；請參見 [API 概觀](/apis/overview#xtwitter-byo-credentials)）。內建的 `.mcp.json` 已經宣告了兩個 X BYOK 標頭並附上空的預設值，同時也宣告了 `Authorization` 與 `Profile-Key`：

```json theme={"system"}
"headers": {
  "Authorization": "Bearer ${AYRSHARE_API_KEY}",
  "Profile-Key": "${AYRSHARE_PROFILE_KEY:-}",
  "X-Twitter-OAuth1-Api-Key": "${X_TWITTER_OAUTH1_API_KEY:-}",
  "X-Twitter-OAuth1-Api-Secret": "${X_TWITTER_OAUTH1_API_SECRET:-}"
}
```

因此你只需透過 `/ayrshare:setup` 或 `settings.json` 的 `env` 設定對應的環境變數（`X_TWITTER_OAUTH1_API_KEY`、`X_TWITTER_OAUTH1_API_SECRET`），然後 **重新啟動 Claude Code**；請勿修改內建的 `.mcp.json`（它會在 `claude plugin update` 時被覆寫）。**兩者要嘛都設定，要嘛都不設定**：都未設定時，X/Twitter 呼叫會回傳錯誤 `419`（`x_credentials_required`）；只設定其中一個時，會回傳錯誤 `400`。這是每個 Ayrshare 帳戶對應一組金鑰對，會在每一次以 X 為目標的請求中送出（同一組金鑰適用於所有子設定檔）。

<Note>
  比較偏好使用直接連線而非外掛？相同的 BYO 標頭也可以透過 `claude mcp add --header` 傳入 —— 請參見 [Connect & Setup → X/Twitter BYO 憑證](/additional/mcp-action-connect#xtwitter-byo-credentials)。
</Note>

## 外掛內容

### 指令

<ul class="custom-bullets">
  <li>`/ayrshare:setup` —— 設定或輪替 Ayrshare API 金鑰。</li>
</ul>

### 代理程式（Agents）

<ul class="custom-bullets">
  <li>`social-manager`：在多個平台上發布、排程並分析內容。</li>
  <li>`profile-manager`：在 Business 帳戶下建立與列出設定檔，並為客戶的設定檔產生 JWT 社群連結 URL。</li>
  <li>`insights-analyst`：唯讀報表。拉取指標與貼文歷史並彙整成效；不會發布、留言、傳送私訊或修改任何內容。</li>
</ul>

### 技能（Skills）

| 技能                           | 用途                  |
| ---------------------------- | ------------------- |
| `getting-started`            | 首次使用時的引導與連線。        |
| `post`                       | 建立、驗證、更新與重試貼文。      |
| `history`                    | 取得貼文與平台歷史紀錄。        |
| `analytics`                  | 拉取單則貼文與帳戶層級的分析資料。   |
| `comments`                   | 讀取、新增與回覆留言。         |
| `messages`                   | 讀取與傳送私訊，並設定自動回覆。    |
| `profiles`                   | 建立與列出子設定檔。          |
| `media`                      | 驗證媒體 URL 是否可存取。     |
| `generate`                   | AI 產生貼文文案並推薦主題標籤。   |
| `webhooks`                   | 註冊、取消註冊與列出 Webhook。 |
| `errors`                     | 解讀 Ayrshare 錯誤碼。    |
| `draft-in-brand-voice`       | 以一致的品牌語調草擬貼文文案。     |
| `plan-and-schedule-campaign` | 規劃並排程由多則貼文構成的行銷活動。  |

### 確認 hook

`PreToolUse` hook 會在任何發布或傳送動作之前徵求你的確認。它涵蓋以下 7 個工具：

<ul class="custom-bullets">
  <li>`create_post`</li>
  <li>`update_post`</li>
  <li>`retry_post`</li>
  <li>`add_comment`</li>
  <li>`reply_comment`</li>
  <li>`send_message`</li>
  <li>`set_auto_response`</li>
</ul>

## 常見問題（FAQ）

<AccordionGroup>
  <Accordion title="外掛會在發布前驗證貼文嗎？">
    會。外掛會在發布前執行 `validate_post`，針對你的內容進行試跑（dry-run）驗證，檢查是否符合每個平台的規則 —— 長度、格式與媒體需求 —— 讓你能事前避免可預見的退件。
  </Accordion>

  <Accordion title="發布到我實際的帳戶前會向我確認嗎？">
    會。`PreToolUse` 確認 hook 會在任何發布或傳送動作之前徵求你的核准，涵蓋的工具包括：`create_post`、`update_post`、`retry_post`、`add_comment`、`reply_comment`、`send_message` 與 `set_auto_response`。
  </Accordion>

  <Accordion title="外掛可以符合我的品牌語調嗎？">
    可以。`draft-in-brand-voice` 技能會讀取你的歷史貼文，以一致的品牌語調草擬新文案。它只會產生草稿 —— 未經你確認前不會發布任何內容。
  </Accordion>

  <Accordion title="我可以讀取分析資料來指引下一則貼文嗎？">
    可以。分析工具會回傳單則貼文與帳戶層級的指標，讓你能回讀結果並據此指引下一則貼文。
  </Accordion>

  <Accordion title="使用此外掛需要準備什麼？">
    一組 Ayrshare API 金鑰（涉及設定檔與子設定檔時，需要 Business 方案的金鑰）以及 Claude Code。透過 `/ayrshare:setup` 或 `AYRSHARE_API_KEY` 環境變數設定金鑰，然後重新啟動 Claude Code。
  </Accordion>

  <Accordion title="發布到 X/Twitter 需要額外設定嗎？">
    需要。X/Twitter 需要你自己的 OAuth 1.0a 憑證，並以兩個連線標頭（`X-Twitter-OAuth1-Api-Key` 與 `X-Twitter-OAuth1-Api-Secret`）的形式加入。請參見上方的 [X/Twitter BYO 憑證](#xtwitter-byo-credentials)。
  </Accordion>
</AccordionGroup>

## 後續步驟

<CardGroup cols={2}>
  <Card title="Connect & Setup" icon="plug" href="/additional/mcp-action-connect" horizontal>
    身分驗證、設定檔定位與 BYO 憑證。
  </Card>

  <Card title="工具目錄" icon="list" href="/additional/mcp-action-tools" horizontal>
    按領域分組的 27 個工具，包含適用範圍與用途。
  </Card>
</CardGroup>