# Claude Code 模型、Effort 与 Fast Mode

> Claude Code /model、/effort、opusplan、fallback model、Fast Mode、1M context、第三方 provider 模型能力和缓存影响。

URL: https://docs.passion8.cc/docs/claude-code/model-fast-mode
Language: zh-CN
Publisher: Passion8

模型配置决定 Claude Code 的能力、速度、成本和缓存命中。接入 Passion8 时,还要确认后台模型名、能力标记、context window、effort 和 fast mode 是否被网关正确支持。

Advisor 这种“主模型咨询强模型”的工作流,以及 Agent View、`/goal`、Ultraplan 和 Ultrareview 的选择边界,见 [高级工作流与云端协作](https://docs.passion8.cc/docs/claude-code/advanced-workflows-cloud)。

## 模型选择优先级

| 来源 | 生效方式 | 适合场景 |
| --- | --- | --- |
| `/model <alias\|id>` | 当前会话立即切换,新版本还会保存用户默认模型 | 交互中临时调整 |
| `claude --model <alias\|id>` | 仅本次启动生效 | 多个终端同时跑不同模型 |
| `ANTHROPIC_MODEL` | 当前环境启动的会话生效 | 临时 shell profile 或脚本 |
| `settings.json` 的 `model` | 持久默认 | 团队或个人默认 |
| Managed / server-managed settings | 管理员下发 | 企业统一限制 |

恢复旧 session 时,Claude Code 会优先使用 transcript 里保存的模型。只有模型退休、被 allowlist 排除,或本次启动明确指定了 `--model` / `ANTHROPIC_MODEL` 时,才会按新的优先级解析。




`/model` 是 cache key 变化。已有长历史时切模型,下一轮会重新读取整段 conversation。TTL 是 5 分钟还是 1 小时都不能跨模型复用。




## 常用别名

| 别名 | 含义 | 注意 |
| --- | --- | --- |
| `default` | 按账号、provider 或组织默认解析 | 不同计划和 provider 默认不同 |
| `opus` | Opus 系列默认候选 | 适合规划、架构、复杂 review |
| `sonnet` | Sonnet 系列默认候选 | 适合大多数编码执行 |
| `haiku` | Haiku 系列默认候选 | 适合低成本轻任务,部分能力可能不可用 |
| `fable` | Fable 系列默认候选（本次官方目录为 Fable 5.1） | 安全/生物相关内容可能自动 fallback |
| `opusplan` | plan mode 用 Opus,执行阶段用 Sonnet | 进出 plan 可能等同模型切换 |
| `opus[1m]` / `sonnet[1m]` | 请求 1M context 变体 | 是否可用取决于账号、模型和 provider |

如果 Passion8 后台使用自定义模型 ID,优先用后台实际展示的 ID。若想让 `/model` picker 显示网关模型,见 [网关与协议](https://docs.passion8.cc/docs/claude-code/gateway)。

## `opusplan`

`opusplan` 是官方的混合策略:

| 阶段 | 使用模型 | 适合 |
| --- | --- | --- |
| Plan mode | Opus | 需求拆解、架构、风险判断 |
| 执行模式 | Sonnet | 编辑代码、跑测试、常规实现 |

代价是缓存分裂。进入 plan mode 和退出 plan mode 时,如果实际模型从 Sonnet 切到 Opus 或反过来,下一轮会 miss。长任务里可以这样用:

1. 开局用 `opusplan` 做计划。
2. 计划确认后进入执行阶段,尽量不要频繁来回切 plan。
3. 如果只想临时问一个高阶判断,优先用 `/advisor` 而不是切整个会话模型。

## Effort

Effort 控制 adaptive reasoning 的深度。越高通常越慢、越贵,但复杂任务更稳。

| Effort | 典型用途 |
| --- | --- |
| `low` | 简短、确定、延迟敏感的小任务 |
| `medium` | 成本敏感但不太复杂的实现 |
| `high` | 默认平衡档,适合多数编码任务 |
| `xhigh` | 复杂架构、迁移、深度 debug |
| `max` | 当前 session 的深度档,不建议默认长期使用 |
| `ultracode` | Claude Code 设置,会用 xhigh 并更积极编排 dynamic workflows |

设置方式:

```bash
claude --effort high
```

```text
/effort xhigh
/effort auto
```

也可以在 `settings.json` 里设置:

```json title="settings.json"
{
  "effortLevel": "high"
}
```




Effort 也是 cache key。中途 `/effort` 后下一轮会重新读取完整历史。先定模型和 effort,再开始长任务。




## Fast Mode

Fast Mode 用于让 Opus 更快返回。官方把它描述成速度和成本的权衡,适合你愿意为低延迟付出更高请求成本的场景。

```text
/fast
```

使用判断:

| 场景 | 建议 |
| --- | --- |
| 一开始就知道要快 | 开局先 `/fast`,再开始长任务 |
| 已经跑了很久的长会话 | 谨慎开启,第一轮会重新读全历史 |
| 当前不是 Opus | 开启可能隐式切到 Opus,等同模型切换 |
| 命中 rate limit | 官方会 fallback 到标准速度,新版本后不一定破坏同一会话缓存 |

Fast Mode 与 effort 不等价。Fast Mode 是速度/计费模式;effort 是 reasoning 深度。你可以用较低 effort 快速处理普通任务,也可以用 Fast Mode 加速复杂 Opus 会话。

## Advisor Tool

Advisor 是“主模型继续工作,关键时刻请第二个模型给建议”。它适合不想切整个会话模型,但希望复杂决策有更强模型把关的场景。

```text
/advisor opus
/advisor off
```

也可以启动时指定:

```bash
claude --advisor opus
```

缓存影响:

| 项目 | 影响 |
| --- | --- |
| 开关 `/advisor` | 官方说明通常不破坏主会话 prompt cache |
| advisor 自己的调用 | 每次 advisor 读取完整 transcript,不复用 advisor 调用之间的缓存 |
| advisor 回复 | 作为会话内容进入后续历史,之后可被主会话缓存 |




Advisor 是 Anthropic API 上的 server-executed tool。Bedrock、Vertex、Foundry 或第三方网关是否可用,取决于 provider/网关是否完整转发相关请求。




## Fallback Model

模型过载或不可用时,可以配置 fallback chain:

```bash
claude --fallback-model sonnet,haiku
```

或写入 settings:

```json title="settings.json"
{
  "fallbackModel": ["sonnet", "haiku"]
}
```

触发 fallback 的那一轮会使用另一个模型,因此也是 cache key 变化。它适合提高可用性,不是节省缓存成本的工具。

## 1M Context

官方模型配置支持 `opus[1m]`、`sonnet[1m]` 或在完整模型名后追加 `[1m]` 来请求 1M context。是否可用取决于模型、账号、provider 和网关能力。

在 Passion8 下使用时要检查:

| 检查项 | 原因 |
| --- | --- |
| 后台是否真的提供 1M context 模型 | 仅改别名不等于 upstream 支持 |
| 网关是否转发 context/extended context beta 字段 | 被剥离后能力可能静默不可用 |
| 自动 compact 阈值是否适配 | 网关如果限制更小 context,需要调整 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` |

## 第三方 Provider 能力声明

Claude Code 会根据模型 ID 判断 effort、thinking、tool search、1M context 等能力。自定义部署名可能不匹配。Provider 专用配置可以用 `_SUPPORTED_CAPABILITIES` 告诉 Claude Code 这个模型支持什么。

示例:

```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="my-opus-deployment"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES="effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking"
```

注意:官方说明这些 capability 变量用于 Bedrock、Vertex、Foundry、Mantle 等 provider 配置。对普通 `ANTHROPIC_BASE_URL` 网关不一定生效,网关侧更重要的是完整转发 headers 和 body fields。

## Passion8 建议

| 需求 | 建议 |
| --- | --- |
| 稳定编码 | 先用 Passion8 后台可用的 Sonnet/Opus 模型,不要中途频繁切 |
| 深度规划 | 用 `opusplan` 或 `/advisor opus`,二选一先试 |
| 长上下文 | 先确认 Passion8 模型窗口和缓存字段,再考虑 `[1m]` |
| 成本控制 | 默认 `high` 或 `medium`,自然断点 `/compact` |
| 速度 | 开局决定 `/fast`,不要长会话中途才开 |
| 网关模型 picker | 需要 `/v1/models` 和 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` |

## 官方参考

- [Model configuration](https://code.claude.com/docs/en/model-config.md)
- [Fast mode](https://code.claude.com/docs/en/fast-mode.md)
- [Advisor tool](https://code.claude.com/docs/en/advisor.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Gateway protocol reference](https://code.claude.com/docs/en/llm-gateway-protocol.md)