模型系统

模型系统分为两个目录。 下面的每条路径都在 src/.

系统可以引用的每个模型都在单个对象中声明 configs.ts。 每个条目都是一个 ModelConfig — 由提供者键入的记录 — 因此，无论 Bedrock 或 Vertex 如何命名，相同的逻辑模型都具有一个规范条目。

// utils/model/configs.ts
export type ModelConfig = Record<APIProvider, ModelName>

export const CLAUDE_OPUS_4_6_CONFIG = {
  firstParty: 'claude-opus-4-6',
  bedrock:     'us.anthropic.claude-opus-4-6-v1',
  vertex:      'claude-opus-4-6',
  foundry:     'claude-opus-4-6',
} as const satisfies ModelConfig

// @[MODEL LAUNCH]: Register the new config here.
export const ALL_MODEL_CONFIGS = {
  haiku35:  CLAUDE_3_5_HAIKU_CONFIG,
  haiku45:  CLAUDE_HAIKU_4_5_CONFIG,
  sonnet35: CLAUDE_3_5_V2_SONNET_CONFIG,
  sonnet37: CLAUDE_3_7_SONNET_CONFIG,
  sonnet40: CLAUDE_SONNET_4_CONFIG,
  sonnet45: CLAUDE_SONNET_4_5_CONFIG,
  sonnet46: CLAUDE_SONNET_4_6_CONFIG,
  opus40:   CLAUDE_OPUS_4_CONFIG,
  opus41:   CLAUDE_OPUS_4_1_CONFIG,
  opus45:   CLAUDE_OPUS_4_5_CONFIG,
  opus46:   CLAUDE_OPUS_4_6_CONFIG,
} as const satisfies Record<string, ModelConfig>

四大提供商

// utils/model/providers.ts
export function getAPIProvider(): APIProvider {
  return isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)
    ? 'bedrock'
    : isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)
      ? 'vertex'
      : isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)
        ? 'foundry'
        : 'firstParty'
}

async function getBedrockModelStrings(): Promise<ModelStrings> {
  const profiles = await getBedrockInferenceProfiles()
  const out = {} as ModelStrings
  for (const key of MODEL_KEYS) {
    const needle = ALL_MODEL_CONFIGS[key].firstParty
    out[key] = findFirstMatch(profiles, needle) || fallback[key]
  }
  return out
}

getMainLoopModel() in model.ts 是确定哪个模型运行对话的单一函数。 它按照严格的优先级顺序遍历五层：

1. 会话期间的 /model 命令 在引导状态下存储为 mainLoopModelOverride。 最高优先级 — 覆盖会话其余部分的所有内容。
2. --model CLI 启动时标志 还设置 mainLoopModelOverride 处于引导状态，但仅在会话开始之前。
3. ANTHROPIC_MODEL 环境变量 同步检查。 接受完整的模型 ID 和别名。
4. settings.json → 模型字段 设置者 /model 并在各个会话中持续存在。 唯一的层迁移接触。
5. 内置订阅默认 最大/团队高级 → Opus 4.6。 其他人 → Sonnet 4.6（3P 可能默认为 4.5）。

// utils/model/model.ts — simplified
export function getUserSpecifiedModelSetting(): ModelSetting | undefined {
  const modelOverride = getMainLoopModelOverride()          // layers 1+2
  if (modelOverride !== undefined) return modelOverride

  const settings = getSettings_DEPRECATED() || {}
  const specifiedModel =
    process.env.ANTHROPIC_MODEL || settings.model || undefined    // layers 3+4

  if (specifiedModel && !isModelAllowed(specifiedModel)) return undefined
  return specifiedModel
}

export function getRuntimeMainLoopModel(params: {
  permissionMode: PermissionMode
  mainLoopModel: string
  exceeds200kTokens?: boolean
}): ModelName {
  if (getUserSpecifiedModelSetting() === 'opusplan'
      && permissionMode === 'plan'
      && !exceeds200kTokens) {
    return getDefaultOpusModel()    // upgrade to Opus in plan mode
  }
  if (getUserSpecifiedModelSetting() === 'haiku' && permissionMode === 'plan') {
    return getDefaultSonnetModel()   // upgrade haiku to sonnet for plan
  }
  return mainLoopModel
}

用户永远不需要输入完整版本的模型 ID。 别名系统将短名称解析为当前提供者适当的模型字符串：

// utils/model/aliases.ts
export const MODEL_ALIASES = [
  'sonnet', 'opus', 'haiku', 'best',
  'sonnet[1m]', 'opus[1m]',
  'opusplan',
] as const

The [1m] 后缀很特殊：它被接受 any 别名或模型 ID，并发出 100 万个令牌上下文窗口变体的信号。 parseUserSpecifiedModel() 在解析基本模型之前将其剥离，然后重新附加它，以便 API 接收正确的模型字符串：

export function parseUserSpecifiedModel(modelInput: ModelName | ModelAlias): ModelName {
  const has1mTag  = has1mContext(normalizedModel)           // checks for [1m] suffix
  const baseModel = has1mTag
    ? normalizedModel.replace(/\[1m]$/i, '').trim()
    : normalizedModel

  if (isModelAlias(baseModel)) {
    switch (baseModel) {
      case 'opus':   return getDefaultOpusModel() + (has1mTag ? '[1m]' : '')
      case 'sonnet': return getDefaultSonnetModel() + (has1mTag ? '[1m]' : '')
      case 'haiku':  return getDefaultHaikuModel() + (has1mTag ? '[1m]' : '')
      // ...
    }
  }
  return modelInputTrimmed  // preserve original case for custom IDs
}

扩展上下文不是一个单独的模型； 它是现有模型上的运行时标志。 这 [1m] 后缀遍历整个管道，并且仅在 API 调用边界处被剥离 normalizeModelStringForAPI().

出入口

两个功能可访问 1M，Opus 和 Sonnet 各一个：

// utils/model/check1mAccess.ts
export function checkOpus1mAccess(): boolean {
  if (is1mContextDisabled()) return false    // CLAUDE_CODE_DISABLE_1M_CONTEXT env
  if (isClaudeAISubscriber()) return isExtraUsageEnabled()  // subscriber: extra-usage billing
  return true                                  // API/PAYG: always available
}

Opus 1M 合并

对于 Max 和 Team Premium 订阅者，只有一种 Opus 选项： opus[1m] ——他们总是能得到扩展的背景信息。 这种“合并”是由 isOpus1mMergeEnabled():

export function isOpus1mMergeEnabled(): boolean {
  if (is1mContextDisabled() || isProSubscriber() || getAPIProvider() !== 'firstParty')
    return false
  if (isClaudeAISubscriber() && getSubscriptionType() === null)
    return false  // fail closed: unknown sub type → no 1M (avoids API rate-limit error)
  return true
}

工作量是作为参数发送到 API 的思考预算提示。 它仅适用于支持它的型号 - 目前 claude-opus-4-6 and claude-sonnet-4-6.

决议顺序

// utils/effort.ts — resolveAppliedEffort()
// Priority: env > appState > model default
const envOverride = getEffortEnvOverride()  // CLAUDE_CODE_EFFORT_LEVEL env var
if (envOverride === null) return undefined    // null = explicit 'unset'
const resolved = envOverride ?? appStateEffortValue ?? getDefaultEffortForModel(model)
// API rejects 'max' on non-Opus-4.6 — auto-downgrade
if (resolved === 'max' && !modelSupportsMaxEffort(model)) return 'high'
return resolved

持久化规则

并非所有的努力值都可以保存到 settings.json。 这 toPersistableEffort() 函数强制执行这些约束：

• low, medium, high ——一直坚持
• max — 仅适用于 Anthropic 员工（USER_TYPE === 'ant'）； 会话范围内的其他人
• 数值（例如 42) — 从未持久化，仅模型默认

快速模式是一项研究预览功能，可为以下内容提供较低延迟的执行路径： 仅 Opus 4.6 在第一方 API 上。 它是通过切换的 /fast 或设置，并且该命令将被隐藏，除非快速模式可用于会话。

// commands/fast/index.ts
const fast = {
  type: 'local-jsx',
  name: 'fast',
  get description() { return `Toggle fast mode (${FAST_MODE_MODEL_DISPLAY} only)` },
  availability: ['claude-ai', 'console'],
  isEnabled: () => isFastModeEnabled(),
  get isHidden() { return !isFastModeEnabled() },
}

可用性检查

快速模式在提供给用户之前会经过分层可用性检查：

• CLAUDE_CODE_DISABLE_FAST_MODE=1 全局硬禁用它
• 仅适用于 firstParty 提供商 — 不在 Bedrock/Vertex/Foundry 上
• 需要付费订阅； 免费帐户请参阅“快速模式需要付费订阅”
• 订户需要启用额外使用计费； 如果没有它，原因是“快速模式需要额外的使用计费”
• 不适用于代理 SDK（非交互式会话），除非 fastMode: true 在标志设置中明确设置
• Statsig 功能标志 tengu_penguins_off 可以使用自定义原因字符串远程杀死它

模型切换开关

如果当前模型不支持快速模式，则启用快速模式仅切换模型。 如果您已经使用 Opus 4.6，则模型保持不变：

// commands/fast/fast.tsx — applyFastMode()
if (enable) {
  setAppState(prev => {
    const needsSwitch = !isFastModeSupportedByModel(prev.mainLoopModel)
    return {
      ...prev,
      ...(needsSwitch ? { mainLoopModel: getFastModeModel() } : {}),
      fastMode: true,
    }
  })
}

企业和团队管理员可以通过设置限制用户可以选择的模型 availableModels 在策略设置文件中。 匹配逻辑分为三层，按顺序应用：

1. 家庭通配符 — "opus" 允许任何 Opus 模型，除非该系列还存在更窄的条目
2. 版本前缀 — "opus-4-5" or "claude-opus-4-5" 匹配段边界处该版本的任何构建
3. 确切的ID — "claude-opus-4-5-20251101" 仅匹配该确切的字符串

// Example: restrict to Sonnet 4.6 and Haiku 4.5 only
// ~/.claude/settings.json (admin policy)
{
  "availableModels": ["sonnet", "haiku"]
}

// Example: allow only Opus 4.5 (not 4.6)
{
  "availableModels": ["opus-4-5"]
}

// Example: empty allowlist blocks ALL user-specified models
// (user gets the subscription default only)
{
  "availableModels": []
}

export function isModelAllowed(model: string): boolean {
  const { availableModels } = settings
  if (!availableModels) return true         // no restriction
  if (availableModels.length === 0) return false // empty blocks all

  // 1. Direct match — but skip family aliases that are narrowed
  if (allowlist.includes(model)) {
    if (!isModelFamilyAlias(model) || !familyHasSpecificEntries(model, allowlist))
      return true
  }

  // 2. Family wildcard (only if no specific entries for that family)
  for (const entry of allowlist) {
    if (isModelFamilyAlias(entry)
        && !familyHasSpecificEntries(entry, allowlist)
        && modelBelongsToFamily(model, entry)) return true
  }

  // 3. Version-prefix match at segment boundary
  for (const entry of allowlist) {
    if (!isModelFamilyAlias(entry) && !isModelAlias(entry)) {
      if (modelMatchesVersionPrefix(model, entry)) return true
    }
  }

  return false
}

当 Claude Code 生成子代理（通过任务工具或 SDK）时，子代理需要知道要使用哪个模型。 决议发生在 utils/model/agent.ts 并遵循以下优先顺序：

1. CLAUDE_CODE_SUBAGENT_MODEL 环境变量 所有子代理的全局覆盖。 在 CI 管道中很有用。
2. 工具指定的模型（任务调用上的模型参数） 编排模型可以请求子代理的特定模型。
3. 代理配置模型字段 在代理定义中设置。 接受任何别名或模型 ID。
4. “继承”（默认） 子代理使用与父线程相同的模型，包括 opusplan 解析。

别名匹配父层优化

当一个裸家庭别名（opus, sonnet, haiku) 匹配父模型的系列，子代理继承父模型的确切模型字符串，而不是将别名解析为提供程序默认值。 这可以防止固定 Opus 版本上的 Vertex 用户让子代理静默降级：

// utils/model/agent.ts
function aliasMatchesParentTier(alias: string, parentModel: string): boolean {
  const canonical = getCanonicalName(parentModel)
  switch (alias.toLowerCase()) {
    case 'opus':   return canonical.includes('opus')
    case 'sonnet': return canonical.includes('sonnet')
    case 'haiku':  return canonical.includes('haiku')
    default: return false
  }
}
// Note: opus[1m], best, opusplan fall through — they have extra semantics

基岩地区前缀继承

在 Bedrock 上，跨区域推理配置文件带有区域前缀 (eu., us.）。 如果父模型使用 eu.anthropic.claude-opus-4-6-v1，使用别名模型的子代理也必须使用 eu. 前缀。 这是由 applyParentRegionPrefix() — 如果子代理的模型规范已经带有自己的显式前缀，则跳过该步骤。

当 Claude Code 升级其默认模型时，之前固定特定模型的用户需要自动迁移其设置。 迁移系统在每次启动时运行一组功能； 每个迁移都是幂等的（可以安全地重新运行）。

实时模型验证

当用户在其中输入自定义模型 ID 时 /model，系统无法仅通过字符串匹配来知道它是否有效。 validateModel() 发送一个 真实的API调用 with max_tokens: 1 探测模型：

// utils/model/validateModel.ts
await sideQuery({
  model: normalizedModel,
  max_tokens: 1,
  maxRetries: 0,
  querySource: 'model_validation',
  messages: [{ role: 'user', content: [{ type: 'text', text: 'Hi' }] }],
})

A NotFoundError (404) 表示该模型不存在。 对于 3P 用户，将返回后备建议（例如，如果您要求 opus-4-6 在 Vertex 上，但它还不可用，它表明 opus-4-1).

弃用警告

弃用表在 deprecation.ts 将模型子字符串映射到每个提供商的退休日期：

const DEPRECATED_MODELS: Record<string, DeprecationEntry> = {
  'claude-3-7-sonnet': {
    modelName: 'Claude 3.7 Sonnet',
    retirementDates: {
      firstParty: 'February 19, 2026',
      bedrock:    'April 28, 2026',
      vertex:     'May 11, 2026',
      foundry:    'February 19, 2026',
    },
  },
  // ...
}

如果活动模型与任何条目匹配并且具有当前提供程序的停用日期，则 UI 会显示黄色警告横幅。 Bedrock 和 Vertex 的退休窗口通常比第一方更长。