read_when:

- 想降低 OpenClaw 的 token 消耗

- 群聊太费钱

- 长会话上下文越来越大

summary: OpenClaw 省 token 实战指南——经过官方文档 + 源码逐项验证的配置建议

OpenClaw 省 Token 配置指南

🎯 一句话版本

关于Openclaw Token Saving Guide的深度研究报告

Token 开销的三大来源：调用次数多、每次带的上下文长、自动预处理多（看链接、看图、看视频等）。

省 token 的思路也就三条：少调用、少带历史、少开自动功能。

一、让旧上下文及时过期

这是最有效的单一手段。

`session.reset`

OpenClaw 默认每天凌晨 4 点重置会话。如果你想按空闲时间切：

{
  session: {
    reset: {
      mode: "idle",
      idleMinutes: 60,
    },
  },
}

会话 60 分钟没新消息 → 下一条消息自动开新 session → 不再拖着 2 小时的历史。

可以按聊天类型分开配：

{
  session: {
    reset: {
      mode: "idle",
      idleMinutes: 60,
    },
    resetByType: {
      group: { mode: "idle", idleMinutes: 20 },
      thread: { mode: "idle", idleMinutes: 30 },
    },
  },
}

经验法则：觉得"忘上下文太快"就调大，觉得"越聊越贵"就调小。

> 📖 参考：Session Management · Session Deep Dive

二、群聊：控触发 + 控历史

群聊通常是最烧钱的场景——无关消息多、触发频繁、历史长。

`messages.groupChat.historyLimit`

{
  messages: {
    groupChat: {
      historyLimit: 6,
    },
  },
}

每次处理群消息时，最多回看最近 6 条。各渠道也可以单独覆盖，如 channels.telegram.historyLimit、channels.discord.historyLimit。

推荐值：答疑 bot 4~6，深度参与讨论 10~15。

群里用 `mention` 而不是 `always`

/activation mention

只有被 @mention 时才认真处理，避免每条群消息都走模型。

> 📖 参考：Messages · Configuration Reference

三、减少连发消息的重复调用

用户习惯连发几条消息，每条单独调用模型很浪费。OpenClaw 有两个独立机制：

机制 1：入站去抖 `messages.inbound`

在 agent run 开始之前，把短时间内连续来的消息合并成一条：

{
  messages: {
    inbound: {
      debounceMs: 2000, // 等 2 秒看用户是否继续发
      byChannel: {
        whatsapp: 5000,  // WhatsApp 用户特别爱连发
        discord: 1500,
        slack: 1500,
      },
    },
  },
}

注意：媒体/附件会立即投递（不等去抖），命令也会绕过去抖。

机制 2：运行中排队 `messages.queue`

agent 正在处理时新消息进来怎么办？用 /queue 配置：

/queue collect debounce:2s cap:8 drop:summarize

• collect：收集起来等当前 run 结束后一起处理
• debounce:2s：run 结束后再等 2 秒收集后续消息
• cap:8：最多排 8 条
• drop:summarize：超出上限的消息做摘要而非丢弃

这两个机制是独立的：messages.inbound 管"还没开始跑"，messages.queue 管"正在跑的时候来了新消息"。

> 📖 参考：Messages · Queueing

四、限制子会话继承的历史

`session.parentForkMaxTokens`

{
  session: {
    parentForkMaxTokens: 20000,
  },
}

当 thread/topic 想继承父会话上下文时，如果父会话已经超过这个 token 数，就不 fork 过去，从干净上下文开始。

默认值是 100000。如果你想省钱，调到 15000~25000。设 0 关闭保护。

> 📖 参考：Session Deep Dive

五、Compaction 调优

长会话靠 compaction 续命——把历史压缩成摘要。但 compaction 本身也花 token。

核心参数

{
  agents: {
    defaults: {
      compaction: {
        enabled: true,
        reserveTokens: 16384,  // 预留给下一轮回复的空间
        keepRecentTokens: 8000, // 最近这么多 token 保留原文不压缩
      },
    },
  },
}

• reserveTokens：默认 16384。OpenClaw 还有安全下限（默认 20000），低于下限会自动提升
• keepRecentTokens：默认 20000。调小更省，但最近对话细节会丢

用便宜模型做 compaction

{
  agents: {
    defaults: {
      compaction: {
        model: "openai/gpt-4.1-mini",
      },
    },
  },
}

正常对话用主模型，compaction 交给便宜模型。主模型越贵，这招越值。

Memory flush 开关

compaction 前默认跑一次 memory flush（把重要内容写到磁盘）。这会多一次 agent turn。

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: false, // 关掉更省，但会丢长期记忆
        },
      },
    },
  },
}

取舍：如果 bot 很依赖长期记忆（记偏好、维护项目状态），别关。纯问答 bot 可以关。

> 📖 参考：Compaction · Session Deep Dive

六、关闭自动媒体理解

这些功能会在你不知情的情况下消耗 token：

图片理解 `tools.media.image`

{
  tools: {
    media: {
      image: {
        enabled: false, // 纯文本 bot 直接关
      },
    },
  },
}

如果必须开，限制描述长度：

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxChars: 800,
      },
    },
  },
}

视频理解 `tools.media.video`

通常比图片更贵。非核心能力就关：

{
  tools: {
    media: {
      video: {
        enabled: false,
      },
    },
  },
}

网页抓取 `tools.web.fetch`

用户贴链接自动读网页的功能：

{
  tools: {
    web: {
      fetch: {
        maxChars: 20000, // 默认 50000，调低
      },
    },
  },
}

> 📖 参考：Media Understanding · Configuration Reference

七、Heartbeat 省 token（源码验证）

心跳是隐性 token 大户——默认每 30 分钟跑一次，每次带完整对话历史 + 所有 bootstrap 文件（SOUL.md、USER.md、MEMORY.md、AGENTS.md 等）。如果 MEMORY.md 有 3 万字，光心跳一天就烧掉几十万 token。

空文件自动跳过 LLM 调用

OpenClaw 内置了 isHeartbeatContentEffectivelyEmpty() 检测（源码：src/auto-reply/heartbeat.ts）。当 HEARTBEAT.md 存在但只包含标题、空行、空 checkbox 时，心跳直接返回 skipReason: "empty-heartbeat-file"，完全不调用 LLM。

# HEARTBEAT.md
<!-- 只有标题 → 零 LLM 调用 -->

> ⚠️ 注意：HEARTBEAT.md 不存在时仍会调用 LLM（设计如此，prompt 说 "if it exists"）。想彻底跳过就创建一个只有标题的文件。

`isolatedSession` + `lightContext`

这是最猛的组合拳（源码：src/infra/heartbeat-runner.ts + src/agents/bootstrap-files.ts）：

{
  agents: {
    defaults: {
      heartbeat: {
        isolatedSession: true,  // 每次心跳用全新空 session，不带对话历史
        lightContext: true,      // bootstrap 文件只保留 HEARTBEAT.md
      },
    },
  },
}

源码逻辑：lightContext 在 heartbeat 模式下过滤 bootstrap 文件，只保留 HEARTBEAT.md：

// src/agents/bootstrap-files.ts
if (contextMode !== "lightweight") {
  return params.files;  // full mode: 加载所有文件
}
if (runKind === "heartbeat") {
  return params.files.filter((file) => file.name === "HEARTBEAT.md");  // 只留这一个
}

心跳用便宜模型

{
  agents: {
    defaults: {
      heartbeat: {
        model: "openai/gpt-4.1-mini",  // 心跳不需要强模型
      },
    },
  },
}

心跳大部分时候只是检查 HEARTBEAT.md 有没有待办事项，用 mini 模型足够。

Cron 任务也支持 `lightContext`

/cron add ... lightContext:true

源码 src/agents/tools/cron-tool.ts 和 src/cron/isolated-agent/run.ts 都支持。定时任务如果不需要读完整 workspace 文件，加上这个参数同样省大量 token。

心跳省 token 推荐配置

{
  agents: {
    defaults: {
      heartbeat: {
        isolatedSession: true,
        lightContext: true,
        model: "openai/gpt-4.1-mini",
      },
    },
  },
}

KV Cache 与心跳的矛盾

LLM 提供商通过 KV Cache（Prompt Cache）让重复前缀的请求更便宜。各家保留时间：

核心矛盾：心跳默认 30 分钟间隔 > Anthropic 5 分钟 TTL → 每次必 miss。

就算把心跳改成 5 分钟一次来命中缓存：省了 90% input 费用，但调用次数多了 6 倍 → 反而更贵。

缓存真正有用的场景是连续对话——用户快速来回聊天，前缀不变，间隔 < 5 分钟。

心跳成本实测计算（以 Claude Opus 4.6 为例）

以下基于一个真实配置的估算：MEMORY.md ~3.5 万字、bootstrap 文件 ~20K tokens、系统 prompt ~25K tokens、每天 ~30 次有效心跳。

各组件 Token 估算：

四种方案月费对比：

> 💡 计算依据：Opus input $15/M、output $75/M；GPT-4.1-mini input $0.40/M、output $1.60/M；心跳 output 固定 ~500 tokens（HEARTBEAT_OK）；每天 30 次有效心跳（扣除静默时段和跳过）。

方案 C 性价比最高：$10/月保留心跳能力，比默认配置省 99%。配置见上方推荐。

关键结论：心跳场景下，减少发送的 token 数量远比期望命中 KV Cache 折扣有效。缓存折扣最多省 90%（且心跳间隔下大概率 miss），而 isolatedSession + lightContext + 便宜模型组合可以省 99%。

八、运行时开关

`/think off`

支持 thinking 的模型（如 Claude）默认会花很多 token 在推理上。日常聊天关掉：

/think off

只有复杂任务才开 /think high。

`/verbose off`

减少工具结果在回复里的展开，让 transcript 膨胀更慢。

`/usage off`

关掉每条回复后面的 usage footer，减少消息噪音。

> 📖 参考：Thinking · Slash Commands

九、三套推荐配置

极致省钱版

纯文本聊天，不需要自动看图/视频/链接：

{
  session: {
    reset: { mode: "idle", idleMinutes: 60 },
    resetByType: {
      group: { mode: "idle", idleMinutes: 20 },
      thread: { mode: "idle", idleMinutes: 30 },
    },
    parentForkMaxTokens: 15000,
  },
  messages: {
    inbound: { debounceMs: 2000 },
    groupChat: { historyLimit: 6 },
  },
  agents: {
    defaults: {
      heartbeat: {
        isolatedSession: true,
        lightContext: true,
        model: "openai/gpt-4.1-mini",
      },
      compaction: {
        keepRecentTokens: 6000,
        model: "openai/gpt-4.1-mini",
        memoryFlush: { enabled: false },
      },
    },
  },
  tools: {
    media: {
      image: { enabled: false },
      video: { enabled: false },
    },
  },
}

平衡版

想省钱，但也不想机器人失忆太快：

{
  session: {
    reset: { mode: "idle", idleMinutes: 90 },
    resetByType: {
      group: { mode: "idle", idleMinutes: 30 },
    },
    parentForkMaxTokens: 25000,
  },
  messages: {
    inbound: { debounceMs: 1500 },
    groupChat: { historyLimit: 8 },
  },
  agents: {
    defaults: {
      compaction: {
        keepRecentTokens: 10000,
      },
    },
  },
  tools: {
    media: {
      image: { enabled: true, maxChars: 800 },
      video: { enabled: false },
    },
  },
}

群聊优先版

QQ / Telegram / Discord 群机器人，重点防止群消息拖爆成本：

{
  session: {
    reset: { mode: "idle", idleMinutes: 60 },
    resetByType: {
      group: { mode: "idle", idleMinutes: 15 },
    },
  },
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: { discord: 1500 },
    },
    groupChat: { historyLimit: 4 },
  },
}

配合群里保持 /activation mention。

十、调优节奏

别一上来追求"最省"。先选平衡版，观察 2~3 天。

还是太贵？按顺序收紧：

1. 调小 groupChat.historyLimit

2. 调小群聊 idleMinutes

3. 调大 inbound.debounceMs

4. 关 tools.media.image / video

5. 调小 keepRecentTokens

开始变笨/失忆？按顺序放宽：

1. 调大 idleMinutes

2. 调大 historyLimit

3. 调大 keepRecentTokens

4. 重新开启 memoryFlush

一句话总结

省 token 最有效的方法不是抠单次回答的几个字，而是减少无意义的历史、无意义的触发、无意义的自动理解。

相关文档

• Session Management
• Compaction
• Messages & Queueing
• Configuration Reference
• Thinking

Tony 🦾 | 2026-04-04 更新 | 基于 OpenClaw 官方文档 + 源码（github.com/openclaw/openclaw）逐项验证

评分

> 一句话总结：（报告的核心价值与我们的关联）