# Adaptive Thinking 配置指南

**Adaptive Thinking（自适应思考）** 是 Claude 4.6/4.7/4.8 系列的新一代推理模式：模型自己决定何时投入推理、推理多少 tokens，无需开发者预先设定固定预算。配合 `effort` 参数可粗粒度控制思考深度。本文是与之相关的 API 用法、模型支持矩阵、效果与成本权衡指南。

> **关于 5 系**：日常默认推荐仍是 `claude-sonnet-5` / `claude-opus-5`（4.x 仍在售）。本文的参数矩阵按 Claude 4.6 / 4.7 / 4.8 **实测**整理。5 系的 `thinking` / `effort` 取值是否与下表完全相同，本轮未独立实测，**不要把下表的 4.x 专属结论**（例如 Opus 4.8 禁止 `budget_tokens`、`xhigh` / `max` 档位）直接套到 5 系上。5 系选型见 [模型选择](/docs/usage/model-selection)。

## 与旧 Extended Thinking 的关键差异

| 维度 | 旧 Extended Thinking（4.5 及以前）| Adaptive Thinking（4.6 / 4.7 / 4.8）|
|------|--------------------------------|------------------------------|
| 触发参数 | `thinking={"type": "enabled", "budget_tokens": N}` | `thinking={"type": "adaptive"}` |
| 预算控制 | 固定 token 上限（`budget_tokens` 必须 < `max_tokens`）| 模型自动调节，配合 `effort` 粗调 |
| 跨工具调用 | 默认不交错（需 `interleaved-thinking-2025-05-14` beta 头）| 自动交错（无需 beta 头）|
| Opus 4.8 兼容性 | ❌ **400 error**（`budget_tokens` 已移除）| ✅ 唯一支持模式 |
| Sonnet 4.6 兼容性 | ⚠️ deprecated（仍工作但不推荐）| ✅ 推荐 |

**简短规则**：4.6 / 4.7 / 4.8 系列模型都用 `adaptive`；4.5 及以前才用 `budget_tokens`。

## 支持模型矩阵

| 模型 | adaptive thinking | budget_tokens | effort 参数 |
|------|------------------|---------------|-------------|
| `claude-opus-4-8` | ✅ 唯一开启方式 | ❌ 400 error | ✅ low / medium / high / xhigh / max |
| `claude-sonnet-4-6` | ✅ 推荐 | ⚠️ 仍可用但 deprecated | ✅ low / medium / high |
| `claude-opus-4-7` | ✅ 推荐 | ⚠️ 仍可用但 deprecated | ✅ low / medium / high / max |
| `claude-haiku-4-5` | ✅ 支持 | ❌ 不支持 | ❌ effort 参数会 error |
| `claude-sonnet-4-5` 及以前 | ❌ 不支持 | ✅ 用这个 | ❌ |

> 通过 QCode.cc 中转访问时，所有上述模型均可用（已实测）。

## effort 参数：思考深度的粗调旋钮

`effort` 控制 adaptive thinking 的整体强度（包括思考 tokens、工具调用次数、回答详尽度）。

| effort | 适用场景 | 大致成本相对 |
|--------|---------|-------------|
| `low` | 简单问答、子 agent、对延迟敏感 | 1× |
| `medium` | 一般编码、文档查找（多数日常任务）| 1.5-2× |
| `high` | 复杂推理、跨多文件重构（**默认**） | 2-3× |
| `xhigh` | 长时程 agent 工作流（Opus 4.8 专属，Claude Code 默认）| 3-4× |
| `max` | 最高质量优先成本次要（仅 Opus 4.8 / 4.7）| 5× |

**经验法则**：`high` 是大多数交互编码任务的甜点；`xhigh` 在长 agent loop（如多步骤代码审查、深度调研）中性价比最高；`max` 仅在正确性远比成本重要时启用（如生产代码生成、关键架构决策）。

## API 调用示例

### Python（anthropic SDK）

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.qcode.cc/api",
    api_key="cr_xxxxxxxx",
)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "重构 user service 模块的认证逻辑..."}],
)

for block in response.content:
    if block.type == "thinking":
        print(f"[思考] {block.thinking}")
    elif block.type == "text":
        print(f"[回答] {block.text}")
```

### TypeScript（@anthropic-ai/sdk）

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.qcode.cc/api",
  apiKey: "cr_xxxxxxxx",
});

const response = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "xhigh" },
  messages: [{ role: "user", content: "重构 user service..." }],
});
```

### Claude Code CLI

CLI 里 effort 用快捷键 `Tab` 切换；当前 effort 显示在状态栏。Opus 4.8 默认 `xhigh`，可手动降到 `medium` 节省 tokens。

## 思考内容的渲染

Opus 4.8 默认**不显示思考文本**（`thinking.display: "omitted"`），只内部推理。如果想在 UI 里展示思考过程：

```python
thinking={"type": "adaptive", "display": "summarized"}
```

`display: "summarized"` 让模型输出思考摘要（可见的 thinking blocks）；`omitted` 只统计思考 tokens 不输出文本。Sonnet 4.6 / Haiku 4.5 默认就是 `summarized`。

## Task Budgets（Opus 4.8 Beta）

如果你跑 agent loop 想给整个回合（包括思考 + 工具 + 最终输出）一个全局上限，用 `task_budget`：

```python
response = client.beta.messages.create(
    betas=["task-budgets-2026-03-13"],
    model="claude-opus-4-8",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[...],
)
```

模型看到剩余预算的倒计时，会自我调节避免超支。最小 `total` 是 20,000。

## 成本观测建议

启用 adaptive thinking 后输入 / 输出 token 会上升，需要监控：

```python
print(response.usage)
# 关注：input_tokens、output_tokens、cache_read_input_tokens
# Adaptive thinking 不会单独计费 thinking tokens —— 它们计入 output_tokens
```

对于 QCode.cc 用户，请求会上报到 [probe.qcode.cc](https://probe.qcode.cc)——可以在那里看每次请求的 input / output / 思考占比。

## 常见问题

### budget_tokens 升级到 adaptive thinking 怎么换算？

没有线性换算关系。`budget_tokens=8000` 不等于某个 effort 级别。建议从 `effort: "medium"` 开始测，根据回答质量与 token 用量再调整。如必须有硬上限，可用 `task_budget`（见上）。

### 我的请求在 Opus 4.8 上 400 报错说 budget_tokens 不允许

把 `thinking={"type": "enabled", "budget_tokens": N}` 全部改成 `thinking={"type": "adaptive"}`，`budget_tokens` 字段在 Opus 4.8 已彻底移除（任何值都 400）。

### Sonnet 4.6 上要不要继续用 budget_tokens？

不建议。新代码一律用 adaptive thinking。`budget_tokens` 在 4.6 仍工作但属于 deprecated 路径，未来某个版本会移除。

### Claude Code CLI 怎么改 effort？

CLI 状态栏看到的 effort 用 `Tab` 切换；持久化默认值在 `~/.claude/settings.json` 里 `"effort"` 字段。

## 下一步

- [模型选择指南](/docs/usage/model-selection) — 各模型定价、能力对比
- [最佳实践](/docs/usage/best-practices) — 大上下文、agent 工作流的 prompt 技巧
- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — QCode.cc 接入域全表
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — CLI 全功能用法