【2026 最新】Claude Agent SDK 月度 API Credits 怎麼接？五步核對組織、金鑰與計費

你已經付了 Claude 訂閱費，接上 SDK 後卻不確定：這次任務吃的是訂閱限額，還是 Console 的 API 額度？Claude Agent SDK 月度 API Credits 最容易弄錯的地方，是把「同一個登入信箱」當成「同一本帳」。

截至 2026 年 10 月 8 日，Anthropic 的 10 月 7 日更新說明 明確保留 SDK、claude -p 與第三方應用使用訂閱限額的路徑，同時加入 Max／Team 的月度 API credits。本文專為第一次接 SDK 的讀者寫：從選組織、建測試金鑰，到保存一份小任務紀錄，再到 Console 核對用量；你不需要先理解完整 Agent 架構。

先說結論：Claude Agent SDK 月度 API Credits 先驗哪四件事？

• 先確認方案與角色，領取到你真正要開發的 Console 組織。
• 用該組織的測試 workspace API key 執行一次假資料任務，保留時間與模型紀錄。
• SDK 的費用欄位是估算；實際用量與成本要到 Console 對帳。
• 檢查其他餘額與自動儲值，再決定是否擴大工作量。

計費路徑＝啟動入口＋驗證方式＋所屬組織。 把 Console 組織想成公司錢包，workspace 是專案的信封，API key 是拿哪個信封付款的憑證。換一把鑰匙，就可能換一本帳；信箱相同，不能替你證明錢包相同。

先分清楚：訂閱限額、API credits 與 extra usage

SDK（軟體開發套件）把 Claude 的任務執行能力接進你的程式；API 是程式向服務送請求的介面。如果還不熟 Agent 為什麼會反覆呼叫模型，可以先讀 Agent Harness 的模型與執行層。這篇先把任務縮到只有一次文字判讀。

根據 月度額度 FAQ，API credits 適用於 Claude Platform 上的 API、Console Playground、Managed Agents 與 Agent SDK。它與 Claude、Claude Code、Cowork 的訂閱使用限額分開，亦不補貼互動式 Claude Code 或產品的 extra usage。

你自己啟動 SDK 或 claude -p，並使用綁定組織的 API key，才走這份 API 額度；改用 Claude 方案登入，則仍使用方案限額。GitHub Action、IDE extension 或桌面 App 啟動的執行被歸為 Claude Code 用量，不能只看到 -p 就判定有抵扣。Bedrock、Vertex AI、Foundry 也不在這份抵扣範圍。

白話說，這次增加的是一個開發用錢包。不要為了領額度，先把原本所有登入方式換掉；也不要把自己使用 SDK 的權利，延伸成第三方產品可以任意提供訂閱登入。官方 SDK 快速入門 對第三方開發者提供 claude.ai 登入或限額，另列出需事先核准的條件。

① 領取前：先確認「哪個錢包接額度」

為什麼找不到領取入口？先查資格與角色。截至上述日期，Max／Team 是符合資格的方案，新訂閱需滿七天；Max 由訂閱者操作，Team 由 Owner 或 Primary Owner 操作。Console 端則需 Owner、Admin 或 Billing 角色。行動平台訂閱也可領取，操作入口在網頁。

進入 claude.ai → Settings → Billing；Team 走 Organization settings → Billing。在 API credits 區塊選 Link organization，選定 Console 組織，閱讀 Supplemental Credit Terms 後確認。領取並使用這份額度不要求先在 Platform 加信用卡。

確認前，先在私人筆記寫下組織名稱與 ID，以及誰會持有它的 API key。一個方案只能綁一個 Console 組織，一個組織也只能接受一個方案的額度。 自助介面不能任意換綁，後續更改需聯絡支援。因此這一步的驗收不是「按成功」，而是組織的 Billing 顯示額度、金額與到期日。

官方表示入口分數天推出；滿七天仍看不到時，依序查方案、兩端角色與組織選擇，再聯絡支援。不要把入口尚未出現推論成訂閱登入已被停用。

② 建測試金鑰：讓「誰花了錢」可以查回去

問題是：大家共用同一把 key，如何辨認這次任務？做法是建立獨立測試 workspace，例如 sdk-credit-check，再到 Settings → API keys → Create key，將 Linked account 選為自己，並限定到這個測試 workspace，建立個人專用 API key。官方認證文件 建議個人工具使用 personal key；未來若改成共用或無人值守服務，再評估 service account 或 Workload Identity Federation。官方 Workspaces 文件 說明 workspace 可分開管理金鑰、成員與花費，但帳務仍集中在組織。

不要直接用 Default Workspace 來教學驗收：官方明確說它不能設定 workspace 限制。新 workspace 的 Spend limits 頁可設每月花費限制；先設小額限制，再開始任務。workspace 限制不能高於組織限制，且它限制的是花費，不是替這個專案保留一份 credits。

同一組織持有 API key 的人都會花到共用餘額。測試期間避免同 workspace 另跑任務，否則前後差額無法乾淨歸因。私人紀錄只需組織、workspace、key 名稱、執行時間與模型；完整 key 留在密碼管理器，不貼進提示詞、截圖或 Git。 可配合 Agent 秘密資料與金鑰安全 檢查保存方式。

③ Claude Agent SDK 月度 API Credits 上手：只讀一段假資料

這一步要驗證傳輸與計費，不需要先授權 Agent 修改檔案。準備一個新資料夾，使用你已安裝、符合 官方 Python SDK 系統要求 的 Python（3.10 以上），建立虛擬環境。以下是 macOS／Linux 的命令；Windows 使用快速入門頁面的 PowerShell 啟用方式。

mkdir sdk-credit-check
cd sdk-credit-check
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade claude-agent-sdk
python -m pip freeze > requirements.lock.txt

SDK 多數平台的套件內附 Claude Code binary；如果裝到不含 binary 的 source distribution，依官方快速入門補齊，別把缺執行檔當成 key 錯誤。鎖定檔是為了下次知道用了哪個版本，不代表各平台都能共用同一份 binary。

把下列程式存為 credits_check.py，執行 python credits_check.py。它會隱藏輸入 key，並要求貼入你帳號可用的完整 API model ID；模型名稱從 Console 與 帳號可用模型清單取得，不把舊教學裡的名稱直接搬來。這份程式清理本程序的既有 Anthropic／雲端路由環境，並使用獨立設定目錄；公司受管環境仍需先確認組織政策允許這種測試。

import asyncio
import getpass
import json
import os
from datetime import datetime, timezone
from importlib.metadata import version
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

root = Path.cwd()
key = getpass.getpass('貼上測試 workspace 的 API key（不顯示）：').strip()
model = input('貼上可用模型的完整 API model ID：').strip()
if not key or not model:
    raise SystemExit('金鑰與模型 ID 都必須填寫')
# 只清理本程式的環境，不改你的 shell 設定。
for name in list(os.environ):
    if name.startswith(('ANTHROPIC_', 'CLAUDE_CODE_USE_')) or name == 'CLAUDE_CODE_OAUTH_TOKEN':
        os.environ.pop(name)
os.environ['ANTHROPIC_API_KEY'] = key
os.environ['CLAUDE_CONFIG_DIR'] = str(root / 'test-config')
receipt = {'started_utc': datetime.now(timezone.utc).isoformat(),
           'sdk_version': version('claude-agent-sdk'), 'requested_model': model}

async def main():
    options = ClaudeAgentOptions(
        model=model, cwd=str(root), setting_sources=[],
        tools=[], disallowed_tools=['*'],
        mcp_servers={}, strict_mcp_config=True,
        max_turns=1, max_budget_usd=0.10,
    )
    try:
        async for msg in query(
            prompt='假資料：紙箱 3 個、筆記本 2 本。只根據這段文字回答物件總數與名稱，不執行工具。',
            options=options,
        ):
            if isinstance(msg, ResultMessage):
                receipt.update({
                    'subtype': msg.subtype,
                    'terminal_reason': getattr(msg, 'terminal_reason', None),
                    'is_error': msg.is_error, 'session_id': msg.session_id,
                    'answer': msg.result, 'usage': msg.usage,
                    'estimated_cost_usd': msg.total_cost_usd,
                    'model_usage': getattr(msg, 'model_usage', None),
                })
    except Exception as exc:
        receipt['exception_type'] = type(exc).__name__
        for field in ('terminal_reason', 'api_error_status', 'session_id', 'subtype'):
            value = getattr(exc, field, None)
            if value is not None:
                receipt[field] = value
    finally:
        receipt['ended_utc'] = datetime.now(timezone.utc).isoformat()
        (root / 'receipt.json').write_text(
            json.dumps(receipt, ensure_ascii=False, indent=2), encoding='utf-8')
        print('已保存 receipt.json；請核對答案、終止原因與 Console 用量。')

asyncio.run(main())

程式的任務只含紙箱與筆記本，人工答案是五個物件。tools=[] 配合 disallowed_tools=["*"] 關掉模型工具，strict_mcp_config=True 不加入既有 MCP；setting_sources=[] 排除檔案型設定來源。依 官方權限文件，allowed_tools 是自動核准名單，並不是工具白名單，因此本例不拿它當安全界線。

這裡的「唯讀」指模型不取得操作檔案與外部服務的工具；Python 本身仍會保存 receipt.json，SDK 也可能保存本機設定與 session 資料。第一次先只放假資料，避免把驗收傳輸變成真實資料處理。本文提供的是依官方介面設計的驗收方法，沒有宣稱 AlphaLab 已替你的組織完成抵扣測試。

④ 對帳：任務成功，還要有「錢從哪裡出」的證據

跑完先開 receipt.json，看答案、is_error、terminal_reason 與 subtype。新版 SDK 有些 API 失敗會在 terminal_reason 表達原因，不能只看到 subtype="success" 就算成功。若只有例外種類而沒有 result，代表這次缺完整任務收據；先排查安裝、認證與模型權限。

接著到 platform.claude.com → Usage，選同一組織，以測試時段、workspace、API key 或可用篩選維度定位用量。官方 Usage and Cost API 文件 也提供組織用量與成本報表能力；第一次不用為了自動化額外建立 Admin API key，先用 Console 核對。用量報表可按 key、workspace 與模型拆分；官方 Cost API 則以日為粒度、可按 workspace 分組。先隔離同一專案與日期，別把每日成本誤認為一筆請求的即時扣款。

最後回 Settings → Billing 檢查月度額度餘額與其他餘額。驗收要留下三種不同證據：任務有回應、正確組織有相應用量、餘額與成本記錄能解釋支出。報表尚未顯示時先保留時間與 session ID，不反覆重跑付費請求。其他專案同時消耗共用池時，總餘額變動也不能全算給你的測試。

estimated_cost_usd 取自 SDK 的 total_cost_usd。官方成本追蹤文件 明確稱它為客戶端估算：價格變動、SDK 內建價表與特殊計費規則，都可能造成落差。估算有數字，能證明程式產生了紀錄；它本身不能證明哪一種餘額已抵扣。

⑤ 停止與退出：先知道額度用完後誰接棒

月度額度依方案帳期更新，年度方案也按月發放；未用完的額度到期不累積，並優先於已購買額度使用。API 額度用完後，組織若還有購入額度或 auto-reload，執行會繼續消耗那些資金；都沒有時請求才停止。透過業務採帳單結算的組織，超出額度仍照既有方式計費。

因此先到 Billing 查 auto-reload 和已購額度。若測試目標是用完補助即停止，選沒有其他餘額、沒有自動儲值的組織配置；已有正式專案共用錢包時，改以測試 workspace 限制與管理員協調，不為驗收任意關掉別人的儲值。

程式的 max_turns=1 限制模型回合，max_budget_usd=0.10 在本次呼叫的成本估算到門檻時停止。這不是精確 0.10 美元的付款保證：觸發門檻的回應本身可能已產生支出。示範預算是你設定的測試條件，不是官方贈送額度或固定任務價格。

需要中止時先停止本機程序，核對 Console；中止不會退回已完成請求的用量。測試結束後到 Settings → API keys 找到這把測試 key 並停用或刪除，再以它執行同一個小任務一次，驗收認證拒絕並保存終止紀錄。若仍成功，先停止，查程式是否真的用了那把 key。刪掉本機變數或檔案，不等於撤銷伺服器端金鑰。

常見問題：八個新手判斷

1. SDK 使用訂閱限額的路徑全面停用了嗎？

沒有。10 月 7 日官方更新明確說仍可使用；本文另教你把自啟動任務接到 Console API credits。

2. Pro 也能領這份月度額度嗎？

不能。這份優惠的官方資格是 Max／Team，Free、Pro 與 Enterprise 不符合。

3. Team 每個人都有自己的 500 美元嗎？

不是。Team 按座位計算後匯成共用池，上限 500 美元；workspace 只是管理使用，不把池切成個人贈額。

4. 月度 API 額度能補互動式 Claude Code 超額嗎？

不能。互動式 Code 與 extra usage 不在這份抵扣範圍，要分開看訂閱帳與 Console 帳。

5. 寫了 .env，SDK 就會自動讀到 key 嗎？

不會。官方快速入門說 SDK 不自動載入 .env；本例由程式讀取隱藏輸入並設定本程序環境，其他整合需自行載入。

6. 用同一個信箱，就保證扣對組織嗎？

不保證。你要核對領取的組織、key 所屬 workspace，以及實際 Console 用量；同一個人可以出現在多個組織。

7. receipt 的估算費用是零，就可以放心批次跑嗎？

不能據此判斷。估算缺失或價表不匹配，也可能導致數字不足以反映成本；先對 Console，再擴大。

8. API 額度到零，任務一定立即停止嗎？

不一定。已購額度、自動儲值或業務帳單可能接棒；先確認這三個條件，再設專案停止規則。

給新手的三個重點

• 記組織，不只記信箱：把領取地點與金鑰來源寫在同一張私人紀錄。
• 先讓任務可人工判分：五個假物件，比一開始放整個專案更容易定位問題。
• 成功與抵扣分開驗：先看答案，再看用量，最後查是哪一份餘額支付。