Skip to main content
Agent SDK 工作階段從設定檔、環境變數和您啟動時傳遞的 options 物件讀取設定。本頁面說明如何組合 options 物件,以及哪些設定檔和環境變數控制它。 如需每個選項的類型和預設值,請參閱 Options(TypeScript)和 ClaudeAgentOptions(Python)參考。

將選項傳遞給工作階段

每個 query() 呼叫都接受一個選項物件:TypeScript 中的 Options、Python 中的 ClaudeAgentOptions。每個欄位都是選擇性的,以無選項啟動的工作階段會以 SDK 的預設值執行。下面的範例設定了一個唯讀工作階段,可以總結專案的開放 TODO。配對讀作 TypeScript / Python,其中拼寫不同:
  • model:選擇模型
  • allowedTools / allowed_tools:預先核准唯讀工具清單
  • maxTurns / max_turns:限制回合數
  • cwd:設定工作目錄
cwd 指向您自己的其中一個專案並執行範例。該專案的開放 TODO 摘要會在結果訊息到達時列印。 allowedTools(TypeScript)或 allowed_tools(Python)預先核准列出的工具,因此對它們的呼叫會在不停止以獲得核准的情況下執行。清單外的工具保持可用。當 Claude 呼叫未列出的工具時,權限模式決定呼叫是否執行。如需詳細資訊,請參閱允許和拒絕規則

載入設定檔

設定檔提供超出選項物件的設定。兩個選項控制它們的載入方式:
  • settingSources / setting_sources:控制哪些檔案系統來源載入:使用者、專案和本機。設定檔和 CLAUDE.md 檔案透過這些來源到達。
  • settings:載入設定檔路徑或任一語言的內嵌 JSON 字串,TypeScript 也接受設定物件。無論您傳遞什麼形式都會覆蓋使用者、專案和本機檔案系統設定;只有受管理的原則設定排名更高。參考文件在 TypeScript 的設定優先順序和 Python 的設定優先順序下記錄完整的優先順序順序。
傳遞 [] 以停用使用者、專案和本機設定。如需詳細資訊,請參閱在 SDK 中使用 Claude Code 功能

選擇模型

除非 model 選項、您的設定或您的環境選擇模型,否則新工作階段會在 Claude Code 的預設模型上啟動。如需這些來源的順序,請參閱設定您的模型。設定 model 以固定特定模型,或選擇較小的模型以獲得更快、更便宜的代理。該值採用模型別名或完整模型名稱;別名及其解析的版本列在模型別名下。 設定 fallbackModel(TypeScript)或 fallback_model(Python)以命名備份模型。當主要模型過載或不可用時,工作階段會切換到備份。主要模型在每個使用者回合開始時重試,因此一旦中斷通過,工作階段會返回到它。 在任一語言中,該選項接受單個模型或逗號分隔的備份清單。如需順序和鏈上限,請參閱備份模型鏈。在 TypeScript 中,等於 model 的備份在啟動時會拋出錯誤。 下面的範例顯示 TypeScript 中的備份清單和 Python 中的單個備份:
Messages API 請求參數 temperaturetop_pmax_tokens 在任一語言的選項物件上都沒有欄位。改為設定努力級別支出上限,或在您需要直接使用這些參數時呼叫 Messages API。

設定環境變數

env 選項為執行您工作階段的 Claude Code 程序設定環境變數。您的值是否替換繼承的環境或合併到它上面因語言而異:
  • TypeScriptenv 替換子程序環境
  • Python:SDK 將您的值合併到繼承的環境上,您的值覆蓋繼承的值
在 TypeScript 中,將 process.env 展開到 env 中以保留繼承的變數,例如 PATHHOMEANTHROPIC_API_KEY。當您不設定 env 時,子程序在兩種語言中都繼承您的環境。 該範例透過設定 ANTHROPIC_BASE_URL 將 API 流量路由通過閘道。
您傳遞的變數也可以設定 Claude Code 本身。如需 Claude Code 程序讀取的變數,請參閱環境變數。若要以這種方式調整 API 逾時和停滯偵測,請遵循 TypeScript 參考Python 參考中的「處理緩慢或停滯的 API 回應」部分。

設定工作目錄

設定 cwd 以在特定目錄中執行工作階段。當您不設定 cwd 時,工作階段會在您程序的工作目錄中執行。兩個 SDK 都沒有 cwd 的設定器。若要在不同目錄中執行,請使用該 cwd 啟動另一個工作階段。 Claude Code 讀取工作目錄以確定: 若要讓工具到達工作目錄外的檔案,請使用 additionalDirectories(TypeScript)或 add_dirs(Python)新增路徑。如需該授予的範圍,請參閱其他目錄授予檔案存取權,而非設定

限制回合和支出

使用 maxTurns / max_turnsmaxBudgetUsd / max_budget_usd 限制回合和支出。當未設定時,兩個上限都關閉。當工作階段達到上限時,執行以結果訊息結束,其子類型命名上限,error_max_turnserror_max_budget_usd。接下來發生的情況因輸入模式而異:
  • 單次 query():SDK 產生上限結果,然後引發,因此將迴圈包裝在 try 區塊中以在錯誤後繼續
  • 串流輸入:工作階段在上限結果後保持活動,最大回合計數為每個排隊訊息重新開始。預算總計在訊息中累積,一旦支出達到上限,同一對話中的後續訊息以相同的預算結果結束。/clear 重新開始預算
兩個上限對 0 的處理方式不同:
  • maxTurns / max_turns0 執行沒有回合限制的工作階段,與不設定選項相同
  • maxBudgetUsd / max_budget_usd:CLI 在啟動時拒絕 0 作為無效金額,工作階段永遠不會執行
如需有關兩個上限的詳細資訊,包括子代理支出,請參閱回合和預算

在工作階段中途變更設定

當您使用串流輸入啟動工作階段時,您可以在執行時切換其模型和權限模式。您呼叫設定器的位置因語言而異:
  • TypeScriptquery() 傳回的物件上的方法
  • PythonClaudeSDKClient 上的方法,因為 query() 傳回沒有控制方法的純迭代器
兩種語言都有相同的設定器:
  • setModel() / set_model():切換模型。不帶模型呼叫它以切換到 Claude Code 的預設模型,而不是您在選項中傳遞的 model
  • setPermissionMode() / set_permission_mode():切換權限模式
TypeScript 也有 applyFlagSettings()updateSettings()
  • applyFlagSettings():在執行時應用設定,如 await session.applyFlagSettings({ effortLevel: "high" })。該方法採用設定檔鍵而不是選項欄位,因此請檢查 applyFlagSettings() 參考以了解架構以及哪些鍵在工作階段中途生效。
  • updateSettings():將允許清單中的一組鍵寫入專案的本機設定檔,如 await session.updateSettings("localSettings", { outputStyle: "Explanatory" })。寫入的鍵在工作階段的下一個請求上生效,並為載入 local 設定的後續工作階段持續。該方法在方法表中的行命名允許清單鍵和版本下限。
下面的範例執行一個兩回合工作階段,在回合之間變更設定,並列印回答每個回合的模型。在 TypeScript 中,提示流保持第二個訊息,直到設定器執行,第二個回合在新模型上執行。
在 Claude API 上,程式列印 First turn model: claude-sonnet-5,然後在切換後列印 Second turn model: claude-opus-5
每個模型都有自己的提示快取,因此在工作階段中途切換後,下一個請求會以新模型的費率重新計算完整對話未快取。如需詳細資訊,請參閱切換模型

設定特定功能

下表將每個選項對應到它設定的功能。如需本頁面未涵蓋的選項,請參閱 TypeScriptPython 參考。如果您知道您的目標但不知道哪個選項為其服務,請從選擇正確的功能開始。

後續步驟

若要查看組合成工作代理的設定:
  • 快速入門:端到端建立並執行第一個代理
  • 範例:找到完整、可執行的專案或符合您想要建立的內容的引導式 Claude Cookbook 配方
  • 多租戶隔離:使用 settingSources / setting_sourcesenvcwd 隔離每個租戶的設定和記憶