模型配置 - Claude Code Docs

可用模型

對於 Claude Code 中的 model 設定，您可以配置以下任一項：

一個模型別名
一個模型名稱
- Anthropic API：完整的**模型名稱**
- Bedrock：推論設定檔 ARN
- Foundry：部署名稱
- Vertex：版本名稱

模型別名

模型別名提供了一種便捷的方式來選擇模型設定，無需記住確切的版本號：

模型別名	行為
`default`	推薦的模型設定，取決於您的帳戶類型
`sonnet`	使用最新的 Sonnet 模型（目前為 Sonnet 4.6）進行日常編碼任務
`opus`	使用最新的 Opus 模型（目前為 Opus 4.6）進行複雜推理任務
`haiku`	使用快速高效的 Haiku 模型進行簡單任務
`sonnet[1m]`	使用 Sonnet 搭配100 萬個 token 的 context window進行長時間會話
`opus[1m]`	使用 Opus 搭配100 萬個 token 的 context window進行長時間會話
`opusplan`	特殊模式，在計畫模式期間使用 `opus`，然後在執行時切換到 `sonnet`

別名始終指向最新版本。若要固定到特定版本，請使用完整模型名稱（例如 claude-opus-4-6）或設定相應的環境變數，如 ANTHROPIC_DEFAULT_OPUS_MODEL。

設定您的模型

您可以透過多種方式配置模型，按優先順序列出：

在會話期間 - 使用 /model <alias|name> 在會話中途切換模型
在啟動時 - 使用 claude --model <alias|name> 啟動
環境變數 - 設定 ANTHROPIC_MODEL=<alias|name>
設定 - 在設定檔中使用 model 欄位永久配置。

使用範例：

# 使用 Opus 啟動
claude --model opus

# 在會話期間切換到 Sonnet
/model sonnet

設定檔範例：

{
    "permissions": {
        ...
    },
    "model": "opus"
}

限制模型選擇

企業管理員可以在受管理或政策設定中使用 availableModels 來限制使用者可以選擇的模型。設定 availableModels 後，使用者無法透過 /model、--model 旗標、Config 工具或 ANTHROPIC_MODEL 環境變數切換到清單中沒有的模型。

{
  "availableModels": ["sonnet", "haiku"]
}

預設模型行為

模型選擇器中的「預設」選項不受 availableModels 影響。它始終保持可用，並代表系統的執行時預設值基於使用者的訂閱層級。即使使用 availableModels: []，使用者仍然可以使用其層級的預設模型來使用 Claude Code。

控制使用者執行的模型

若要完全控制模型體驗，請將 availableModels 與 model 設定一起使用：

availableModels：限制使用者可以切換到的內容
model：設定明確的模型覆蓋，優先於預設值

此範例確保所有使用者執行 Sonnet 4.6，並且只能在 Sonnet 和 Haiku 之間選擇：

{
  "model": "sonnet",
  "availableModels": ["sonnet", "haiku"]
}

合併行為

當 availableModels 在多個層級設定時（例如使用者設定和專案設定），陣列會被合併並去重。若要強制執行嚴格的允許清單，請在受管理或政策設定中設定 availableModels，這具有最高優先順序。

特殊模型行為

`default` 模型設定

default 的行為取決於您的帳戶類型：

Max 和 Team Premium：預設為 Opus 4.6
Pro 和 Team Standard：預設為 Sonnet 4.6
Enterprise：Opus 4.6 可用但不是預設值

如果您達到 Opus 的使用閾值，Claude Code 可能會自動回退到 Sonnet。

`opusplan` 模型設定

opusplan 模型別名提供了一種自動化的混合方法：

在計畫模式中 - 使用 opus 進行複雜推理和架構決策
在執行模式中 - 自動切換到 sonnet 進行程式碼生成和實現

這為您提供了兩全其美的方案：Opus 優越的推理能力用於計畫，Sonnet 的效率用於執行。

調整努力等級

努力等級控制自適應推理，根據任務複雜性動態分配思考。較低的努力對於直接的任務更快且更便宜，而較高的努力為複雜問題提供更深入的推理。三個等級在會話中持續存在：low、medium 和 high。第四個等級 max 提供最深入的推理，對 token 支出沒有限制，因此回應速度較慢且成本高於 high。max 僅在 Opus 4.6 上可用，除了透過 CLAUDE_CODE_EFFORT_LEVEL 環境變數外，不會在會話間持續。 Opus 4.6 和 Sonnet 4.6 預設為中等努力。這適用於所有提供者，包括 Bedrock、Vertex AI 和直接 API 存取。中等是大多數編碼任務的推薦等級：它平衡了速度和推理深度，較高的等級可能會導致模型過度思考日常工作。保留 high 或 max 用於真正受益於更深入推理的任務，例如困難的除錯問題或複雜的架構決策。對於一次性的深入推理而不改變您的會話設定，在您的提示中包含「ultrathink」以觸發該輪的高努力。 設定努力：

/effort：執行 /effort low、/effort medium、/effort high 或 /effort max 來變更等級，或執行 /effort auto 以重設為模型預設值
在 /model 中：選擇模型時使用左/右箭頭鍵調整努力滑塊
--effort 旗標：在啟動 Claude Code 時傳遞 low、medium、high 或 max 以為單一會話設定等級
環境變數：設定 CLAUDE_CODE_EFFORT_LEVEL 為 low、medium、high、max 或 auto
設定：在設定檔中設定 effortLevel 為 "low"、"medium" 或 "high"
Skill 和 subagent frontmatter：在 skill 或 subagent markdown 檔案中設定 effort 以在該 skill 或 subagent 執行時覆蓋努力等級

環境變數優先於所有其他方法，然後是您配置的等級，然後是模型預設值。Frontmatter 努力在該 skill 或 subagent 活動時適用，覆蓋會話等級但不覆蓋環境變數。 Opus 4.6 和 Sonnet 4.6 支援努力。當選擇支援的模型時，努力滑塊會出現在 /model 中。目前的努力等級也會顯示在標誌和微調器旁邊，例如「with low effort」，因此您可以確認哪個設定處於活動狀態，而無需開啟 /model。若要在 Opus 4.6 和 Sonnet 4.6 上禁用自適應推理並恢復到先前的固定思考預算，請設定 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1。禁用時，這些模型使用由 MAX_THINKING_TOKENS 控制的固定預算。請參閱環境變數。

擴展 context

Opus 4.6 和 Sonnet 4.6 支援100 萬個 token 的 context window，用於具有大型程式碼庫的長時間會話。可用性因模型和計畫而異。在 Max、Team 和 Enterprise 計畫上，Opus 會自動升級到 1M context，無需額外配置。這適用於 Team Standard 和 Team Premium 席位。

計畫	Opus 4.6 搭配 1M context	Sonnet 4.6 搭配 1M context
Max、Team 和 Enterprise	包含在訂閱中	需要額外使用
Pro	需要額外使用	需要額外使用
API 和隨用隨付	完全存取	完全存取

若要完全禁用 1M context，請設定 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。這會從模型選擇器中移除 1M 模型變體。請參閱環境變數。 1M context window 使用標準模型定價，超過 200K 的 token 無需額外費用。對於訂閱中包含擴展 context 的計畫，使用量仍由您的訂閱涵蓋。對於透過額外使用存取擴展 context 的計畫，token 會計入額外使用。如果您的帳戶支援 1M context，該選項會出現在最新版本 Claude Code 的模型選擇器（/model）中。如果您看不到它，請嘗試重新啟動您的會話。您也可以將 [1m] 後綴與模型別名或完整模型名稱一起使用：

# 使用 opus[1m] 或 sonnet[1m] 別名
/model opus[1m]
/model sonnet[1m]

# 或將 [1m] 附加到完整模型名稱
/model claude-opus-4-6[1m]

檢查您目前的模型

您可以透過多種方式查看您目前使用的模型：

在狀態行中（如果已配置）
在 /status 中，它也會顯示您的帳戶資訊。

新增自訂模型選項

使用 ANTHROPIC_CUSTOM_MODEL_OPTION 將單一自訂項目新增到 /model 選擇器，而無需取代內建別名。這對於 LLM 閘道部署或測試 Claude Code 預設不列出的模型 ID 很有用。此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

自訂項目出現在 /model 選擇器的底部。ANTHROPIC_CUSTOM_MODEL_OPTION_NAME 和 ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION 是可選的。如果省略，模型 ID 會用作名稱，描述預設為 Custom model (<model-id>)。 Claude Code 會跳過在 ANTHROPIC_CUSTOM_MODEL_OPTION 中設定的模型 ID 的驗證，因此您可以使用您的 API 端點接受的任何字串。

環境變數

您可以使用以下環境變數，這些變數必須是完整的模型名稱（或您的 API 提供者的等效項），以控制別名對應到的模型名稱。

環境變數	描述
`ANTHROPIC_DEFAULT_OPUS_MODEL`	用於 `opus` 的模型，或在 Plan Mode 活動時用於 `opusplan` 的模型。
`ANTHROPIC_DEFAULT_SONNET_MODEL`	用於 `sonnet` 的模型，或在 Plan Mode 未活動時用於 `opusplan` 的模型。
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	用於 `haiku` 的模型，或背景功能
`CLAUDE_CODE_SUBAGENT_MODEL`	用於 subagents 的模型

注意：ANTHROPIC_SMALL_FAST_MODEL 已棄用，改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。

為第三方部署固定模型

透過 Bedrock、Vertex AI 或 Foundry 部署 Claude Code 時，在向使用者推出前固定模型版本。不固定模型時，Claude Code 使用模型別名（sonnet、opus、haiku），這些別名會解析為最新版本。當 Anthropic 發佈新模型時，帳戶未啟用新版本的使用者將無聲地中斷。

在初始設定中將所有三個模型環境變數設定為特定版本 ID。跳過此步驟意味著 Claude Code 更新可能會在您無需採取任何行動的情況下破壞您的使用者。

使用以下環境變數搭配您提供者的版本特定模型 ID：

提供者	範例
Bedrock	`export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'`
Vertex AI	`export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'`
Foundry	`export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'`

對 ANTHROPIC_DEFAULT_SONNET_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 應用相同的模式。有關所有提供者的目前和舊版模型 ID，請參閱模型概述。若要將使用者升級到新模型版本，請更新這些環境變數並重新部署。若要為固定模型啟用擴展 context，請將 [1m] 附加到 ANTHROPIC_DEFAULT_OPUS_MODEL 或 ANTHROPIC_DEFAULT_SONNET_MODEL 中的模型 ID：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'

[1m] 後綴將 1M context window 應用於該別名的所有使用，包括 opusplan。Claude Code 在將模型 ID 發送到您的提供者之前會移除該後綴。只有當基礎模型支援 1M context（例如 Opus 4.6 或 Sonnet 4.6）時，才附加 [1m]。

使用第三方提供者時，settings.availableModels 允許清單仍然適用。篩選會根據模型別名（opus、sonnet、haiku）進行匹配，而不是提供者特定的模型 ID。

按版本覆蓋模型 ID

上述家族級環境變數為每個家族別名配置一個模型 ID。如果您需要將同一家族內的多個版本對應到不同的提供者 ID，請改用 modelOverrides 設定。 modelOverrides 將個別 Anthropic 模型 ID 對應到 Claude Code 發送到您提供者 API 的提供者特定字串。當使用者在 /model 選擇器中選擇對應的模型時，Claude Code 會使用您配置的值而不是內建預設值。這讓企業管理員可以將每個模型版本路由到特定的 Bedrock 推論設定檔 ARN、Vertex AI 版本名稱或 Foundry 部署名稱，以進行治理、成本分配或區域路由。在您的設定檔中設定 modelOverrides：

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  }
}

鍵必須是模型概述中列出的 Anthropic 模型 ID。對於日期模型 ID，請包含日期後綴，完全如其所示。未知的鍵會被忽略。覆蓋會取代支援 /model 選擇器中每個項目的內建模型 ID。在 Bedrock 上，覆蓋優先於 Claude Code 在啟動時自動發現的任何推論設定檔。您直接透過 ANTHROPIC_MODEL、--model 或 ANTHROPIC_DEFAULT_*_MODEL 環境變數提供的值會按原樣傳遞給提供者，不會由 modelOverrides 轉換。 modelOverrides 與 availableModels 一起運作。允許清單會根據 Anthropic 模型 ID 進行評估，而不是覆蓋值，因此 availableModels 中的項目（如 "opus"）即使 Opus 版本對應到 ARN 時仍會繼續匹配。

Prompt caching 配置

Claude Code 自動使用 prompt caching 來優化效能並降低成本。您可以全域禁用 prompt caching 或針對特定模型層級禁用：

環境變數	描述
`DISABLE_PROMPT_CACHING`	設定為 `1` 以禁用所有模型的 prompt caching（優先於每個模型的設定）
`DISABLE_PROMPT_CACHING_HAIKU`	設定為 `1` 以僅禁用 Haiku 模型的 prompt caching
`DISABLE_PROMPT_CACHING_SONNET`	設定為 `1` 以僅禁用 Sonnet 模型的 prompt caching
`DISABLE_PROMPT_CACHING_OPUS`	設定為 `1` 以僅禁用 Opus 模型的 prompt caching

這些環境變數為您提供對 prompt caching 行為的細粒度控制。全域 DISABLE_PROMPT_CACHING 設定優先於模型特定的設定，讓您可以在需要時快速禁用所有快取。每個模型的設定對於選擇性控制很有用，例如在偵錯特定模型或使用可能具有不同快取實現的雲端提供者時。

設定

​可用模型

​模型別名

​設定您的模型

​限制模型選擇

​預設模型行為

​控制使用者執行的模型

​合併行為

​特殊模型行為

​default 模型設定

​opusplan 模型設定

​調整努力等級

​擴展 context

​檢查您目前的模型

​新增自訂模型選項

​環境變數

​為第三方部署固定模型

​按版本覆蓋模型 ID

​Prompt caching 配置

可用模型

模型別名

設定您的模型

限制模型選擇

預設模型行為

控制使用者執行的模型

合併行為

特殊模型行為

`default` 模型設定

`opusplan` 模型設定

調整努力等級

擴展 context

檢查您目前的模型

新增自訂模型選項

環境變數

為第三方部署固定模型

按版本覆蓋模型 ID

Prompt caching 配置