# 修复 OpenClaw context_length_exceeded：上下文、工具输出与 Failover 诊断

> 在 OpenClaw 中遇到 context_length_exceeded，先证明请求是否真的超过所选模型路由的可用上下文，还是速率限制、fallback、cooldown 或更小模型路由把配额问题显示成上下文错误。然后再 compact、拆任务、减少工具输出、裁剪工作区注入或切换模型路由。

- URL: https://blog.laozhang.ai/zh/posts/openclaw-context-length-exceeded
- Published: 2026-02-08
- Updated: 2026-05-08
- Author: AI Free API Team (https://blog.laozhang.ai/zh/about)
- Category: OpenClaw 故障排除
- Tags: OpenClaw, 上下文长度超限, Token 限制, 上下文窗口, AI 故障排除

---
OpenClaw 的 `context_length_exceeded` 通常表示组装后的模型请求超过了所选路由能接受的可用上下文。这个请求不只包含你的最后一句话，还可能包含系统指令、工具 Schema、工作区规则、检索到的记忆、频道元数据、对话历史和近期工具输出。但可见错误不一定就是根因：速率限制、provider cooldown、fallback 到更小上下文的模型，或者代理重试循环，都可能让配额或路由问题看起来像上下文溢出。先判断责任归属，再决定是压缩、拆任务还是换路由。

## 快速答案

- **先证明症状**：看 `/status`、`/context list`（如果当前版本支持）和 `openclaw logs --follow`。如果错误刚出现在 429、cooldown 或 fallback 后，先查 provider 日志。
- **真实上下文过大**：用 `/compact` 保留关键决策并压缩旧历史；任务已经换方向时，用 `/new` 开干净会话。
- **工具输出过大**：不要把完整日志、整仓搜索和大文件一次性塞进模型；改用关键片段、文件范围和摘要。
- **工作区注入过大**：精简 AGENTS/规则文件，减少过期指令和一次性分析，让 Agent 按需读取文件。
- **模型路由不匹配**：不要只看旧文章里的“窗口大小”。检查你当前账号、provider、gateway、fallback 实际暴露的上下文。

## 先确认谁拥有这个错误

`context_length_exceeded` 至少有四个常见 owner。

| 现象 | 更可能的 owner | 下一步 |
|---|---|---|
| `/status` 显示上下文持续升高，错误随长会话出现 | 真实上下文溢出 | `/compact`、`/new`、拆任务、减少工具输出 |
| 新会话或低使用率下突然出现 | bootstrap、memory/search、频道元数据或错误路由 | 查 `/context list` 和 logs，减少注入源 |
| 错误紧跟 429、cooldown、provider failover | 速率限制或 fallback 路由 | 先读第一条 provider 日志，不要急着调上下文 |
| 只在某个 provider/gateway 出现 | 模型路由或 proxy 窗口不同 | 用当前 provider 文档和实际响应确认可用窗口 |

正确顺序很重要。真实上下文溢出需要压缩；fallback 到小模型需要改路由；provider quota 需要等待、降并发或切换已验证 route；工作区注入过大需要改输入结构。把这些都当成一个问题，会让排查越来越慢。

## OpenClaw 为什么会用掉大量上下文

OpenClaw 是 agentic 工作流。一次看起来很短的用户请求，可能触发读文件、搜索、命令执行、测试、工具输出回填和多轮模型调用。后续请求往往会带上前面的历史和工具结果，所以消耗增长取决于“本轮实际装进请求的内容”，不取决于你工作了几分钟。

固定开销通常来自系统和工具说明。你不应该随便删它们，因为它们决定 Agent 如何使用工具、遵守项目规则和处理文件。真正应该控制的是变量开销：大段日志、宽泛搜索、无关文件、过期工作区规则、重复失败输出和跨任务延续的旧历史。

工作区注入是最容易被忽视的一项。AGENTS.md、项目规则、生成文档和长期记忆都很有价值，但如果它们变成过长、过期、互相冲突的说明，就会在每次请求里挤占上下文。好的做法不是删除规则，而是把长期规则写短，把一次性分析放到文件里，并让 Agent 按需读取精确范围。

## 恢复工作：从低风险动作开始

**1. 读状态和第一条日志。** 先运行：

```bash
/status
/context list
openclaw logs --follow
```

如果你的版本没有 `/context list`，就用 logs 和最近操作回溯：刚刚是否读了大文件、跑了长测试、开启了多个 agent、从旧任务直接切到新任务，或者刚经历了 provider 429/fallback。

**2. 真实会话过大时用 `/compact`。** `/compact` 适合保留关键决策、文件位置和当前任务状态，同时压缩早期冗余细节。压缩效果取决于会话内容和当前版本，不要假设固定百分比。压缩后再看 `/status`，确认是否给下一轮工具调用和模型回复留出了空间。

**3. 任务已经换方向时用 `/new`。** 如果旧会话已经混入无关日志、失败尝试和另一个任务的决策，继续压缩不一定是最佳选择。用 `/new` 开新会话，并带上简短交接：目标、已改文件、未解决风险、需要保留的命令和测试结果。

**4. 减少工具输出。** 把“把所有日志都发给模型”改成“只截取第一条错误、栈顶、相关配置和复现命令”。把“读整个仓库”改成“读这三个文件的相关段落”。工具输出越干净，后续每次请求越轻。

**5. 不要把配额问题误修成上下文问题。** 如果错误出现在 429、cooldown 或 fallback 后，先处理 provider owner：尊重 `retry-after`、降低并发、缩短上下文、切换已验证 fallback，或等待 quota 窗口恢复。

## 调整配置时的安全边界

OpenClaw 的上下文相关配置会随版本变化。你可以参考旧文章理解原则，但不要复制旧默认值当合同。实际修改前，先用当前文档、`openclaw config` 输出或现有配置文件确认键名和默认行为。

常见方向包括：

| 调整方向 | 适合场景 | 风险 |
|---|---|---|
| 更早 compact | 长会话经常接近上限 | 保留的逐字历史变少，需要摘要质量稳定 |
| 降低 bootstrap/workspace 注入 | AGENTS 或项目规则过大 | Agent 可能需要更多按需读取 |
| 限制 memory/search 检索 | 新会话一开始就很重 | 跨会话连续性变弱 |
| 换更大可用上下文的 route | 大仓库、多文件审查、长文档 | 价格、延迟、tool support 和 fallback 行为要重新验证 |

一个保守的配置片段可以作为形状参考，但字段和数值必须按你的版本确认：

```json
{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokens": 40000,
        "keepRecentTokens": 25000
      },
      "bootstrapMaxChars": 12000,
      "memorySearch": {
        "softThresholdTokens": 3000
      }
    }
  }
}
```

这里的重点不是这些数字本身，而是三个原则：压缩要早于硬失败，工作区注入要短且当前，检索结果要和任务相关。

## 选择模型路由时不要只看宣传窗口

模型的标称上下文窗口不等于 OpenClaw 实际可用上下文。你还要确认：

- 当前账号是否能使用这个模型。
- 你走的是 direct provider、cloud route、gateway 还是 proxy。
- fallback 是否会切到更小窗口模型。
- 工具调用、图像/文件输入、流式响应和 structured output 是否仍然可用。
- gateway 是否保留了上游同样的上下文窗口和错误信息。

如果你需要多 provider 路由，[laozhang.ai](https://docs.laozhang.ai/) 这类 OpenAI-compatible gateway 可以简化凭据和 fallback 配置，但模型覆盖、价格、上下文窗口、quota 行为和工具兼容性都必须在当前环境验证后再用于生产。

## 长期预防

**保持工作区规则短而稳定。** AGENTS.md 和类似文件应该承载长期规则，不应该堆放一次性日志、历史争论和过期计划。

**长任务分阶段。** 完成一个阶段就压缩或新开会话，并写清楚交接状态。不要把调研、实现、测试、复盘和另一个项目连续塞进同一条长线程。

**让工具输出可读。** 测试失败时先截取最小复现、关键错误和相关文件。宽泛输出不仅浪费上下文，也让 Agent 更难判断真正问题。

**监控 context 和成本。** 上下文 token 也是 API 成本的一部分。减少无关历史和工具噪声，通常同时减少失败率、等待时间和账单。

## FAQ

**OpenClaw 中的 context_length_exceeded 是由什么引起的？**

它发生在组装后的请求超过所选模型路由的可用上下文时。请求可能包含系统指令、工具 Schema、工作区文件、对话历史、memory/search 结果、频道元数据和工具输出。也可能是 fallback、quota 或 gateway 行为让问题显示成上下文错误。

**如何增加 OpenClaw 的上下文窗口？**

你不能增加模型本身的窗口，但可以换到更大可用上下文的已验证 route，减少工作区注入，降低检索噪声，更早 compact，拆分任务，并避免把巨大日志或整仓输出放进同一会话。

**`/compact` 会丢数据吗？**

它会把旧历史压缩成摘要，保留关键决策和近期上下文，但逐字细节可能不再进入后续请求。重要命令、错误、文件路径和结论最好写入本地文档或交接说明。

**为什么新会话也会出现 context_length_exceeded？**

通常是 bootstrap 文件、memory/search 检索、频道元数据或 fallback 路由过小。先查 `/status`、`/context list` 和第一条 provider 日志，再裁剪注入源或调整路由。