AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

Claude Code

チュートリアル

Claude Code 中切换与配置 Claude Opus 5.5 的完整指南

在 Claude Code 里把模型切到 Claude Opus 5.5、并把 effort 档位调对，比想象中容易踩坑：用户设置顶层的 effortLevel 对 Opus 5.5 已经失效，只写这一行会让它一直停在默认的 medium。本文按切换模型、设置 effort、优先级判定、非交互模式、API 与 Bedrock 模型 ID、从 Opus 5 迁移这几条线，把可用的命令、参数与配置位置逐项列清楚。

Claude Code 支持在会话中或启动时切换底层模型，也支持为模型设置不同的思考投入档位（effort）。当目标模型是 Claude Opus 5.5 时，这两件事各有三条以上的设置路径，而且生效范围互不相同：有的只影响当前会话，有的会写回用户设置成为默认，有的则会被项目级配置覆盖。更麻烦的是，用户设置顶层的 effortLevel 对 Opus 5.5 已经不再生效，只写这一行会让模型一直按默认的 medium 运行，看起来像「设置没起作用」。这篇教程按实际操作顺序，把切换模型、设置 effort、判断优先级、非交互模式、API 与 Bedrock 的模型 ID、以及从 Opus 5 迁移时的破坏性变更逐项说明。如果你还没安装 Claude Code，可以先看 Claude Code 的工具页了解它是什么、适合哪些场景。

准备工作

开始之前需要确认几件事，它们决定了后面哪些命令可用。

  • Claude Code 已安装并可以正常启动。本文涉及的部分行为有最低版本要求：在 -p 非交互模式中使用 /model 需要 Claude Code v2.1.205 及以上；在滑块或模型选择器中按 s 把 effort 限定为「仅当前会话」需要 v2.1.257 及以上。版本号与功能可用性会变化，请以官网当前信息为准。
  • 账号具备使用 Opus 5.5 的权限。不同订阅或 API 方案可用的模型不同，具体以官网当前信息为准。
  • 清楚自己想让设置生效多久。这是本文的核心分岔点：只想试一次、想改当前会话、还是想永久改默认。三种目标对应完全不同的命令。
  • 知道配置文件分几层。Claude Code 的配置至少涉及用户设置、项目设置、本地设置、管理设置，以及通过 --settings 传入的设置。层级不同，优先级不同。

另外要提前记住一个结论：用户设置最顶层的 effortLevel 对 Opus 5.5 不生效，它是旧形式的键。如果你只在那里写了 effort，Opus 5.5 会当作「既没有显式指定、也没有已保存的设置」，从默认的 medium 起步。这个坑在后面的「注意事项」里还会展开。

操作步骤

第一步：把模型切换到 Claude Opus 5.5

切换模型有三条路径，按「生效范围」区分使用。

方式一：会话中切换。直接输入不带参数的斜杠命令：

/model

这会打开一个模型选择器，从中挑出 Opus 5.5 即可。也可以直接在命令后面跟上别名或模型名，当场切换：

/model <别名或模型名>

通过 /model 选定的模型会写入用户设置中的 model 字段，因此它不仅影响当前会话，也会成为之后新会话的默认值。

方式二：启动时指定。在启动 Claude Code 时把模型作为参数传入：

claude --model <别名或模型名>

也可以用环境变量 ANTHROPIC_MODEL 达到同样效果。这两种方式只对「用它们启动的那一个会话」生效，不会改动默认值。

方式三：写进配置文件。在配置文件的 model 字段里写死模型名，这样每次启动都会应用。但要注意优先级：项目设置与管理设置中的 model 会覆盖用户设置里的值。也就是说，即使你用 /model 选了 Opus 5.5，只要项目设置或管理设置里写了 model，下次启动时生效的仍然是那一层写的模型。

把三条路径的生效范围放在一起对比：

r>
方式生效范围补充说明
/model 后接名称，或在选择器中选取当前会话，以及之后新会话的默认值立即切换；选中的模型会写入用户设置的 model
在 /model 的选择器中按 s仅当前会话默认值不变
claude --model 或环境变量 ANTHROPIC_MODEL仅用该方式启动的会话默认值不变
配置文件中的 model长期生效项目设置与管理设置优先，下次启动时再次应用

如果只是想「试一次」，用选择器里按 s，或者用 --model 启动，是最稳妥的做法，不会污染默认配置。

第二步：设置 effort 档位

Opus 5.5 可选五档 effort：low、medium、high、xhigh、max。设置位置有四个。

会话中设置：/effort。在命令后跟上档位名称，该档位会被设置并保存为默认值：

/effort high

不带参数直接输入 /effort，会打开一个滑块。在滑块里选择，或在 /model 的选择器中按 s，该档位只对当前会话生效（需要 Claude Code v2.1.257 及以上）。

要清除当前模型已保存的档位，指定 auto：

/effort auto

启动时设置：--effort。把档位名传给该参数，只对这一次启动产生的单个会话生效：

claude --effort high

环境变量：CLAUDE_CODE_EFFORT_LEVEL。取值是档位名或 auto。它不写入保存的设置，但作为显式指定，优先级高于已保存的设置。除通过该环境变量设置的情况外，max 只对当前会话生效。示例：

CLAUDE_CODE_EFFORT_LEVEL=max claude

配置文件：modelSettings 与 effortLevel。modelSettings 用于按模型分别写档位；effortLevel 用于给「没有单独保存档位的模型」提供默认值。注意 modelSettings 中不能写 max。

四种方式的差异汇总如下：

方式是否保存指定 max 时补充说明
/effort 后接档位名保存为默认值仅当前会话生效—
滑块 / 选择器中按 s不保存（仅当前会话）—需要 Claude Code v2.1.257 及以上
--effort不保存（仅启动的那一个会话）仅当前会话生效—
CLAUDE_CODE_EFFORT_LEVEL不保存，但作为显式指定生效，优先于已保存的设置不限于当前会话取值为档位名或 auto
modelSettings / effortLevel作为已保存的设置生效不能写—

第三步：理解 effort 的判定顺序

effort 按优先级从高到低看三层，上层一旦确定，下层就不再参与：

  1. 显式指定：环境变量 CLAUDE_CODE_EFFORT_LEVEL、启动参数 --effort、会话中的 /effort。
  2. 已保存的设置：按模型保存的档位（modelSettings），或 effortLevel 键。
  3. 模型默认值：Opus 5.5 的默认是 medium。

换句话说，Opus 5.5 以默认的 medium 运行，只发生在「既没有显式指定，也没有对 Opus 5.5 生效的已保存设置」的时候。如果你遇到「明明设置了却还是 medium」，先确认写下的设置是否真的位于对 Opus 5.5 生效的位置。

第四步：确认 effortLevel 写在哪里才有效

这是最容易出错的一环。用户设置最顶层的 effortLevel 是旧形式的键，对 Opus 5.5 不生效。但 effortLevel 并非在所有位置都失效，写在下面这些位置时，它对包括 Opus 5.5 在内的所有模型都有效：

effortLevel 所在位置对 Opus 5.5 是否生效
用户设置的最顶层不生效（旧形式的键）
项目设置的最顶层生效
本地设置的最顶层生效
管理设置的最顶层生效
通过 --settings 传入的设置生效

如果希望在自己的环境里为 Opus 5.5 保存档位，可以从下面几种做法里选：

  • 在会话中执行 /effort high 这类带档位名的命令，它会设置并保存为默认值。
  • 把 effortLevel 写进项目设置、本地设置、管理设置，或通过 --settings 传入的设置。
  • 需要按模型区分档位时，在 modelSettings 中为各模型分别写档位（不能写 max）。
  • 想让设置优先于已保存的值，用环境变量 CLAUDE_CODE_EFFORT_LEVEL，它属于显式指定。

第五步：非交互模式（-p）下的行为

在 -p 非交互模式下，/model 与 /effort 都只对当前会话生效，不会保存为默认值。要在 -p 中使用 /model，需要 Claude Code v2.1.205 及以上。

启动参数 --model、环境变量 ANTHROPIC_MODEL、以及 --effort，则对用它们启动的那个会话生效，这一点与非交互模式无关。

第六步：通过 API 或 Amazon Bedrock 指定模型 ID

不走 Claude Code 而是直接调用接口时，模型 ID 的写法按平台区分：

使用位置模型 ID
Claude APIclaude-opus-5-5
Amazon Bedrockanthropic.claude-opus-5-5

请求体中的写法示例：

{
  "model": "claude-opus-5-5"
}

通过 API 使用 Opus 5.5 时有三点需要留意：

  • 自适应思考始终开启，无法关闭。思考深度通过 effort 调节。如果发送关闭思考的请求（thinking: {"type": "disabled"}），无论 effort 处于哪一档，都会返回 400 错误。
  • 使用高 effort 档位时，把 max_tokens 设得大一些。因为 max_tokens 是思考量与回复量合计的上限。
  • 模型 ID 要写对。Claude API 与 Amazon Bedrock 的写法不同，见上表。

一个完整示例

下面走一遍「临时试一次 Opus 5.5 + 高 effort，然后决定是否固化为默认」的完整流程。

第 1 步：临时启动一个会话，不改动任何默认配置。

claude --model opus-5-5 --effort high

这条命令启动的会话使用 Opus 5.5，effort 为 high。两个参数都只对这个会话生效，退出后不会留下痕迹。

第 2 步：在会话中确认当前模型与 effort。如果发现行为不符合预期，可以在会话里用不带参数的命令打开选择器查看：

/model
/effort

第 3 步：决定固化设置。如果确认 Opus 5.5 加 high 的组合合适，在会话中执行：

/model opus-5-5
/effort high

这两条会把模型写入用户设置的 model，把 effort 保存为默认值。

第 4 步：检查是否有更高优先级的配置覆盖了你的选择。查看项目设置与管理设置中是否写了 model。如果写了，下次启动时生效的会是那一层的模型，而不是你在 /model 里选的。同理，检查环境变量 CLAUDE_CODE_EFFORT_LEVEL 是否仍被设置着，以及启动脚本里是否还带着 --effort 或 --model——它们都是显式指定，会压过已保存的设置。

第 5 步：如果只想让某个项目使用特定档位，把 effortLevel 写进该项目的项目设置或本地设置，而不是用户设置的最顶层。

注意事项

从 Opus 5 迁移到 Opus 5.5 时的破坏性变更

只改模型 ID 是不够的。有些写法会直接报错，有些则不会报错但行为发生变化。迁移前请逐项检查 Opus 5 时代的代码：

  • 是否发送了关闭思考的设置：包含 thinking: {"type": "disabled"} 的请求在 Opus 5.5 上会返回 400 错误。
  • 是否强制使用工具：Opus 5.5 中强制使用工具会报错。
  • 是否使用了 computer_20251124 工具：Claude API 与 Google Cloud 不再接受这个旧工具。
  • 思考块的处理：思考块与模型、对话的绑定关系也属于破坏性变更之一。

还有一类不会报错、但行为改变的情况：

  • 默认 effort 降低。Opus 5 的默认是 high，而省略 effort 的请求在 Opus 5.5 上会以低一档的 medium 运行。不建议把 Opus 5 上用的档位直接照搬过来，应重新评估后再定档位。从 medium 起步是较为稳妥的做法。另外，在相同档位下，Opus 5.5 每个回合的思考量倾向于比 Opus 5 更多。
  • 工具调用之间的文本为空。在显示设置保持默认时，工具调用之间的文本会以「正文为空的思考块」形式返回。请求本身不会失败，但需要在工具调用之间展示中间过程的应用，应把显示设置改为返回文本的取值。

设置不生效时的排查顺序

按下面的顺序逐项检查，可以较快定位到冲突发生在哪一层：

  1. 用户设置：最顶层是不是只写了 effortLevel？如果是，改用 /effort high 这类带档位名的命令重新保存档位。
  2. 项目设置与管理设置：里面是否写了 model？写了的话，它会压过 /model 的选择，并在下次启动时再次生效。
  3. 环境变量与启动命令：CLAUDE_CODE_EFFORT_LEVEL 是否仍处于设置状态？启动命令或脚本里是否带着 --effort、--model？这两个都是显式指定，优先级高于已保存的设置。
  4. -p 的执行：是否误以为上一次运行中的 /model、/effort 会保留下来？在非交互模式下它们只对当次会话生效。
  5. API 请求：模型 ID 是否为 claude-opus-5-5（Bedrock 为 anthropic.claude-opus-5-5）？是否漏写了 effort？是否残留了关闭思考的设置、强制使用工具、或 computer_20251124？

最后提醒一句：模型可用范围、effort 档位、最低版本要求、以及 API 的计费与配额都属于会变动的信息，动手前请以官网当前信息为准。

戻る