# 上下文管理

Claude Code 的每次会话都运行在一个**上下文窗口**中。理解上下文的工作方式，能帮助你更高效地使用 Claude，避免因上下文溢出导致的错误。

## 理解上下文窗口

Claude Code 默认使用 **20 万 token** 的上下文窗口。Opus 4.8 和 Sonnet 4.6 模型支持扩展至 **100 万 token（1M context）**。

上下文包含：
- 所有对话历史（你的提问 + Claude 的回答）
- 通过 `@` 引用的文件内容
- 工具调用的输入和输出
- 系统提示和 CLAUDE.md 内容

随着对话进行，上下文会不断增长。当上下文接近上限时，Claude 的响应速度可能变慢，并最终触发自动压缩或出现错误。

## 压缩上下文：/compact

`/compact` 命令将当前对话历史压缩为简短摘要，释放上下文空间，同时保留重要信息。

```
/compact
```

你也可以添加自定义指令，控制压缩重点：

```
/compact 保留所有代码示例和已完成的任务清单
```

**自动压缩机制**：Claude Code 默认在上下文达到 **95% 容量**时自动触发压缩。你也可以在上下文达到 70-80% 时主动运行 `/compact`，避免等到最后一刻。

## 清除历史：/clear

`/clear` 命令清除所有对话历史，开始全新会话：

```
/clear
```

> **注意**：`/clear` 会删除所有上下文，包括 Claude 已了解的项目信息。适合切换到完全不相关的新任务时使用。

## 查看上下文状态：/context

使用 `/context` 命令查看当前上下文的使用情况：

```
/context
```

## @ 引用文件

使用 `@` 符号将文件内容添加到上下文：

```
@src/main.ts 解释这个文件的功能
@package.json 检查依赖版本
@README.md
```

**最佳实践**：
- 只引用当前任务相关的文件，避免引入不必要的上下文
- 大文件会快速消耗上下文空间，优先引用关键文件
- 使用 `CLAUDE.md` 提供项目背景，而不是在每次对话中重复粘贴

## 管道输入

通过管道将命令输出或文件内容传入 Claude：

```bash
# 将文件内容传入
cat error.log | claude "分析这个错误"

# 将命令输出传入
git diff | claude "生成提交信息"

# 多行输入
echo "请分析以下代码：
$(cat src/utils.ts)" | claude
```

## 长会话溢出预防

### 症状：E015 Internal server error

当对话上下文接近模型容量上限（~95%）时，Anthropic API 会返回 500 错误。QCode.cc 将其包装为 429 响应：

```
429 {"error":{"code":"E015","message":"Internal server error"},"status":500}
```

这是 Anthropic API 的已知行为（非 QCode.cc 特有问题）。QCode.cc 将上游 5xx 错误包装为 429 响应，是为了利用 Claude Code 内置的重试机制。

### 解决步骤

1. **尝试 `/compact`**：
   - 如果成功，对话可以继续正常进行
   - 如果 `/compact` 本身也报错（压缩请求也需要发送完整上下文），执行下一步

2. **退出并重启 Claude Code**：
   ```bash
   # 按 Ctrl+C 或输入 /exit
   # 然后重新启动
   claude
   ```

### 预防建议

- **定期压缩**：在上下文达到 70-80% 时主动运行 `/compact`，而不是等到溢出
- **任务分解**：将大任务拆分为多个小任务，每个任务使用独立会话
- **用 CLAUDE.md 替代重复粘贴**：将项目背景写入 `CLAUDE.md`，Claude 启动时会自动读取，无需在每次对话中重复提供
- **避免引入大文件**：每引用一个大文件会消耗大量上下文，优先引用关键部分
- **使用 `/cost` 监控**：`/cost` 命令可以查看当前会话的 token 消耗情况

## 相关命令速查

| 命令 | 作用 |
|------|------|
| `/compact` | 压缩上下文（保留摘要） |
| `/clear` | 清除所有上下文 |
| `/context` | 查看上下文状态 |
| `/cost` | 查看 token 消耗 |
| `@文件路径` | 引用文件到上下文 |
## 上下文工程层级

「上下文工程」指的是有意识地组织 Claude 在每次请求中读到的内容——让高价值、稳定的信息排在前面，把噪声挡在外面。Claude Code 的上下文遵循一个明确的**优先级层级**（从高到低）：

1. **企业 / 托管策略**——由组织统一下发的规则，优先级最高，个人无法覆盖。
2. **项目记忆 `CLAUDE.md` / `AGENTS.md`**——仓库根目录的项目级指令，描述代码规范、构建命令、项目背景。
3. **路径作用域规则**——子目录中的嵌套 `CLAUDE.md` 或 `.claude/rules`，只对该路径下的工作生效。
4. **实时对话历史**——当前会话里你和 Claude 的往来内容，优先级最低，也最容易膨胀。

理解这个层级，能帮你把指令放在**正确的位置**：通用规范写进项目级 `CLAUDE.md`，目录专属约定写进路径作用域规则，而不要在每次对话里反复口述。

### 实用要点

- **指令要简洁、高信号**：`CLAUDE.md` 越精炼，Claude 越容易遵循；冗长、跑题的内容反而会稀释关键指令。
- **在逻辑断点处 `/compact`**：完成一个阶段后压缩历史，过长且发散的对话会降低准确率。
- **不相关任务之间 `/clear`**：切换到完全无关的新任务时清空历史，避免旧上下文干扰。
- **用路径引用代替整段粘贴**：通过 `@文件路径` 让 Claude 按需读取文件，而不是把大段内容塞进对话——既省上下文，也更准确。
- **把稳定内容放在最前面**：系统提示、`CLAUDE.md`、大块背景等不变内容应排在前部且不频繁改动，这样它们可以被**提示缓存**命中（缓存读取成本约为正常输入的 10%）。这也是「简洁稳定的 `CLAUDE.md` + 复用会话」能省钱的根本原因。

简单说：把稳定、高价值的内容沉到层级上方并保持不变，把易变的对话历史定期收口。需要进一步了解，请参阅 [CLAUDE.md 项目记忆](/docs/usage/claude-md) 与 [成本优化](/docs/usage/cost-optimization)。