Claude Code SDK #45：Model Configuration 全解——model × effort × fallback × budget，把质量和成本分开调

先给结论：四个旋钮，管的是四件事

• model 决定「谁来做」：能力上限、知识范围，以及每个 token 的单价。
• effort 决定「愿意做多少」：会读多少文件、调用多少工具、验证多少次、走多少步。
• fallback 决定「主模型不可用时怎么办」：它是可用性策略，不是质量调参。
• budget / max_turns 决定「最多允许跑到哪里」：它们是硬护栏，不是模型路由。

1. model 与 effort：能力和投入不是一回事

1. Claude 已经拿到了相关上下文，也认真尝试了，但仍然在陌生领域或复杂架构上判断错误？这是能力问题，优先换更强的 model。
2. Claude 漏读文件、没跑测试、改到一半就停？这是投入问题，优先提高 effort。

# 复杂、含糊、需要架构判断的任务
claude --model opus --effort high "定位这个并发 bug，并给出可验证的修复"

# 机械、边界清楚的任务
claude --model sonnet --effort medium "给所有公开函数补上缺失的类型注解"

effort 的几个边界

2. 配置优先级：启动参数最适合做实验，settings 最适合做默认值

• 交互中用 /model 立即切换；交互式选择可以保存为新会话默认值。
• 启动时用 --model，只影响这次启动的会话，并覆盖 model 设置和 ANTHROPIC_MODEL。
• ANTHROPIC_MODEL 适合在 shell、容器或 CI 环境注入。
• settings 里的 model 只是初始选择，不等于强制锁定。

3. fallback：只解决不可用，不负责「答得更好」

claude --model opus --fallback-model sonnet,haiku "分析这次线上故障"

• fallback 只对当前轮次生效；下一条消息仍会先尝试主模型。
• 如果 fallback 模型不在 availableModels allowlist 中，它会在读取链时被丢弃，不会等到故障发生后才发现不可用。

4. 预算与轮数：CLI 和 Agent SDK 的硬护栏

claude -p \
  --model sonnet \
  --effort medium \
  --fallback-model haiku \
  --max-budget-usd 2.00 \
  --max-turns 6 \
  "检查最近改动，运行测试，并只输出 JSON 结果"

from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    model="sonnet",
    effort="high",
    fallback_model="haiku",
    max_turns=8,
    max_budget_usd=3.0,
    allowed_tools=["Read", "Glob", "Grep", "Edit", "Bash"],
)

async for message in query(
    prompt="检查 auth 模块，修复 bug，并运行最小必要测试",
    options=options,
):
    if hasattr(message, "result"):
        print(message.result)

5. 团队治理：model 不是 allowlist

{
  "model": "sonnet"
}

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "enforceAvailableModels": true,
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

6. 一套可落地的调参顺序

1. 先看上下文：文件、工具、CLAUDE.md 和任务边界是否完整。上下文缺失时，换模型通常只是更昂贵地猜。
2. 再看能力：确实是陌生领域、隐蔽 bug 或架构决策，提升 model。
3. 再看投入：漏读文件、没验证、过早收工，提升 effort。
4. 再加护栏：脚本加 max-budget-usd 和 max-turns；SDK 加 max_budget_usd 和 max_turns。
5. 最后做可用性兜底：为服务端过载配置 fallback，但不要把它当质量路由。
6. 团队统一策略：用 availableModels + enforceAvailableModels 做真正的模型边界；需要版本复现时固定完整模型名。

model 管能力，effort 管投入，fallback 管可用性，budget 管止损。

• Model configuration
• CLI reference
• Agent SDK Python reference
• Choosing a Claude model and effort level