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 請求參數
temperature、top_p 和 max_tokens 在任一語言的選項物件上都沒有欄位。改為設定努力級別或支出上限,或在您需要直接使用這些參數時呼叫 Messages API。設定環境變數
env 選項為執行您工作階段的 Claude Code 程序設定環境變數。您的值是否替換繼承的環境或合併到它上面因語言而異:
- TypeScript:
env替換子程序環境 - Python:SDK 將您的值合併到繼承的環境上,您的值覆蓋繼承的值
process.env 展開到 env 中以保留繼承的變數,例如 PATH、HOME 和 ANTHROPIC_API_KEY。當您不設定 env 時,子程序在兩種語言中都繼承您的環境。
該範例透過設定 ANTHROPIC_BASE_URL 將 API 流量路由通過閘道。
設定工作目錄
設定cwd 以在特定目錄中執行工作階段。當您不設定 cwd 時,工作階段會在您程序的工作目錄中執行。兩個 SDK 都沒有 cwd 的設定器。若要在不同目錄中執行,請使用該 cwd 啟動另一個工作階段。
Claude Code 讀取工作目錄以確定:
- 專案設定和 hooks:哪個專案的設定和 hooks 載入
- Skills:工作階段 skills 的發現位置
- 工作階段儲存:儲存的工作階段屬於哪個專案
additionalDirectories(TypeScript)或 add_dirs(Python)新增路徑。如需該授予的範圍,請參閱其他目錄授予檔案存取權,而非設定。
限制回合和支出
使用maxTurns / max_turns 和 maxBudgetUsd / max_budget_usd 限制回合和支出。當未設定時,兩個上限都關閉。當工作階段達到上限時,執行以結果訊息結束,其子類型命名上限,error_max_turns 或 error_max_budget_usd。接下來發生的情況因輸入模式而異:
- 單次
query():SDK 產生上限結果,然後引發,因此將迴圈包裝在 try 區塊中以在錯誤後繼續 - 串流輸入:工作階段在上限結果後保持活動,最大回合計數為每個排隊訊息重新開始。預算總計在訊息中累積,一旦支出達到上限,同一對話中的後續訊息以相同的預算結果結束。
/clear重新開始預算
0 的處理方式不同:
maxTurns/max_turns:0執行沒有回合限制的工作階段,與不設定選項相同maxBudgetUsd/max_budget_usd:CLI 在啟動時拒絕0作為無效金額,工作階段永遠不會執行
在工作階段中途變更設定
當您使用串流輸入啟動工作階段時,您可以在執行時切換其模型和權限模式。您呼叫設定器的位置因語言而異:- TypeScript:
query()傳回的物件上的方法 - Python:
ClaudeSDKClient上的方法,因為query()傳回沒有控制方法的純迭代器
setModel()/set_model():切換模型。不帶模型呼叫它以切換到 Claude Code 的預設模型,而不是您在選項中傳遞的model。setPermissionMode()/set_permission_mode():切換權限模式
applyFlagSettings() 和 updateSettings():
applyFlagSettings():在執行時應用設定,如await session.applyFlagSettings({ effortLevel: "high" })。該方法採用設定檔鍵而不是選項欄位,因此請檢查applyFlagSettings()參考以了解架構以及哪些鍵在工作階段中途生效。updateSettings():將允許清單中的一組鍵寫入專案的本機設定檔,如await session.updateSettings("localSettings", { outputStyle: "Explanatory" })。寫入的鍵在工作階段的下一個請求上生效,並為載入local設定的後續工作階段持續。該方法在方法表中的行命名允許清單鍵和版本下限。
First turn model: claude-sonnet-5,然後在切換後列印 Second turn model: claude-opus-5。
每個模型都有自己的提示快取,因此在工作階段中途切換後,下一個請求會以新模型的費率重新計算完整對話未快取。如需詳細資訊,請參閱切換模型。