---
title: 透過 API 觸發例行程序
url: https://platform.claude.com/docs/zh-TW/api/claude-code/routines-fire
description: 透過發送經過驗證的 POST 請求，按需啟動 Claude Code 例行程序工作階段。
---

<Warning>
  這是一個實驗性 API。請求和回應的結構、速率限制以及 token 語意可能會變更。
</Warning>

[Claude Code](https://code.claude.com/docs) 是 Anthropic 的代理式編碼工具。[Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) 在 Anthropic 管理的雲端基礎設施上於 claude.ai/code 執行 Claude Code 工作階段，而[例行程序](https://code.claude.com/docs/en/routines)是其中儲存的設定：一個提示、一個或多個儲存庫以及連接器，經過封裝後可以按排程、回應 GitHub 事件或透過 HTTP 呼叫時無人值守地執行。

此端點是 HTTP 進入點。向它發送 POST 請求會啟動現有例行程序的新執行，並回傳產生的工作階段 ID 和 URL。典型的呼叫者是警報系統、CI 管線以及需要以程式化方式啟動 Claude Code 工作階段的內部工具。

呼叫此端點需要一個使用 Pro、Max、Team 或 Enterprise 方案且已啟用 [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) 的 claude.ai 帳戶。請使用在 Claude Code 網頁介面中建立的每個例行程序專屬「bearer token」（持有者權杖）進行驗證，而非使用 Claude API 金鑰。

## 與 Claude Platform 的差異

例行程序觸發端點屬於 Claude Code 產品範疇，它在幾個方面與 Claude Platform 的 API 和 SDK 不同：

| 方面       | 此端點                                                                                                                          | Claude Platform API                                                                  |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 驗證       | `Authorization: Bearer`，使用在 [claude.ai/code/routines](https://claude.ai/code/routines) 建立的每個例行程序專屬 token（`sk-ant-oat01-...`） | `x-api-key`，使用來自 Claude Console 的 Claude API 金鑰                                      |
| Token 範圍 | 僅限一個例行程序；無讀取存取權                                                                                                              | 工作區層級                                                                                |
| SDK 支援   | 無                                                                                                                            | 在所有[用戶端 SDK](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/overview) 中可用 |
| 計費       | claude.ai 上的 Claude Code 訂閱用量                                                                                                | Claude Platform 用量                                                                   |
| 路徑命名空間   | `/v1/claude_code/...`                                                                                                        | `/v1/...`                                                                            |
| 穩定性      | 實驗性                                                                                                                          | 穩定或標準 beta                                                                           |

## 開始之前

要呼叫此端點，您需要：

1. 在 [claude.ai/code/routines](https://claude.ai/code/routines) 建立的例行程序。
2. 為該例行程序產生的 bearer token：開啟例行程序進行編輯，在 **Select a trigger** 下點擊 **Add another trigger**，選擇 **API**，然後在彈出視窗中點擊 **Generate token**。該 token 只會顯示一次，之後無法再取得。

請參閱 Claude Code 文件中的[新增 API 觸發器](https://code.claude.com/docs/en/routines#add-an-api-trigger)以取得完整的設定逐步說明。

## 觸發例行程序

```http
POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire
```

當您新增 API 觸發器時，Claude Code 網頁 UI 會在 token 旁提供完整的 URL，因此大多數整合會將兩者都儲存為密鑰並直接呼叫端點。以下範例展示了一個 shell 呼叫以及一個在 CI 失敗時觸發例行程序的 GitHub Actions 步驟。

```bash cURL
curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'
```

```yaml GitHub Actions
- if: failure()
  env:
    ROUTINE_FIRE_URL: ${{ secrets.ROUTINE_FIRE_URL }}
    ROUTINE_FIRE_TOKEN: ${{ secrets.ROUTINE_FIRE_TOKEN }}
  run: |
    curl -X POST "$ROUTINE_FIRE_URL" \
      -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d "{\"text\": \"CI failed: $GITHUB_WORKFLOW run $GITHUB_RUN_ID on $GITHUB_REF\"}"
```

請求會在工作階段建立後回傳。它不會串流工作階段輸出，也不會等待工作階段完成。

### 標頭

| 名稱                  | 必填      | 說明                                                                                    |
| ------------------- | ------- | ------------------------------------------------------------------------------------- |
| `Authorization`     | 是       | `Bearer <token>`。在 Claude Code 網頁 UI 中建立的每個例行程序專屬 token，前綴為 `sk-ant-oat01-`。          |
| `anthropic-version` | 是       | [API 版本](https://platform.claude.com/docs/zh-TW/api/versioning)。`2023-06-01` 是唯一接受的值。 |
| `Content-Type`      | 當有請求主體時 | `application/json`。                                                                   |

發送 `anthropic-beta: experimental-cc-routine-2026-04-01` 標頭的較舊整合不受影響：端點接受帶有和不帶有此標頭的請求。

### 路徑參數

| 名稱           | 類型     | 說明                                                                            |
| ------------ | ------ | ----------------------------------------------------------------------------- |
| `routine_id` | string | 例行程序的識別碼。儘管參數名稱如此，其值的前綴是 `trig_` 而非 `routine_`。包含在您新增 API 觸發器時彈出視窗所顯示的 URL 中。 |

### 請求主體

| 欄位     | 類型     | 必填 | 說明                                                                                                                     |
| ------ | ------ | -- | ---------------------------------------------------------------------------------------------------------------------- |
| `text` | string | 否  | 此次執行的初始上下文，例如警報內容、失敗的日誌行或 git diff。該值為自由格式文字且不會被解析；如果您發送 JSON 或其他結構化負載，例行程序會將其作為字面字串接收。與其儲存的提示一起傳遞給例行程序。最多 65,536 個字元。 |

請求主體為選填。主體中的未知欄位會被忽略。

### 回應

成功的請求會回傳 `200 OK` 以及新工作階段的詳細資訊：

```json
{
  "type": "routine_fire",
  "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
  "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}
```

| 欄位                        | 類型     | 說明                                          |
| ------------------------- | ------ | ------------------------------------------- |
| `type`                    | string | 永遠是 `routine_fire`。                         |
| `claude_code_session_id`  | string | 為此次執行建立的 Claude Code 工作階段的 ID。              |
| `claude_code_session_url` | string | claude.ai 上工作階段的連結。在瀏覽器中開啟它以觀看執行、檢閱變更或繼續對話。 |

### 錯誤

錯誤使用標準的 Anthropic [錯誤封裝](https://platform.claude.com/docs/zh-TW/api/errors)：

```json
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "<string>"
  }
}
```

| HTTP 狀態 | 錯誤類型                    | 原因                                                                                                                                                |
| ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400     | `invalid_request_error` | 缺少或不支援的 `anthropic-version` 標頭、`text` 超過 65,536 個字元，或例行程序已暫停（請參閱[編輯和控制例行程序](https://code.claude.com/docs/en/routines#edit-and-control-routines)）。 |
| 401     | `authentication_error`  | `Authorization` 標頭中沒有 bearer token，或 token 與此例行程序不符。                                                                                              |
| 403     | `permission_error`      | 帳戶或組織無權存取此端點。                                                                                                                                     |
| 404     | `not_found_error`       | 例行程序不存在。                                                                                                                                          |
| 429     | `rate_limit_error`      | 已達到例行程序或帳戶的每小時觸發次數上限。回應包含一個 `Retry-After` 標頭，指示視窗何時重設。                                                                                            |
| 500     | `api_error`             | 意外的伺服器錯誤。請使用指數退避重試；如果錯誤持續存在，請聯繫支援並提供請求 ID。                                                                                                        |
| 503     | `overloaded_error`      | 服務暫時過載。請在短暫延遲後重試。Claude Platform 對此錯誤類型回傳 529；此端點回傳 503。                                                                                          |

## 驗證

bearer token 的範圍僅限於單一例行程序。遭洩露的 token 只能觸發該例行程序；它不授予讀取存取權、不授予對其他例行程序的存取權，也不授予對帳戶資料的存取權。

在 [claude.ai/code/routines](https://claude.ai/code/routines) 的例行程序 API 觸發器設定中產生和撤銷 token。沒有用於 token 管理的公開 API。產生新 token 會撤銷前一個 token。

## 冪等性

每個成功的請求都會建立一個新的工作階段。沒有冪等性金鑰。如果 webhook 呼叫者重試，端點會建立多個工作階段。

## 速率限制

API 觸發次數有每小時上限：每個例行程序每小時最多接受 30 次觸發（由 API 觸發、網頁 UI 中的 **Run now** 按鈕和一次性重新啟用共用），而每個帳戶每小時在所有例行程序中最多可進行 100 次 API 觸發。產生的工作階段會消耗與互動式工作階段相同的 Claude Code 訂閱用量。當達到限制時，端點會回傳 `429 rate_limit_error` 以及一個 `Retry-After` 標頭。

要了解例行程序用量如何與訂閱限制和額外用量計費互動，請參閱 Claude Code 文件中的[用量與限制](https://code.claude.com/docs/en/routines#usage-and-limits)。

## SDK 支援

此端點不在 Anthropic SDK 中。其 token 模型與 API 金鑰驗證不同，而典型的呼叫者（例如 CI 工作和警報 webhook）會直接發送請求。

## 另請參閱

* Claude Code 文件中的[使用例行程序自動化工作](https://code.claude.com/docs/en/routines)
* [錯誤](https://platform.claude.com/docs/zh-TW/api/errors)