OpenClaw Token 用量与成本控制完全指南上下文构建、计费估算与缓存策略【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本篇技术指南系统讲解 OpenClaw 的 Token 计量与成本体系系统提示词如何逐段组装、哪些内容计入上下文窗口、如何通过/usage、/status等命令实时查看用量与费用、成本估算的定价模型以及如何利用缓存 TTL 与心跳机制降低长会话的缓存写入开销。读完本文你将掌握从配置层面到源码层面的完整 Token 预算控制手段能够在多 Agent 生产环境中精准压住上下文膨胀与成本增长。计量基础Token 而非字符OpenClaw 的用量统计以Token为单位而不是字符数。Token 是模型相关的不同模型对同一段文本的分词结果可能不同。作为通用估算基准大多数 OpenAI 风格模型对英文文本的平均分词密度约为每 Token 约 4 个字符。这一换算关系贯穿全文多个关键逻辑——例如工具结果上限、上下文占比守卫等都以“Token 数 × 4 ≈ 字符数”作为近似换算见 工具结果上限源码因此在阅读配置项时需要时刻在“字符数”与“Token 数”两个单位之间切换理解。系统提示词是如何逐段组装的OpenClaw 在每次运行时都会重新组装自己的系统提示词而不是复用一份静态文本。组装内容包含以下组成部分组成部分说明工具列表工具名 简短描述Skills 列表仅注入元数据完整指令按需通过read加载自更新指令Self-update 相关提示工作区与引导文件AGENTS.md、SOUL.md、IDENTITY.md、USER.md新会话时的BOOTSTRAP.md以及存在时的MEMORY.md时间信息UTC 时间 用户时区回复标签与心跳行为Reply tags heartbeat 行为说明运行时元数据主机 / 操作系统 / 模型 / 思考模式Skills 列表的注入策略Skills 列表只注入元数据名称、简介完整指令在需要时才通过read加载从而避免把全部 Skill 文档塞进上下文。整个技能列表块受skills.limits.maxSkillsPromptChars上限约束并支持按 Agent 覆盖agents.entries.*.skillsLimits.maxSkillsPromptChars。此外存在一个特例Native Codex模式下托管的内置 app-server 会启用紧凑型 skills 块注入到 parent-local 模型请求指令中其他 harness 则在常规提示面中获得该块。配置层面对该上限的合并逻辑可以在 Agent 作用域配置 中看到。引导文件的注入与截断大型注入文件会被截断相关上限如下配置键默认值作用agents.defaults.bootstrapMaxChars20000单个引导文件的注入字符上限agents.defaults.bootstrapTotalMaxChars60000全部引导注入的总字符上限当总注入量逼近上限时OpenClaw 会给出预算警告提示“若非有意为之请调高agents.defaults.bootstrapMaxChars和/或agents.defaults.bootstrapTotalMaxChars”见 引导预算警告实现 与对应的 预算测试用例。围绕MEMORY.md与memory.md有若干值得注意的细节Native Codex 特例当工作区可用记忆工具时Native Codex 回合不会把原始MEMORY.md直接粘贴进提示词而是在 parent-local 请求指令中放入一个简短的记忆指针按需调用记忆工具。仅当工具被禁用、记忆搜索不可用或活动工作区与 Agent 记忆工作区不一致时MEMORY.md才回退到常规的有界回合上下文路径。小写memory.md永不注入它只是openclaw doctor --fix的遗留修复输入会被迁移为MEMORY.md。memory/*.md每日文件不属于常规引导提示普通回合中它们通过记忆工具按需获取。仅在 reset/startup 模型运行时可把近期每日记忆作为一次性 startup 上下文块前置到首个回合由agents.defaults.startupContext控制。裸聊天的/new与/reset只做确认、不触发模型调用。压缩后的AGENTS.md摘录默认不注入需要显式开启agents.defaults.compaction.postCompactionSections相关类型定义可见 压缩保护运行时。插件则可以通过before_prompt_build注入其他上下文。系统提示词的完整构成清单可进一步参考 System Prompt 概念文档。文档安全提示在文档或配置中记录凭证、认证片段时请遵循 Secret Placeholder 约定避免文档改动触发 secret-scanner 误报。什么计入上下文窗口模型收到的一切内容都计入上下文上限系统提示词上文全部小节对话历史用户 助手消息工具调用与工具结果附件 / 转录图片、音频、文件压缩摘要与剪枝产物compaction summaries、pruning artifacts提供商包装器或安全头用户不可见但仍计入运行时上下文的显式上限运行时较重的界面runtime-heavy surfaces在agents.defaults.contextLimits下拥有自己的显式上限按 Agent 覆盖为agents.entries.*.contextLimitsKey作用memoryGetMaxCharsmemory_get在截断前返回的最大字符数postCompactionMaxChars压缩后刷新时从AGENTS.md保留的最大字符数这两项是有界的运行时摘录与运行时自持块与引导上限、startup 上下文上限、skills 提示上限彼此独立、互不影响。工具结果上限的动态推导OpenClaw 会根据生效模型上下文窗口动态推导实时工具结果上限live tool-result cap上下文窗口规模实时工具结果上限低于 100K Token16000字符100K Token 及以上32000字符200K Token 及以上64000字符同时运行时上下文共享守卫runtime context-share guard会把单个工具结果限制在上下文窗口的 30% 以内。这两套逻辑在源码中分别对应resolveAutoLiveToolResultMaxChars按窗口分级取上限与calculateMaxToolResultCharsWithCapcontextWindowTokens × 0.3 × 4与硬上限取较小值详见 工具结果上限源码。大窗口不自动启用当大提供商窗口会实质性改变成本或延迟时OpenClaw不会自动启用。典型例子直接连接的 OpenAI GPT-5.5 / GPT-5.6 模型发布的总窗口为1050000Token但 OpenClaw 默认把它们的活动运行时预算设为272000Token可选加入的922000输入预算则保留完整的128000输出配额。需要注意一旦输入超过272000TokenOpenAI 会对整个请求应用更高的长上下文定价。详细说明见 OpenAI 上下文窗口默认值。图片载荷的下采样对图片OpenClaw 会在调用提供商之前对转录 / 工具图片载荷做下采样通过agents.defaults.imageMaxDimensionPx调优默认1200调低 → 减少视觉 Token 消耗与载荷体积调高 → 为 OCR、UI 密集型截图保留更多视觉细节。源码侧默认值与解析逻辑位于 图片净化模块DEFAULT_IMAGE_MAX_DIMENSION_PX 1200同时还有DEFAULT_IMAGE_MAX_BYTES 5 * 1024 * 10245MB的字节上限供工具与提供商载荷构建器共用。如需按“每个注入文件、工具、skills、系统提示词大小”逐项拆解可在会话内使用/context list或/context detail并参考 Context 概念文档。如何查看当前 Token 用量聊天内命令/status输出 emoji 丰富的状态卡片包含会话模型、上下文用量、最近一次响应的输入/输出 Token 数以及来自记录账单或当前模型本地定价的成本估算。/usage off|tokens|full为每条回复追加一个用量页脚per-response usage footer按会话持久化存储为responseUsage。/usage reset别名inherit、clear、default清除会话覆盖恢复继承配置默认值。/usage tokens显示单回合 Token / 缓存细节。/usage full显示紧凑的模型 / 上下文 / 成本细节。成本来自记录金额或基于当前模型本地定价的用量元数据。自定义messages.usageTemplate布局可包含 Token / 缓存字段。/usage cost基于 OpenClaw 会话日志的本地成本汇总。配置层的messages.usageTemplate与messages.responseUsage均在 消息配置 Schema 中定义并在 配置标签表 中登记为“Usage Footer Template”与“Default Usage Footer Mode”。其他界面界面能力Control UI工作指示器与已完成任务回顾中显示该次运行的累计输出 Token涵盖工具调用与重试中的模型调用仅在运行时上报完成响应用量时更新计数而不是每次流式文本片段都更新重新加载进行中的运行会恢复最新计数。该计数器不含输入 Token且与 composer 的上下文窗口计量器、持久化账单摘要相互独立TUI / Web TUI支持/status与/usageCLIopenclaw status --usage与openclaw channels list显示归一化后的提供商配额窗口X% left而非单次响应成本截至 2026.9.3 检查具备用量窗口的提供商包括ClaudeAnthropic、ClawRouter、CopilotGitHub、DeepSeek、MiniMax、OpenAI、OpenRouter、Venice、xAI、Xiaomi、Xiaomi Token Plan 与 z.ai。这些快照由提供商插件提供因此安装相应插件即可扩展支持面。用量数据的归一化用量展示层会先对常见的提供商原生字段别名做归一化OpenAI 家族的 Responses 流量同时兼容input_tokens/output_tokens与prompt_tokens/completion_tokens两套字段因此传输层字段名差异不会影响/status、/usage或会话摘要。Gemini CLI 用量同样归一化默认stream-json解析器读取助手的message事件stats.cached映射为cacheRead当 CLI 未给出显式stats.input字段时用stats.input_tokens - stats.cached计算。旧式 JSON 覆盖仍从response读取回复文本。原生 OpenAI 家族 Responses 流量中WebSocket/SSE 用量别名按相同规则归一化当total_tokens缺失或为0时总数回退为归一化的输入 输出之和。当当前会话快照数据稀疏时/status与session_status可以从最近的转录用量日志中恢复 Token / 缓存计数与活跃运行时模型标签现有非零的实时值仍优先于转录回退值而更大的面向提示词的转录总量可能在存储总量缺失或更小时胜出。用量认证方面提供商配额窗口优先使用各提供商专用钩子若提供商没有钩子或钩子未解析出 TokenOpenClaw 回退到从认证配置、环境变量或配置中匹配 OAuth / API-Key 凭证。会话转录与用量持久化助手转录条目持久化相同的归一化用量结构包含运行时估算成本或提供商上报的已计费金额时的usage.cost字段。这为/usage cost与转录支撑的会话状态提供了稳定数据源——即使实时运行时状态已经消失。OpenClaw 将提供商用量记账与当前上下文快照分开提供商的usage.total可能包含缓存输入、输出以及多轮工具循环的多次模型调用适合成本与遥测但可能高估实时上下文窗口。上下文展示与诊断使用最新提示快照promptTokens无提示快照时取最近一次模型调用来计算context.used。Native Codex 回合用量汇总每次已完成的唯一模型响应上报的计数含重试或取消前的响应缺失的响应计数保持未知不会抹掉已观测的用量但缺失最终响应快照时上下文用量不可用。成本估算何时显示、如何计算成本估算基于模型定价配置models.providers.provider.models[].cost这些价格是每 100 万 Token 的美元价格USD per 1M tokens分input、output、cacheRead、cacheWrite四个桶。若定价与记录金额同时缺失/usage full将省略成本此时可改用/usage tokens或自定义messages.usageTemplate在每条回复中获取 Token / 缓存细节。成本显示不限于 API-Key 认证像aws-sdk这类非 API-Key 提供商只要其配置的模型条目包含本地定价且提供商返回用量元数据也能显示估算成本。分层定价tieredPricing规则当模型发布tieredPricing时每个请求依据其总提示输入未缓存输入 缓存读取 缓存写入选择一个分层输出 Token 不参与分层选择。选中层的费率应用于该请求的每一个 Token 桶而不是仅作用于阈值之上的 Token。区间为左闭右开[start, end)开放式末尾区间写作[start]。回合总成本是每个模型请求估算成本之和并在工具循环与重试之间保留分层与模型边界。若旧版或外部运行时只提供聚合 Token则继续可用统一费率估算而缺少完整逐请求成本的分层聚合会省略成本而不是把求和后的 Token 当作一次大请求处理。其他关键规则提供商计费总额含零优先于目录估算即使 Token 计数不可用也保持可见未知 Token 计数不会从已计费金额反推。转录报告保留有效的逐调用总额与分配含 priority/flex 调整仅对缺失成本或未知价格的零占位符使用当前目录定价。Anthropic 快速模式估算对基础费率与分层费率一律乘以倍率同时保留分层阈值与混合的 5 分钟 / 1 小时缓存写入定价。定价继承与目录刷新省略cost或设为{}→ 继承目录定价计划catalog pricing schedule。显式的统一费率或全零模型价格 → 不继承目录分层计划但省略的统一费率字段仍可继承目录默认值。显式tieredPricing计划 → 优先于目录计划。本地models.json价格优先于显式的models.providers.*.models[].cost条目两者都覆盖目录估算含显式统一费率与零费率。定价更新随托管模型目录hosted model catalog与模型元数据一起发布其发布者读取公开定价源包括 OpenCode 官方目录以及提供商声明原生来源时 Venice 的公开模型 API基础费率与上下文分层同源用量渲染不发网络请求。托管更新在下次 Gateway 重启后生效。离线或受限网络环境可设置models.catalogRefresh.enabled: false关闭托管目录流量捆绑定价仍然可用。当 Gateway 写入更新后的 Agent 本地models.json价格时后续本地估算无需重启即可使用新费率已记录的逐调用成本保留原始金额。OpenRouter 的:nitro与:floor路由快捷方式在精确快捷方式无价格时使用基础模型的目录估算记录成本与显式价格保持其优先级私有端点与其他模型变体不使用此回退。Priority 与 flex 计费可能不同于基础估算。缓存 TTL 与剪枝对成本的影响提供商提示缓存只在缓存 TTL 窗口内生效。OpenClaw 可选运行cache-ttl 剪枝一旦缓存 TTL 过期就剪掉会话然后重置缓存窗口使后续请求复用新缓存的上下文而不是重新缓存全部历史。这能在会话空闲超过 TTL 时降低缓存写入成本。源码侧的默认行为mode: cache-ttl时 TTL 解析失败会回退到内置的 5 分钟默认值5 * 60_000ms并支持hardClear与占位符替换具体见 缓存 TTL 剪枝实现。配置入口位于 Gateway 配置行为细节见 Session pruning 概念文档。心跳保温心跳可以在空闲间隙保持缓存“热”。如果模型缓存 TTL 是1h把心跳间隔设为略低于它例如55m就能避免重新缓存整个提示词从而降低缓存写入成本。多 Agent 场景下可保持一份共享模型配置再通过agents.entries.*.params.cacheRetention按 Agent 调优缓存行为。cacheRetention的合法取值在源码中约束为none | short | long非法值会被警告并忽略见 extra-params 实现 与 L361-L366。完整的逐旋钮knob-by-knob指南参见 Prompt Caching 参考文档。示例用心跳保温 1 小时缓存agents: defaults: model: primary: anthropic/claude-opus-4-6 models: anthropic/claude-opus-4-6: params: cacheRetention: long heartbeat: every: 55m示例混合流量下的按 Agent 缓存策略agents: defaults: model: primary: anthropic/claude-opus-4-6 models: anthropic/claude-opus-4-6: params: cacheRetention: long # default baseline for most agents list: - id: research default: true heartbeat: every: 55m # keep long cache warm for deep sessions - id: alerts params: cacheRetention: none # avoid cache writes for bursty notificationsagents.entries.*.params会叠加到所选模型的params之上因此可以只覆盖cacheRetention其余模型默认值原样继承。Anthropic 1M 上下文OpenClaw 会把具备 GA 能力的 Claude 4.x 模型如 Opus 4.8、Opus 4.7、Opus 4.6、Sonnet 4.6按 Anthropic 1M 上下文窗口缩放这些模型无需设置params.context1m: trueagents: defaults: models: anthropic/claude-opus-4-6: alias: opus旧配置可以继续保留context1m: true但 OpenClaw 不再为此发送 Anthropic 已退役的context-1m-2025-08-07beta 头也不会把不支持的旧版 Claude 模型扩展到 1M。前提是凭证必须具有长上下文使用资格否则 Anthropic 会针对该请求返回提供商侧限流错误。若使用 OAuth / 订阅 Tokensk-ant-oat-*认证 AnthropicOpenClaw 会保留 OAuth 必需的 Anthropic beta 头同时剥离旧配置中残留的已退役context-1m-*beta。关于 Anthropic 的缓存定价缓存读取显著便宜于输入 Token缓存写入则按更高倍数计费具体费率与 TTL 倍数以 Anthropic 官方提示缓存定价页为准。降低 Token 压力的实用技巧使用/compact总结长会话在工作流中裁剪过大的工具输出对截图密集型会话调低agents.defaults.imageMaxDimensionPx保持 Skill 描述简短Skill 列表会注入提示词对冗长的探索性工作优先选择更小的模型。Skill 列表开销的确切公式见 Skills 工具文档。延伸阅读API 用量与成本提示缓存用量追踪概念【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
