在 Claude Code 中选择模型与努力程度的指南
英文标题：Choosing a Claude model and effort level in Claude Code
本文深入解释了 Claude Code 中模型选择与努力程度（effort level）的工作原理。模型由固定权重驱动，决定回答的“知识能力”，而努力程度则控制模型在每个任务上投入的思考和验证量（即生成 token 的数量）。文章提供了实际场景下的选择建议，例如例行任务用小模型、复杂问题用大模型，并指出默认设置适用于大多数情况，调整应先从检查上下文开始。对开发者而言，理解这两者的区别有助于在成本、速度与输出质量之间取得最佳平衡。
11.7 KB
403 B
154.9 KB
173.8 KB
129.5 KB
162.4 KB
175.7 KB
183.8 KB
238.1 KB
259.6 KB
225.0 KB
280.0 KB
27.9 KB
13.6 KB
8.1 KB
9.5 KB
12.4 KB
中文
模型选择的工作原理
当你按下回车键时，Claude Code 会将你的消息与系统提示、工具定义、你的 CLAUDE.md 文件、对话历史以及上下文中的任何文件组合在一起。所有这些内容会作为一个请求发送到 API。
Claude Code 拥有的所有内容都会被打包进一个 API 请求。在服务器端，文本在到达模型之前会先进行分词。
不过，模型永远看不到纯文本。服务器端发生的第一件事是分词；文本被拆分成片段，每个片段被映射到模型训练时所用固定词汇表中的一个整数。const 可能映射到 1978，await 可能映射到 4293。从这时起，你的提示词就是一个整数数组了。
分词器将文本拆分成片段，并将每个片段映射到固定词汇表中的一个整数。上面一行中的每个块都变成它对应的 token ID（下面一行）；所示 ID 仅为示意。
模型的职责是接收这个数组并预测下一个 token 是什么。它通过计算词汇表中每个 token 的概率并从最高的里面挑选来实现这一点。在 const x = await 之后，一个训练良好的模型会给 fetch 赋予很高的概率（非常可能），而给 banana 接近零的概率（完全不可能）。
模型的预测给出的是词汇表中每个 token 的概率。最佳猜测和一个完全不相关的 token 之间的差距是巨大的。
将你的输入 token 转化为这些概率的是权重（也称为参数）。这是数十亿个组织成大型矩阵的数字。为了预测一个 token，模型会让你的输入通过这些矩阵，进行一连串的矩阵乘法运算，然后在末端读出概率。权重是模型所“知道”的一切内容的寄存之处。
每个模型的权重都是在训练期间设定的，到你发送请求时它们已经是只读的了。 你的提示词、你的 CLAUDE.md 文件或你的上下文都不会改变它们。（如果你遇到过“推理”这个词，它的全部含义就是：训练完成后，在权重固定的情况下使用模型。）
你的提示词进入，概率出来。中间的权重不会改变。
Claude 所了解的关于 TypeScript、热门框架、地道的 Go 或任何其他通用编程知识，都是在训练时被编码到这些权重中的。
你的提示词和上下文仍然可以引导预测（将你的真实代码放在 Claude 面前就是一种引导，而且效果非常好），但它们不会向权重本身添加任何东西。
如果某个库在模型训练时还不存在，它就不在权重中。你可以将文档放进上下文，Claude 会使用它，但那是引导，而不是教导。Claude 的响应只会对那一次请求产生影响；底层模型并没有保留这些信息。
所以，当 Claude 自信地调用一个根本不存在的 API（幻觉）时，那是权重在生成一个根据训练模式看起 plausible 的 token 序列，而不是一次失败的查找。
那么更换模型实际上起到了什么作用？它换掉了处理你请求的那组冻结权重。
模型并不一次性生成整个回答。它预测一个 token，将它追加到序列中，然后重新运行整个计算过程以获取下一个 token。一个 200 token 的响应意味着要通过权重进行 200 次独立计算。这个循环是你大部分等待时间和输出成本的来源。
序列每一步恰好增加一个 token。模型每次都要重新读取整个数组来预测接下来会出现什么。
所以模型设置决定了哪些权重处理你的请求，同时也决定了每个输出 token 的成本。
它决定不了的，是生成多少个 token。这个数字对于同一个提示词可能会有很大差异，具体取决于 Claude 决定做多少工作。
这就是努力程度所控制的东西：Claude 在每一轮中决定做多少工作。
努力程度如何起作用
当 Claude Code 在完成一项任务时，它生成的 token 可以划分为几类：
- 思考：你在操作之前和之间看到的流式输出推理。
- 工具调用：命名了某个工具及其参数的结构化块，例如 Read 或 Edit，然后由 Claude Code 解析并执行。
- 给你的文本：计划、进度更新、最后的总结。
所有这些都是来自同一个循环的普通输出 token，按相同费率计费。例如，思考 token 的生成方式与其他输出 token 完全相同，并在该轮余下的时间内保留在上下文中。
当 Claude 转而开始写代码时，它早前的推理就像它读取过的文件一样成为输入的一部分。
Claude 的所有输出都是 token。思考、工具调用和给你的文本都产生于同一个循环。
努力程度如何改变这一切呢？努力程度作为请求的一部分发送给模型，就在你的提示词旁边。模型被训练成理解每个努力程度下该如何行动，这种学习到的行为被固化在了冻结的权重里。
当你的请求到达时，努力程度是模型响应的另一个输入，就像它响应你的提示词文本一样。这设定了 Claude 在它认为任务完成之前需要多么细致和确定的行为模式。
这会在每一轮中被考虑到，并产生更多的 token 以给出置信度更高的答案。
相同的提示词，两种努力程度。高努力程度路径生成了大约 7 倍的 token 来达到一个置信度更高的答案。
在较高的努力程度下，Claude 常常会从制定计划开始，而努力程度的高低会影响该计划的深度和广度。然而，计划并非一成不变。当 Claude 从它的行动中收到结果时，它会更新已取得的进展以及它对累积结果的确定程度。
因此，当一个三步调试计划中的第一步就发现了错误时，“调查假设二和假设三”可能就不再是必要的行动了。Claude 通常会明确说出来：“第一次检查就找到了，所以不需要剩下的检查了”，然后跳过。你会在 Claude Code 中看到当任务列表在运行中被修订时发生这种情况。
在较高的努力程度下，Claude 会更容易倾向于复查额外的假设或验证正确性，但对于简单的任务，它在高努力程度下通常不会人为地增加使用量。事实上，我们的团队在模型训练期间会对“过度思考”密切关注，因为它会降低有效性。
选择努力程度
我们的指导是，对于大多数任务，你应该使用模型的默认努力程度。默认程度是 Claude 会根据大多数人为一项任务愿意花费的 token 量来调整其 token 使用的水平。
将努力程度视为一种手动控制拨盘，用来调整 Claude 工作的努力程度和时长。当你根据你的领域或工作类型对细致度或速度有强烈偏好时，可以刻意选择它。更多地将其视为一种总体偏好，而不是针对每个任务逐次做出的决定。
在Claude Opus 4.8 发布之后，一些可能有助于指导你的实际见解：在我们的测试中，我们发现当你对 Opus 4.8 使用默认努力设置时，与对同一任务使用 Opus 4.7 的默认努力设置相比，它会在生成大致相同数量的 token 的情况下给出更好的结果。
当 Claude 出错时该调整什么
当 Claude 出错时，你的第一反应不应该是去调整旋钮，而是检查你提供的上下文。你的提示词是否太模糊？Claude 是否连接到了正确的工具？是否配备了合适的技能？
如果你要为一个不应该需要那么高努力程度的任务增加努力程度，那么修复工作往往在上游——在你的上下文、你的 CLAUDE.md 文件或任务的范围限定中。
但假设你已经提供了清晰的上下文而 Claude 仍然出错了，你需要问自己的问题是：它是尝试得不够，还是了解得不够？
两个问题，一个后备方案。把这个启发式方法用作选择起点的参考，而不是一条硬性规则。
模型：问题太难了
当问题真正困难时选择更大的模型。例如，诸如细微的 bug、不熟悉的领域或架构决策之类的问题。对于那种无论你给多少上下文，较小模型都自信地出错的情况，更大模型能起到帮助。
更大的模型也更擅长处理模棱两可的情况，而对于较小模型，引导其执行的具体指令往往是成功的更好配方。
当工作是常规任务时选择较小的模型。例如，你能精确描述的编辑、机械性的改动，或者关于已存在于上下文中的代码的问题。没有理由为任务不需要的能力付费。
如果 Claude 已拥有所有相关上下文并且明显尝试了但仍然出错，这便是一个选用更大模型的信号。而如果你已经用着更大的模型，且一段时间以来都是常规工作，那么降低模型则能提高速度，并通常能在不降低输出质量的同时降低成本。
努力程度：Claude 不够努力
如果 Claude 因为跳过一个文件、没有运行测试或没有复查自己的工作而出错，则选择更高的努力程度。这种情况在你选择了低于模型默认程度的努力水平时最相关。
Fable 对比 Opus 对比 Sonnet：专才、专家与通才
我喜欢用来思考这两种设置之间关系的一种方式是：Fable 是一位见过几乎无人见过的难题的专才，Opus 是专家，而 Sonnet 是一位非常优秀的通才。努力程度则决定了他们中任何一位在你的任务上投入多少时间。
低努力程度的 Opus 就像是与一位对你的这类问题有深厚经验的专家交谈五分钟。他们带来了你代码库中不存在于任何地方的知识：他们以前见过的模式，他们知道要去检查的陷阱，这种知识只能通过解决过大量类似问题来获得。但只给他们五分钟意味着快速浏览你的代码，而不是仔细阅读。
高努力程度的 Sonnet 就像是给一位非常优秀的通才一整个下午的时间。他们会阅读所有内容，运行各种东西，复查他们的工作，并最终彻底理解你的具体代码。他们所缺少的是那种“我以前完全见过这种情况”的辨识力。
即使是低努力程度的 Fable，也是这位专才瞥了一眼所有其他人都被卡住的问题，并且仍然发现了其他人谁都发现不了的东西。这种辨识力是你最花钱的地方，所以值得把它留给那些真正需要它的任务。
这些没有哪个是普遍更好的。模型设置大致是有多大能力；努力程度设置大致是有多细致。大多数实际任务两者都需要一些。
努力程度、模型与 token 消耗
那么模型选择、努力程度和 token 消耗这三者如何相互作用呢？这取决于任务。
在相同的努力程度下处理常规工作时，两个模型通常都能做对。更大模型会以更高的单 token 价格消耗更多的 token 来进行额外的验证步骤。这就是为什么在常规工作阶段切换到较小模型可以实在节省成本而不牺牲质量。
曲线仅用于示意，展示的是对一个简单到两个模型都能快速完成的任务，并不能代表真实的基准数据。
在更困难、多步骤的工作上，等式就不同了。较小模型必须在其能力极限附近“苦战”，消耗多次迭代，而更大模型则以更少的步骤达到相同的质量水平。
你为更大模型支付的单 token 价格更高，但在那些真正让较小模型难以胜任的任务上，每个任务的总成本可能会更低。此外，更重要的是，较大模型能完成较小模型即使在最高努力程度设置下也无法完成的任务。
这一点在 Fable 上表现最为突出。在漫长、多步骤的工作中，它领先得最多。在我们的测试中，它完成了 Opus 和 Sonnet 在任何努力程度下都无法达到的任务。它的单 token 成本也最高，这也是要把它留给需要它的工作的另一个原因。
曲线仅用于示意，展示的是对一个困难到让两个模型都有些吃力的任务，并不能代表真实的基准数据。
以上图表的关键点是，努力程度选择了 Claude 愿意沿着曲线走多远，但依旧，这并不意味着 Claude 需要走那么远才能完成任务。
另一个细微之处在于：努力程度会影响 token 消耗，但并不限制它。系统中唯一的硬性上限是max_tokens，它会在达到上限时截断中途的响应。这是一个粗放的仪表，主要与 API 开发者相关。更柔性的控制，如任务预算或是在提示词中让 Claude 保持简洁，是更有帮助的工具。它们充当模型经过训练会去遵循的指导——如果接近限制，它会设法结束任务——而不是直接撞上一堵墙。
从默认设置开始，然后再使用拨盘
大多数时候，你不应该考虑这两个设置。当某个结果不达预期时，问问“是 Claude 不够懂，还是它不够努力？”，然后根据需要调整。
本文由 Claude Code 团队技术人员 Lydia Hallie 撰写。
English / 原文
How model selection works
When you press enter, Claude Code assembles your message together with the system prompt, tool definitions, your CLAUDE.md, the conversation history, and any files in context. All of this is sent as one request to the API.
Everything Claude Code has gets packed into one API request. On the server, the text is tokenized before it ever reaches the model.
The model never sees that as plain text, though. The first thing that happens on the server is tokenization ; the text is split into pieces, and each piece is mapped to an integer from a fixed vocabulary the model was trained with. const might map to 1978, await might map to 4293. From here on, your prompt is an array of integers.
The tokenizer splits your text into pieces and maps each piece to an integer in a fixed vocabulary. Each chunk in the top row becomes its token ID (bottom row); IDs shown are illustrative.
The model's job is to take that array and predict which token comes next. It does this by computing a probability for every token in its vocabulary and picking from the top. After const x = await, a well-trained model puts high probability on fetch (very likely) and near-zero on banana (not likely at all).
The model’s prediction is a probability for every token in its vocabulary. The gap between the top guess and an unrelated one is enormous.
What turns your input tokens into those probabilities is the weights (also called parameters). These are billions of numbers organized into large matrices. To predict one token, the model runs your input through those matrices, a long chain of matrix multiplications, and reads the probabilities at the end. The weights are where everything the model "knows" lives.
The weights of each model are set during training, and by the time you're sending requests they're read-only. Nothing in your prompt, your CLAUDE.md, or your context changes them. (If you've run into the word inference, that's all it means: using the model after training is done, with the weights fixed.)
Your prompt goes in, probabilities come out. The weights in the middle don’t change.
Everything Claude knows about TypeScript, popular frameworks, idiomatic Go, or any other general programming knowledge, was encoded into those weights at training time.
Your prompt and context can still steer the prediction (putting your real code in front of Claude is steering , and it works really well), but they don't add anything to the weights themselves.
If a library didn't exist when the model was trained, it isn't in the weights. You can put the docs in context and Claude will use them, but that's steering , not teaching. Claude’s response will only be influenced for that request; the underlying model hasn’t retained the information.
So when Claude confidently calls an API that doesn't exist (a hallucination), that's the weights producing a token sequence that looks plausible from training patterns, not a failed lookup.
So what does changing the model actually do? It swaps which set of frozen weights handles your request.
The model doesn't generate a whole answer at once. It predicts one token, appends it to the sequence, and runs the whole computation again to get the next one. A 200-token response is 200 separate passes through the weights. This loop is where most of your wait time and your output cost come from.
The sequence grows by exactly one token per step. The model re-reads the whole array each time to predict what comes next.
So the model setting decides which weights handle your request, and it also decides what each output token costs.
What it doesn't decide is how many tokens get generated. That number can vary a lot for the same prompt, depending on how much work Claude decides to do.
This is what effort level controls: how much work Claude decides to do for each turn.
How effort works
When Claude Code is working on a task, the tokens it generates fall into a few categories:
- Thinking : the reasoning you see streaming before and between actions.
- Tool calls : structured blocks naming a tool like Read or Edit and its arguments, which Claude Code then parses and executes.
- Text to you : the plan, progress updates, the summary at the end.
These are all ordinary output tokens from the same loop, billed at the same rate. For example, thinking tokens are generated exactly like the other output tokens and stay in context for the rest of that turn.
When Claude moves on to writing code, its earlier reasoning is part of the input just like a file it’s read.
All of Claude’s output is tokens. Thinking, tool calls, and text to you are all generated from the same loop.
How does effort change any of this? The effort level is sent to the model as part of the request, right alongside your prompt. The model was trained to understand how to behave at each effort level and that learned behavior is baked into the frozen weights.
When your request arrives, effort level is one more input the model responds to, the same way it responds to your prompt text. This sets Claude’s behavior for how thorough and certain it needs to be before it considers the task done.
This is considered on every turn and**** results in more tokens to produce higher confidence answers.
Same prompt, two effort levels. The high effort path generates roughly 7x more tokens to reach a higher confidence answer.
At higher effort levels, Claude often starts with creating a plan and the level of effort influences the depth and breadth of that plan. However, the plan is not frozen in place. As Claude receives results from its actions, it updates the progress that has been made and how certain it is of the accumulated result.
So when step 1 of a three-hypothesis debugging plan finds the bug, "investigate hypotheses 2 and 3" may no longer be necessary actions. Claude will typically say this explicitly, "the first check found it, so the remaining checks aren't needed" and skip ahead. You see this happen in Claude Code when task lists get revised mid-run.
Claude will be more predisposed to double-checking additional hypotheses or verifying correctness at higher effort levels, but it generally won’t artificially inflate usage for simple tasks at higher effort levels. In fact, our team pays close attention to “overthinking” during model training as it degrades effectiveness.
Picking an effort level
Our guidance is thatfor most tasks you should use the model’s default effort level. The default is the level where Claude will scale its token usage according to what most people would want to spend on a task.
Think of effort as a manual override to scale how hard and long Claude works. Choose it deliberately when you have a strong preference for thoroughness or speed based on your domain or the type of work you do. Consider this more as a general preference than a task-by-task decision.
Some practical insight that may help guide you following the launch of Claude Opus 4.8: in our testing we found when you use the default effort setting for Opus 4.8, it will produce better results for about the same number of tokens when compared to using the default effort setting of Opus 4.7 for the same task.
What to change when Claude gets it wrong
When Claude gets something wrong, your first instinct shouldn’t be to adjust a knob, but to examine the context you have provided. Is your prompt too vague? Is Claude connected to the right tools? Equipped with the right skills?
If you're increasing effort on a task that shouldn't need it, the fix is often upstream, in your context, your CLAUDE.md, or how the task is scoped.
But assuming you have provided clear context and Claude still gets something wrong, the question to ask yourself is: did it not try hard enough, or did it not know enough?
Two questions, one fallback. Use the heuristic to pick a starting point, not a hard rule.
Model: The problem was too hard
Pick a larger model when the problem is genuinely hard. For example, problems like subtle bugs, unfamiliar domains, or architecture decisions. A larger model is helpful for situations where the smaller model is confidently wrong no matter how much context you give it.
Larger models are also better at handling ambiguity, whereas specific instructions directing execution are a better recipe for success on the smaller models.
Pick a smaller model when the work is routine. For example, edits you can describe precisely, mechanical changes, or questions about code that's already in context. There's no reason to pay for capability the task doesn't need.
If Claude has all the pertinent context and clearly tried and still got it wrong, that's a signal to pick a larger model. If you're on the larger model and the work has been routine for a while, dropping down will increase speed and typically reduce cost without impacting the quality of the output.
Effort: Claude didn’t try hard enough
Pick a higher effort level if Claude got it wrong by skipping a file, not running the tests, or not double-checking its work. This is most relevant if you selected an effort level below the model’s default.
Fable vs. Opus vs. Sonnet: The specialist, the expert, and the generalist
One way I like to think about how the two settings relate: Fable is a specialist who's seen problems almost no one else has, Opus is the expert, and Sonnet is a really good generalist. The effort level decides how much time any of them spends on your task.
Opus at low effort is like getting five minutes with an expert who has deep experience with problems like yours. They bring knowledge that isn't anywhere in your codebase: patterns they've seen before, gotchas they know to check for, the kind of thing you only get from having solved a lot of similar problems. But just giving them five minutes means a quick read of your code, not a careful one.
Sonnet at high effort is like giving a really good generalist the whole afternoon. They'll read everything, run things, double-check their work, and end up understanding your specific code thoroughly. What they bring less of is that "I've seen exactly this before" recognition.
Fable, even at low effort, is that specialist glancing at the problem everyone else is stuck on and still spotting the thing no one else would. That recognition is what you're paying the most for, so it's worth saving for the tasks that genuinely need it.
None of these is universally better. The model setting is roughly how capable ; the effort setting is roughly how thorough. Most real tasks need some of both.
Effort, model, and token consumption
So how do model selection, effort, and token consumption all interact? It depends on the task.
On routine work at the same effort level, both models generally will get it right. The larger model consumes more tokens with extra verification steps at a higher per-token price. That's why dropping to the smaller model for routine stretches saves real money at no quality cost.
Curves are for illustration purposes only, shown for a single task simple enough to be accomplished quickly by both models. They do not represent real benchmark data.
On harder, multi-step work, the equation is different. The smaller model has to grind toward the limit of its ability, burning iterations, while the larger model reaches the same quality bar in fewer steps.
You're paying more per token for the larger model, but on tasks that genuinely stretch the smaller one, the total cost per task can come out lower. Also, more importantly, the larger model can accomplish tasks the smaller one cannot even at the highest effort settings.
This is most pronounced with Fable. On long, multi-step work it pulls furthest ahead. In our testing, it finished jobs Opus and Sonnet can't reach at any effort level. It also costs the most per token, which is the other reason to save it for the work that needs it.
Curves are for illustration purposes only, shown for a single task hard enough to stretch both models. They do not represent real benchmark data.
The key point in the graphs above is that effort level picks how far Claude is willing to travel along the curve, but again, that doesn’t mean Claude will need to travel that far to complete the task.
Another nuance to this: effort shapes token consumption but doesn't limit it. The only hard cap in the system is max_tokens, which truncates a response mid-stream when hit. It’s a blunt instrument, mostly relevant to API developers. Softer controls, like task budgets or asking Claude to keep it brief in your prompt, are more helpful tools. They serve as guidance the model is trained to follow-it will look to conclude its tasks if it gets near the limit–rather than a wall it runs into.
Start with the defaults, then reach for the dials
Most of the time, you shouldn't be thinking about either setting. When a result misses the mark, ask, “did Claude not know enough or did it not try hard enough?” and adjust as needed.
This article was written by Lydia Hallie, member of technical staff on the Claude Code team.