Claude Code 深度学习手册

主题

模型配置（model/effort/thinking） ​

Claude Code 中通过 model（选哪个模型）、effort（自适应推理强度）、thinking（扩展思考开关）三组设置控制使用哪个模型、想多深、是否输出推理过程。

你的真实情况 ​

你这个会话跑的是 Opus 4.8（1M 上下文）。模型/推理强度可按任务和角色分别配，不用全程顶配。

去真实体验 ​

想干什么这样做
切模型/model（中途切，立即生效）
调推理强度/config 里 effort（low/medium/high/xhigh/max）
给某 subagent 配更省的模型它 frontmatter 写 model: haiku（如内置 Explore 就是 Haiku）
Fast mode（Opus 更快输出）/fast 切换（Opus 4.6/4.7/4.8 可用，溢价但快，不降级到小模型）

对你的实际意义（省钱又够用） ​

  • 分层用模型：主线复杂推理用 Opus；探索/检索类 subagent 用 Haiku（Explore 默认就是）——你 AGENTS.md 让"探索用 Explore"，正好顺带省钱。
  • effort 按任务调：写架构方案 high/max；改个小 bug low/medium，省 token。
  • agent teams 队友默认不继承你的 /model，可在 /config 设"默认队友模型"，研究类用 Sonnet 更划算。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

这是 Claude Code 的「模型配置」官方文档，讲三件事：一是 model 设置——用 alias（如 opus/sonnet/haiku/opusplan）或完整 model name（如 claude-opus-4-8）选模型，并支持企业级限制与第三方部署 pin 版本；二是 effort 设置——控制 adaptive reasoning（自适应推理）强度，分 low/medium/high/xhigh/max，外加 Claude Code 专属的 ultracode；三是 extended thinking——模型回答前输出的推理，可开关与控制显示。还涵盖 1M 扩展上下文、prompt caching 开关等环境变量。

怎么工作 ​

  • model 解析分两类：alias 指向「你当前 provider 推荐的版本」会随时间更新；要 pin 版本就用完整 model name（如 claude-opus-4-8）或对应 env（ANTHROPIC_DEFAULT_OPUS_MODEL 等）。
  • alias 在不同 provider 解析到不同版本：Anthropic API 上 opus=Opus 4.8、sonnet=Sonnet 4.6；Claude Platform on AWS 上 opus=Opus 4.7、sonnet=Sonnet 4.6；Bedrock/Vertex/Foundry 上 opus=Opus 4.6、sonnet=Sonnet 4.5。
  • model 设置优先级（从高到低）：会话内 /model > 启动 --model > 环境变量 ANTHROPIC_MODEL > settings 的 model 字段。Project/managed settings 始终更高，会在下次启动时重新生效。
  • default 不是 alias，而是清除 override、回到「你账户类型的推荐模型」的特殊值；其解析结果按订阅档位决定。
  • opusplan 是混合模式：plan mode 用 opus 做推理/架构决策，执行时自动切到 sonnet 做代码生成。plan 阶段 Opus 用标准 200K 上下文，不享受自动 1M 升级。
  • effort 控制 adaptive reasoning——模型按任务复杂度自行决定是否思考及思考多深；effort 等级是每模型独立校准的，同名等级在不同模型不代表相同底层值。
  • 若设了当前模型不支持的 effort 等级，会回落到「等于或低于该等级的最高支持等级」（例：xhigh 在 Opus 4.6 上按 high 跑）。
  • effort 来源优先级：环境变量 CLAUDE_CODE_EFFORT_LEVEL > 你配置的等级 > 模型默认；skill/subagent frontmatter 的 effort 在其激活时覆盖会话等级，但不覆盖环境变量。
  • extended thinking 在支持 adaptive reasoning 的模型上，主要由 effort 等级控制思考量，thinking 设置只负责开/关与显示方式。
  • Opus 4.7 及更新版本永远用 adaptive reasoning，fixed thinking budget 模式与 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 对其无效；只有 Opus 4.6 和 Sonnet 4.6 可回退到由 MAX_THINKING_TOKENS 控制的固定预算。

怎么配置 / 用法 ​

settings 文件设 model：{"model": "opus"}。企业限制可选模型：{"availableModels": ["sonnet", "haiku"]}（managed/policy settings 优先级最高，可做强 allowlist）。设 effort（仅接受 low/medium/high/xhigh）：{"effortLevel": "high"}；max 和 ultracode 是 session-only，settings 不接受。第三方多版本映射：{"modelOverrides": {"claude-opus-4-7": "arn:...:opus-prod"}}（key 必须是 Anthropic model ID）。命令行：claude --model opus、claude --effort high；会话内：/model sonnet、/effort、/effort auto、/model opus[1m]。扩展思考全局默认：/config 切换 thinking，保存为 ~/.claude/settings.json 的 alwaysThinkingEnabled。一次性深推理：prompt 里写 ultrathink。

什么时候用 ​

  • 日常编码任务用 sonnet（最新 Sonnet）；复杂推理用 opus；简单任务用 haiku；要最强用 best（当前等于 opus）。
  • 长会话/大代码库需要 1M 上下文时用 sonnet[1m] / opus[1m]，或在 alias/完整名后加 [1m]。
  • 想要「规划用 Opus、执行用 Sonnet」的自动混合，用 opusplan。
  • effort=low：短小、限定范围、对延迟敏感且不吃智力的任务；medium：成本敏感、可牺牲部分智力；high：默认平衡（Opus 4.8/4.6、Sonnet 4.6 默认）；xhigh：更深推理、更高 token（Opus 4.7 默认）；max：高难任务但可能过度思考、有边际递减，需先测试再大范围用。
  • 只想这一轮深思而不改会话设置：prompt 里加 ultrathink（注意 think/think hard/think more 不是关键字、当普通文本）。
  • 企业要完全管控模型：组合 availableModels + model + ANTHROPIC_DEFAULT_*_MODEL 三项（单靠 model 不是强制，用户仍能在 /model 选 Default 回到档位默认）。

限制 / 坑 ​

  • Opus 4.8 需要 Claude Code v2.1.154 或更高，运行 claude update 升级。
  • model 设置只是初始选择不是强制：用户仍可在 /model 选 Default 回到其档位的系统默认，绕过 model/availableModels 的版本 pin（需配 ANTHROPIC_DEFAULT_*_MODEL 才能锁住 Default）。
  • Default 选项不受 availableModels 影响，即使 availableModels:[] 用户仍能用 Default 模型。
  • availableModels 在多层级设置时是合并去重；要强 allowlist 必须放 managed/policy settings。
  • --model 和 ANTHROPIC_MODEL 只作用于本次启动的会话；多终端跑不同模型要各自 --model，不要用 /model 切。
  • resume/--continue/--resume 的会话保留 transcript 保存时的模型，若该模型已退役才回落到正常优先级。
  • opusplan 的 plan 阶段 Opus 只有 200K 上下文，自动 1M 升级不适用于 opusplan（除非通过 ANTHROPIC_DEFAULT_OPUS_MODEL 加 [1m]）。
  • effort 等级跨模型不可比：同名等级底层值不同，per model 校准。
  • max effort 无 token 花费上限、易过度思考、有边际递减；仅作用当前会话（除非经 CLAUDE_CODE_EFFORT_LEVEL 设置）。
  • ultracode 不是模型 effort 等级而是 Claude Code 设置：发 xhigh 给模型并编排 dynamic workflows，session-only，不属于 effortLevel/--effort/CLAUDE_CODE_EFFORT_LEVEL。
  • 所有 thinking token 都计费，即使被折叠或 redacted。
  • Sonnet 1M context 不在自动升级范围，所有订阅（含 Max）都要 usage credits；1M 上下文超过 200K 部分无额外溢价、按标准定价。
  • ANTHROPIC_SMALL_FAST_MODEL 已废弃，改用 ANTHROPIC_DEFAULT_HAIKU_MODEL。
  • ANTHROPIC_BASE_URL 只改请求去向不改回答的模型。
  • 第三方 provider 上 pin 的 provider-specific ID 可能无法被识别支持哪些特性，需用 _SUPPORTED_CAPABILITIES 显式声明，否则 effort/thinking 等会被禁用。
  • Foundry 没有 Bedrock/Vertex 那样的启动回退检查，遇到未启用的新模型会直接报错，所以必须提前 pin 三个 env。

硬事实速查（35 条） ​

  • model 可填 alias 或 model name；Bedrock 用 inference profile ARN、Foundry 用 deployment name、Vertex 用 version name。
  • Model aliases：default、best（=opus）、sonnet、opus、haiku、sonnet[1m]、opus[1m]、opusplan。
  • Anthropic API 上 opus=Opus 4.8、sonnet=Sonnet 4.6；Claude Platform on AWS 上 opus=Opus 4.7、sonnet=Sonnet 4.6；Bedrock/Vertex/Foundry 上 opus=Opus 4.6、sonnet=Sonnet 4.5。
  • Pin 具体版本用完整名如 claude-opus-4-8 或 env ANTHROPIC_DEFAULT_OPUS_MODEL。
  • Opus 4.8 需 Claude Code v2.1.154+。
  • model 设置优先级：会话 /model > 启动 --model > ANTHROPIC_MODEL > settings 的 model 字段。
  • v2.1.153 起 /model 会把选择写入 user settings 的 model 字段作为新会话默认；picker 中 Enter=切换并存默认、s=仅本会话；/model <name> 直输等同 Enter。
  • v2.1.144~v2.1.152 中 /model 仅作用当前会话，picker 中 d 才存默认。
  • availableModels 限制可选模型；Default 选项不受其影响；多层级合并去重；强 allowlist 放 managed/policy settings。
  • 完全管控三件套：availableModels + model + ANTHROPIC_DEFAULT_SONNET_MODEL/OPUS_MODEL/HAIKU_MODEL。
  • default 解析：Max/Team Premium/Enterprise pay-as-you-go/Anthropic API → Opus 4.8；Claude Platform on AWS → Opus 4.7；Pro/Team Standard/Enterprise 订阅席位 → Sonnet 4.6；Bedrock/Vertex/Foundry → Sonnet 4.5。命中 Opus 用量阈值可能自动回落 Sonnet。
  • effort 等级支持：Opus 4.8 与 Opus 4.7 = low/medium/high/xhigh/max；Opus 4.6 与 Sonnet 4.6 = low/medium/high/max（无 xhigh）。其他未列模型不支持 effort。
  • effort 默认：Opus 4.8/Opus 4.6/Sonnet 4.6 = high；Opus 4.7 = xhigh。首次跑 4.8/4.7 会套用该模型默认，需再 /effort 改。
  • low/medium/high/xhigh 跨会话持久；max 无 token 上限、仅当前会话（除非经 CLAUDE_CODE_EFFORT_LEVEL）。
  • ultracode：在 /effort 菜单，发 xhigh 并编排 dynamic workflows，session-only，可 /effort 设或经 --settings/Agent SDK 传 "ultracode": true。
  • 改 effort 途径：/effort（无参开滑块、带等级名直接设、auto 重置默认）、/model 内左右方向键、--effort flag、env CLAUDE_CODE_EFFORT_LEVEL（=等级名或 auto）、settings 的 effortLevel（仅 low/medium/high/xhigh）、skill/subagent frontmatter 的 effort。
  • effort 优先级：CLAUDE_CODE_EFFORT_LEVEL > 配置等级 > 模型默认；frontmatter 覆盖会话但不覆盖 env。
  • 当前 effort 显示在 logo 和 spinner 旁，如「with low effort」。
  • ultrathink：放在 prompt 任意位置请求该轮更深推理，不改会话 effort、发给 API 的 effort 不变；think/think hard/think more 不是关键字。
  • Opus 4.7+ 永远 adaptive reasoning，CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 与 fixed budget 对其无效；Opus 4.6/Sonnet 4.6 可设 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 回退由 MAX_THINKING_TOKENS 控制的固定预算。
  • extended thinking：会话切换 macOS Option+T / Win&Linux Alt+T；全局默认 /config 切换，存为 ~/.claude/settings.json 的 alwaysThinkingEnabled；MAX_THINKING_TOKENS=0 无视 effort 禁用思考。
  • 思考输出默认折叠，Ctrl+O 切换 verbose 显示为灰色斜体；API 交互会话默认收到 redacted thinking blocks，要全摘要设 showThinkingSummaries: true；所有 thinking token 都计费。
  • Extended context：Opus 4.6+ 与 Sonnet 4.6 支持 1M token 上下文。Max/Team/Enterprise 的 Opus 自动升级 1M（含 Team Standard 与 Premium）；Sonnet 1M 不在自动升级、所有计划含 Max 都需 usage credits；CLAUDE_CODE_DISABLE_1M_CONTEXT=1 禁用并从 picker 移除 1M 变体；1M 超 200K 部分无溢价。
  • [1m] 用法：/model opus[1m]、/model sonnet[1m]、/model claude-opus-4-8[1m]；env 如 ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'（含 opusplan）；Claude Code 发给 provider 前会去掉 [1m]；[1m] 按变量读取不按模型。
  • 查当前模型：status line（若配置）、/status（含账户信息）。
  • ANTHROPIC_CUSTOM_MODEL_OPTION 给 /model picker 加一个自定义条目，配 _NAME 和 _DESCRIPTION（默认描述 Custom model (<model-id>)），跳过 model ID 校验；条目出现在 picker 底部。
  • alias 映射 env：ANTHROPIC_DEFAULT_OPUS_MODEL（opus / plan mode 的 opusplan）、ANTHROPIC_DEFAULT_SONNET_MODEL（sonnet / 非 plan 的 opusplan）、ANTHROPIC_DEFAULT_HAIKU_MODEL（haiku / 后台功能）、CLAUDE_CODE_SUBAGENT_MODEL（所有 subagent 与 agent teams，设 inherit 用正常解析）。
  • ANTHROPIC_SMALL_FAST_MODEL 已废弃，用 ANTHROPIC_DEFAULT_HAIKU_MODEL。
  • 第三方部署须提前把三个 ANTHROPIC_DEFAULT_*_MODEL 设为具体版本 ID（Bedrock 例 us.anthropic.claude-opus-4-8、Vertex/Foundry 例 claude-opus-4-8）以控制升级时机。
  • _SUPPORTED_CAPABILITIES 取值：effort、xhigh_effort（min-version 2.1.111）、max_effort、thinking、adaptive_thinking、interleaved_thinking；设了则只启用所列、其余禁用，未设则按 model ID 内置检测。
  • _NAME/_DESCRIPTION/_SUPPORTED_CAPABILITIES 后缀对 ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL 与 ANTHROPIC_CUSTOM_MODEL_OPTION 均可用；_NAME/_DESCRIPTION 在 ANTHROPIC_BASE_URL 指向 LLM gateway 时也生效，直连 api.anthropic.com 时无效。
  • modelOverrides：key 必须是 Anthropic model ID（dated ID 要带日期后缀），未知 key 忽略；与 availableModels 共存且 allowlist 按 Anthropic ID 匹配；ANTHROPIC_MODEL/--model/ANTHROPIC_DEFAULT_*_MODEL 直接给的值原样传不被 modelOverrides 转换。
  • Mantle：availableModels 中以 anthropic. 开头的条目加入 /model picker 并路由到 Bedrock Mantle endpoint（alias-only 匹配的例外）。
  • prompt caching 自动开启；DISABLE_PROMPT_CACHING=1 全局禁用（优先于 per-model）、DISABLE_PROMPT_CACHING_HAIKU/SONNET/OPUS=1 按层禁用。
  • LLM gateway 可设 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 从 gateway 的 /v1/models 端点填充 picker。

官方出处：https://code.claude.com/docs/en/model-config