Token 使用与成本
OpenClaw 追踪的是 Token,而非字符。Token 因模型而异,但大多数 OpenAI 风格模型对英文文本平均约 4 个字符对应 1 个 Token。
系统提示是如何构建的¶
OpenClaw 在每次运行时都会自行组装系统提示。其中包括:
- 工具列表 + 简短描述
- 技能列表(仅元数据;指令按需通过
read加载)。原生 Codex 会启用受管理的捆绑应用服务,以在父级本地模型请求指令中获取紧凑技能块。没有该中继的连接则使用线程开发者指令;其他工具链在正常提示区域中获取它。受skills.limits.maxSkillsPromptChars限制,并可通过agents.entries.*.skillsLimits.maxSkillsPromptChars进行可选的按代理覆盖。 - 自更新指令
- 工作区 + 引导文件(
AGENTS.md、SOUL.md、IDENTITY.md、USER.md,当为新建时还包括BOOTSTRAP.md,以及存在时的MEMORY.md)。较大的注入文件会由agents.defaults.bootstrapMaxChars(默认:20000)截断;引导注入总量由agents.defaults.bootstrapTotalMaxChars(默认:60000)限制。 - 原生 Codex 回合在内存工具可用于该工作区时不会粘贴原始
MEMORY.md;它们会在父级本地请求指令中获取一个小的内存指针,并按需使用内存工具。如果工具被禁用、内存搜索不可用,或当前工作区与代理内存工作区不同,MEMORY.md将回退到正常的受限回合上下文路径。 - 小写根目录
memory.md永远不会被注入。它是openclaw doctor --fix的遗留修复输入,该命令会将其迁移到MEMORY.md。 memory/*.md每日文件不属于正常引导提示的一部分;它们会在普通回合中通过内存工具按需保留。重置/启动模型运行可以在首回合前添加一个一次性的启动上下文块,其中包含最近的每日内存,由agents.defaults.startupContext控制。裸聊天/new和/reset会被确认,而无需调用模型。- 压缩后的
AGENTS.md摘录需要显式选择启用agents.defaults.compaction.postCompactionSections;插件可以通过before_prompt_build添加其他上下文。 - 时间(UTC + 用户时区)
- 回复标签 + 心跳行为
- 运行时元数据(主机/操作系统/模型/思考)
详见系统提示中的完整说明。
在记录凭据或认证片段时,请使用机密占位符约定,以避免仅文档变更中的机密扫描器误报。
上下文中计入哪些内容¶
模型接收到的所有内容都会计入上下文限制:
- 系统提示(以上所有部分)
- 对话历史(用户 + 助手消息)
- 工具调用和工具结果
- 附件/转录内容(图像、音频、文件)
- 压缩摘要和修剪产物
- 提供者包装器或安全标头(不可见,但仍会计入)
运行时重负载区域在 agents.defaults.contextLimits 下有各自的显式上限(按代理覆盖项位于 agents.entries.*.contextLimits 下):
| Key | Purpose |
|---|---|
memoryGetMaxChars |
memory_get 在截断之前返回的最大字符数。 |
postCompactionMaxChars |
在压缩后刷新期间从 AGENTS.md 保留的最大字符数。 |
这些是受限的运行时摘录和注入的运行时所属块,与引导限制、启动上下文限制和技能提示限制分开。
OpenClaw 根据有效模型上下文窗口推导实时工具结果上限:16000 字符(低于 100K Token)、32000 字符(100K+ Token)、64000 字符(200K+ Token)。运行时上下文共享保护还将单个工具结果限制为上下文窗口的 30%。
大型提供者上下文窗口在实质上改变成本或延迟时不会自动启用。例如,直接使用 OpenAI GPT-5.5 和 GPT-5.6 模型会公布 1050000 Token 的总窗口,但 OpenClaw 默认将其活动运行时预算设为 272000 Token。可选择启用的 922000 输入预算保留完整的 128000 输出额度,而一旦输入超过 272000 Token,OpenAI 会对整个请求应用更高的长上下文定价。请参阅 OpenAI 上下文窗口默认值。
对于图像,OpenClaw 会在提供者调用前缩小转录/工具图像负载。可使用 agents.defaults.imageMaxDimensionPx(默认:1200)进行调整:
- 较低的值会减少视觉 Token 使用量和负载大小。
- 较高的值会为 OCR/UI 密集的截图保留更多视觉细节。
如需实际的细分(每个注入文件、工具、技能和系统提示大小),请使用 /context list 或 /context detail。参见上下文。
如何查看当前的 Token 用量¶
在聊天中:
/status-> 显示一张包含会话模型、上下文使用量、上次响应的输入/输出 Token 以及成本(来自记录账单或活动模型的本地定价)的富表情状态卡片。/usage off|tokens|full-> 每次回复后追加一个每次响应的使用量页脚。按会话持久化(存储为responseUsage)。/usage reset(别名:inherit、clear、default)清除会话覆盖,使其重新继承配置的默认值。/usage tokens显示回合 Token/缓存细节。/usage full显示紧凑的模型/上下文/成本细节。成本来自记录的金额或包含活动模型本地定价的使用量元数据。自定义的messages.usageTemplate布局可包含 Token/缓存字段。/usage cost-> 来自 OpenClaw 会话日志的本地成本摘要。
其他界面:
- 控制界面: 工作指示器和已完成运行的摘要会显示该运行的累计输出 Token,包括其在工具使用和重试期间的模型调用。计数在运行时报告完成响应使用量时更新,而不是在每个流式文本片段中更新。重新加载活动运行会恢复其最新计数。此计数器排除输入 Token,并与编辑器上下文窗口仪表和持久化账单摘要分开。
- TUI/Web TUI: 支持
/status和/usage。 - CLI:
openclaw status --usage和openclaw channels list显示标准化的提供者配额窗口(X% 剩余,而非每次响应成本)。使用量窗口提供者(检查日期:2026.9.3):Claude (Anthropic)、ClawRouter、Copilot (GitHub)、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 时,总计回退到规范化的 input + output。
当当前会话快照不完整时,/status 和 session_status 可以从最近的会话记录用量日志中恢复 token/缓存计数器和活动运行时模型标签。现有的非零实时值仍优先于会话记录回退值,当存储的总计缺失或较小时,较大的提示词相关会话记录总计可以胜出。
提供商配额窗口的用量认证首先来自提供商特定的钩子;如果提供商没有钩子(或钩子无法解析出 token),OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配 OAuth/API 密钥凭据。
助手会话记录条目持久化相同的规范化用量结构,包括运行时计算估算值或提供商报告计费金额时的 usage.cost。这为 /usage cost 和基于会话记录的会话状态提供了稳定的数据源,即使在实时运行时状态消失后也是如此。
OpenClaw 将提供商用量核算与当前上下文快照分开。提供商的 usage.total 可能包含缓存输入、输出和多次工具循环模型调用,因此它对成本和遥测有用,但可能夸大实时上下文窗口。上下文显示和诊断使用最新的提示词快照(promptTokens,或当没有提示词快照时使用最近一次模型调用)作为 context.used。
原生 Codex 回合用量汇总每个唯一已完成的模型响应报告的数量,包括重试或取消之前的响应。缺失的响应数量保持未知状态;它们不会抹除已观察到的用量。缺少最终响应快照会使上下文用量不可用。
成本估算(显示时)¶
成本根据您的模型定价配置进行估算:
这些是 input、output、cacheRead 和 cacheWrite 的每 100 万 token 的 USD 价格。如果定价和已记录金额都缺失,/usage full 会省略成本;当您需要在每次回复中获取 token/缓存详细信息时,请使用 /usage tokens 或自定义的 messages.usageTemplate。成本显示不限于 API 密钥认证:非 API 密钥提供商(如 aws-sdk)在其配置的模型条目包含本地定价且提供商返回用量元数据时,也可以显示估算成本。
当模型发布 tieredPricing 时,每个请求使用其总提示词输入来选择一层:未缓存输入加上缓存读取和缓存写入。输出 token 不参与选择层级。所选费率适用于该请求中的每个 token 桶,而不仅仅是高于阈值的 token。范围是半开区间 [start, end);无上限的最终范围使用 [start]。
回合总计汇总每个模型请求计算出的成本,跨工具循环和重试保留层级和模型边界。如果较旧或外部运行时仅提供聚合 token,则仍可使用统一费率估算。没有完整逐请求成本的层级聚合会省略成本,而不是将汇总的 token 视为一个大型请求。提供商计费的总计(包括零)优先于目录估算,并且即使 token 数量不可用也保持可见。未知的 token 数量不会从计费金额中推断出来。
会话记录报告保留有效的已记录逐调用总计和分配,包括优先级/弹性调整,并且仅在成本缺失或未知价格零占位符时使用当前目录定价。Anthropic 快速模式估算将基础费率和层级费率以相同方式相乘,保留层级阈值和混合的 5 分钟/1 小时缓存写入定价。
省略 cost 或将其设置为 {} 会继承目录定价方案。显式的统一费率或全零模型价格不会继承目录层级方案。省略的统一费率字段仍可继承目录默认值。显式的 tieredPricing 方案优先于目录方案。
定价更新包含在托管模型目录中,与模型元数据一同发布。其发布者读取公开的定价来源,包括 OpenCode 的官方目录和 Venice 的公开模型 API(当提供商声明原生来源时)。基础费率和上下文层级来自同一来源;用量渲染不会发起网络请求。托管更新随 Gateway 下一次准备好的目录生成而激活,无需重启。每次估算操作捕获一个定价上下文,因此一次发布不能中途改变其费率。设置 models.catalogRefresh.enabled: false 可在离线或受限网络上禁用托管目录流量;内置定价仍然有效。代理本地的 models.json 价格优先于显式的 models.providers.*.models[].cost 条目,两者都覆盖目录估算,包括显式的统一费率和零费率。
当 Gateway 写入更新后的代理本地 models.json 价格时,后续本地估算无需重启即可使用这些费率。已记录的逐调用成本保留其原始金额。
OpenRouter 的 :nitro 和 :floor 路由快捷方式在对应快捷方式本身没有价格时,使用基础模型的目录估算。已记录成本和显式价格保持其优先级。私有端点和其他模型变体不使用此回退。优先级和弹性计费可能与基础估算不同。
缓存 TTL 与修剪影响¶
提供商 Prompt 缓存仅在缓存 TTL 窗口内生效。OpenClaw 可选择运行 缓存 TTL 修剪:当缓存 TTL 过期后,它会修剪会话,然后重置缓存窗口,使后续请求复用刚刚缓存的上下文,而不是重新缓存完整历史。当会话空闲超过 TTL 时,这可以降低缓存写入成本。
心跳可以在空闲间隔期间保持缓存处于 热 状态。如果你的模型缓存 TTL 为 1h,将心跳间隔设置为略低于该值(例如 55m)可以避免重新缓存完整 Prompt,从而降低缓存写入成本。
在多代理设置中,你可以保留一个共享模型配置,并使用 agents.entries.*.params.cacheRetention 按代理调整缓存行为。
如需完整的逐项配置指南,请参阅 Prompt 缓存。
对于 Anthropic API 定价,缓存读取比输入 Token 便宜得多,而缓存写入按更高的倍率计费。有关最新费率和 TTL 倍率,请参阅 Anthropic 的 Prompt 缓存定价: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
示例:使用心跳保持 1 小时缓存处于热状态¶
agents:
defaults:
model:
primary: "anthropic/claude-opus-4-6"
models:
"anthropic/claude-opus-4-6":
params:
cacheRetention: "long"
heartbeat:
every: "55m"
示例:混合流量与按代理缓存策略¶
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 notifications
agents.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: true。
旧配置可以保留 context1m: true,但 OpenClaw 不再为此设置发送 Anthropic 已弃用的 context-1m-2025-08-07 beta 请求头,也不会将不支持的旧版 Claude 模型扩展到 1M。
要求:凭据必须支持长上下文使用。如果不支持,Anthropic 会针对该请求返回提供商侧速率限制错误。
如果你使用 OAuth/订阅 Token(sk-ant-oat-*)对 Anthropic 进行身份验证,OpenClaw 会保留 OAuth 所需的 Anthropic beta 请求头,同时移除旧配置中仍然存在的已弃用 context-1m-* beta。
降低 Token 压力的技巧¶
- 使用
/compact总结长会话。 - 在你的工作流中裁剪大型工具输出。
- 对于截图较多的会话,降低
agents.defaults.imageMaxDimensionPx。 - 保持技能描述简短(技能列表会注入到 Prompt 中)。
- 对于冗长、探索性的工作,优先使用较小的模型。
有关技能列表开销的确切公式,请参阅 技能。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw