本页内容
本页内容
技术参考
Token 使用量和成本
OpenClaw 跟踪 令牌,而不是字符。标记是特定于模型的,但大多数 OpenAI-style 模型对于英语文本来说每个标记平均约为 4 个字符。
系统提示是如何构建的
OpenClaw 会在每次运行时组装自己的系统提示。它包括:
- 工具列表 + 简短描述
- 技能列表(仅限元数据;使用
read按需加载指令)。本机 Codex 打开托管捆绑应用程序服务器,获取父本地模型请求指令中的紧凑技能块。没有该中继的连接使用线程开发人员指令;其他harness将其置于正常的提示界面中。以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)。- 当内存工具可用于该工作区时,Native Codex 不会粘贴原始
MEMORY.md;相反,它们在父本地请求指令中获取一个小内存指针,并根据需要使用内存工具。如果工具被禁用,内存搜索不可用,或者活动工作空间与代理内存工作空间不同,MEMORY.md将回退到正常的有界回合上下文路径。 - 小写根目录
memory.md永远不会被注入。它是给openclaw doctor --fix使用的遗留修复输入,该命令会将其迁移到MEMORY.md。 memory/*.md日常文件不是正常引导提示的一部分;他们在普通轮流中通过记忆工具保持按需状态。 Reset/startup 模型运行可以在第一轮的近期每日内存中添加一次性启动上下文块,由agents.defaults.startupContext控制。无需调用模型即可确认裸聊天/new和/reset。- 进行压缩后,
AGENTS.md摘录需要显式启用agents.defaults.compaction.postCompactionSections;插件可以通过before_prompt_build添加其他上下文。
- 当内存工具可用于该工作区时,Native Codex 不会粘贴原始
- 时间(UTC + 用户时区)
- 回复标签 + 心跳行为
- 运行时元数据 (host/OS/model/thinking)
请参阅 System Prompt 中的完整细分。
记录凭据或身份验证片段时,请使用 Secret 占位符 Conventions 以避免仅文档更改中的秘密扫描器误报。
什么计入上下文窗口
模型接收到的所有内容都会计入上下文限制:
- 系统提示词(上面的所有部分)
- 对话历史(用户消息 + 助手消息)
- 工具调用和工具结果
- Attachments/transcripts(图像、音频、文件)
- 压缩摘要和裁剪产物
- 提供方包装器或安全标头(不可见,但仍会计入)
运行时开销较大的部分有其独立的明确上限,配置位于 agents.defaults.contextLimits(每个代理的覆盖配置位于 agents.entries.*.contextLimits):
| 键 | 用途 |
|---|---|
memoryGetMaxChars |
memory_get 返回结果在截断前的最大字符数。 |
postCompactionMaxChars |
压缩后刷新期间,从 AGENTS.md 中保留的最大字符数。 |
这些都是有界的运行时摘录和注入的运行时内容, 它们与启动引导限制、启动上下文限制以及技能提示词限制是分开的。
OpenClaw 会根据有效模型上下文窗口推导实时工具结果上限: 在 100K tokens 以下为 16000 字符,在 100K+ tokens 时为 32000 字符,在 200K+ tokens 时为 64000 字符。运行时上下文共享保护也会将单个工具结果限制为上下文窗口的 30%。
当大型提供商窗口显着改变成本或延迟时,不会自动启用。例如,直接 OpenAI GPT-5.5 和 GPT-5.6 模型发布 1050000 代币总窗口,但 OpenClaw 将其活动运行时预算默认为 272000 代币。选择加入的 922000 输入预算保留全部 128000 输出限额,一旦输入超过 272000 代币,OpenAI 就会对整个请求应用更高的长上下文定价。请参阅 OpenAI 上下文窗口默认值 。
对于图像,OpenClaw 在提供程序调用之前缩小 transcript/tool 图像有效负载。使用 agents.defaults.imageMaxDimensionPx 进行调谐(默认:1200):
- 更低的值会减少视觉 token 的使用和载荷大小。
- 较高的值可以为 OCR/UI-heavy 屏幕截图保留更多视觉细节。
如需按注入文件、工具、技能和系统提示词大小进行实际拆解,请使用 /context list 或 /context detail。另请参阅 上下文。
如何查看当前 token 使用量
在聊天中:
/status-> 富含表情符号的状态卡,其中包含会话模型、上下文使用、上次响应 input/output 令牌以及活动模型的记录账单或本地定价的成本。/usage off|tokens|full-> 为每次回复附加使用量页脚。 按会话持久化(存储为responseUsage)。/usage reset(别名:inherit、clear、default)会清除会话覆盖值,使其重新继承已配置的默认值。/usage tokens显示轮次 token/cache 详情。/usage full显示紧凑的 model/context/cost 细节。成本来自记录的金额或使用情况元数据以及活动模型的本地定价。自定义messages.usageTemplate布局可以包含 token/cache 字段。
/usage cost-> 来自 OpenClaw 会话日志的本地成本摘要。
其他界面:
- Control UI: 工作指示器和完成的运行回顾显示该运行的累积 输出标记,包括跨工具使用和重试的模型调用。当运行时报告已完成的响应使用情况时计算更新,而不是在每个流式传输的文本片段上计算更新。重新加载活动运行会恢复其最新计数。该计数器不包括输入令牌,并且与编写器上下文窗口计量器和持久计费摘要分开。
- **TUI/Web TUI:**支持
/status和/usage。 - CLI:
openclaw status --usage和openclaw channels list显示规范化的提供商配额窗口(X% left,不是每次响应成本)。使用窗口提供程序,根据 2026.9.3 检查:Claude (Anthropic)、ClawRouter、Copilot (GitHub)、DeepSeek、MiniMax、 OpenAI、OpenRouter、Venice、xAI、小米、小米代币计划和 z.ai. Provider 插件提供这些快照,因此已安装的插件可以添加一个。
使用表面在显示之前标准化常见的提供者本机字段别名。对于 OpenAI-family 响应流量,包括 input_tokens/output_tokens 和 prompt_tokens/completion_tokens,因此传输特定的字段名称不会更改 /status、/usage 或会话摘要。 Gemini CLI 的使用也被标准化:默认的 stream-json 解析器读取辅助 message 事件,并且 stats.cached 映射到 cacheRead,当 CLI 省略显式时使用 stats.input_tokens - stats.cached stats.input 字段。旧版 JSON 会覆盖仍从 response 读取的回复文本。
对于本机 OpenAI-family 响应流量,WebSocket/SSE 使用别名以相同的方式标准化,并且当 total_tokens 缺失或 0 时,总数回落到标准化输入 + 输出。
当当前会话快照较为稀疏时,/status 和 session_status 可以从最近的转录使用日志中恢复 token/cache 计数器以及活动运行时模型标签。 现有的非零实时值仍然优先于转录回退值,而当存储的总数缺失或更小时,更大的、以 prompt 为导向的转录总数可以胜出。
提供者配额窗口的使用验证首先来自提供者特定的挂钩;如果提供程序没有挂钩(或者挂钩无法解析令牌),则 OpenClaw 会回退到匹配来自身份验证配置文件、env 或 config 的 OAuth/API-key 凭据。
当运行时计算估计值或提供商报告计费金额时,助理记录条目保留相同的标准化使用形状,包括 usage.cost。即使实时运行时状态消失后,这也为 /usage cost 和转录支持的会话状态提供了稳定的来源。
如果流在其最终使用报告之前被中断,则令牌和成本核算将不可用。中间令牌快照不计为完整使用,并且 /status 会清除先前响应的计数器,而不是显示中断响应的计数器。使用成本摘要保留已完成响应中的已知金额,并将聚合标记为不完整。提供商报告的终端零仍然是测量的零;初始化的零不是测量值。
OpenClaw 将提供方使用量统计与当前上下文快照分开维护。提供方 usage.total 可能包含缓存输入、输出以及多次工具循环中的模型调用,因此它有助于成本和遥测统计,但可能会高估实时上下文窗口。上下文显示和诊断会使用最新的 prompt 快照(promptTokens,或者在没有 prompt 快照时使用最后一次模型调用)来计算 context.used。
本机 Codex 轮次使用情况对每个唯一已完成模型响应的报告计数进行求和,包括重试或取消之前的响应。缺失回复计数仍然未知;它们不会删除已经观察到的用法。缺少最终响应快照会导致上下文无法使用。
成本估算(显示时)
成本根据你的模型定价配置进行估算:
这些都是USD每 100 万个代币为了input, output, cacheRead, 和cacheWrite。如果定价和记录金额均缺失,/usage full省略成本;使用/usage tokens或自定义messages.usageTemplate当你需要的时候token/cache每个回复中都有详细信息。成本显示不限于API-密钥授权:非API-关键提供商,例如aws-sdk当其配置的模型条目包含本地定价并且提供商返回使用元数据时,可以显示估计成本。
当模型发布 tieredPricing 时,每个请求使用其总提示输入选择一层:未缓存的输入加上缓存读取和缓存写入。输出令牌不选择层。所选速率适用于该请求中的每个令牌桶,而不是仅适用于高于阈值的令牌。范围为半开 [start, end);开放式最终范围使用 [start]。
为每个模型请求计算的周转总数总和成本,跨工具循环和重试保留层和模型边界。如果较旧的或外部运行时仅提供聚合令牌,则统一费率估算仍然可用。没有完整的每个请求成本的分层聚合会忽略成本,而不是将求和的令牌视为一个大请求。提供商计费的总计(包括零)优先于目录估计,并且即使在令牌计数不可用时也保持可见。未知的令牌计数无法从计费金额中推断出来。
成绩单报告保留有效记录的每次调用总计和分配,包括 priority/flex 调整,并仅针对缺失的成本或未知价格的零占位符使用当前目录定价。 Anthropic 快速模式估计乘以基本速率和层速率,保留层阈值和混合 5-minute/1-hour 缓存写入定价。
省略 cost 或将其设置为 {} 将继承目录定价表。明确的固定价格或全零模型价格不会继承目录层计划。省略的统一费率字段仍然可以继承目录默认值。显式 tieredPricing 计划优先于目录计划。
定价更新与模型元数据一起发布在托管模型目录中。当提供商声明本机来源时,其发布者会读取公开定价来源,包括 OpenCode 的官方目录和 Venice 的公开模型 API。基本费率和上下文等级来自同一来源;使用呈现不会发出网络请求。托管更新将随着网关下一个准备好的目录生成而激活,而无需重新启动。每个估算操作都会捕获一个定价环境,因此出版物不能中途更改其费率。设置 models.catalogRefresh.enabled: false 以禁用离线或受限网络上的托管目录流量;捆绑定价仍然有效。代理本地 models.json 价格优先于明确的 models.providers.*.models[].cost 条目,并且两者都会覆盖目录估计,包括明确的统一费率和零费率。
当网关写入更新的代理本地 models.json 价格时,后续本地估算将使用这些费率而无需重新启动。记录的每次通话费用保留其原始金额。
当确切的快捷方式没有价格时,OpenRouter :nitro 和 :floor 布线快捷方式使用基本模型的目录估计。记录的成本和明确的价格保持优先地位。专用端点和其他模型变体不使用此后备。优先计费和灵活计费可能与基本估算不同。
Cache TTL 和剪枝影响
提供方提示词缓存仅在缓存 TTL 窗口内生效。OpenClaw 可以选择性地运行 cache-ttl 剪枝:当会话的 cache TTL 过期后,它会剪枝该会话,然后重置缓存窗口,从而使后续请求复用新缓存的上下文,而不是重新缓存完整历史记录。 这样可以在会话在 TTL 过期后进入空闲状态时,降低缓存写入成本。
在 Gateway configuration 中进行配置,并在 Session pruning 中查看行为细节。
Heartbeat 可以在空闲间隙保持缓存 warm。如果您的模型缓存 TTL 为 1h,则将心跳间隔设置为略低于该值(e.g.、55m)可以避免重新缓存完整提示,从而降低缓存写入成本。
在多代理配置中,你可以使用一份共享的模型配置,并通过 agents.entries.*.params.cacheRetention 为每个代理单独调整缓存行为。
关于逐项旋钮指南,请参见 Prompt Caching。
对于 Anthropic API 定价,缓存读取的费用显著低于输入 token,而缓存写入则按更高的倍数计费。有关最新费率和 TTL 倍数,请参阅 Anthropic 的提示词缓存定价: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
示例:使用心跳保持 1h 缓存温热
示例:按代理使用不同的缓存策略处理混合流量
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/subscription 令牌 (sk-ant-oat-*) 对 Anthropic 进行身份验证,则 OpenClaw 会保留 OAuth- 所需的 Anthropic beta 标头,同时剥离已停用的 context-1m-* beta(如果它保留在旧配置中)。
降低 token 压力的建议
- 使用
/compact来概括长会话。 - 在你的工作流中裁剪大型工具输出。
- 为截图密集型会话降低
agents.defaults.imageMaxDimensionPx。 - 保持技能描述简短(技能列表会被注入到提示中)。
- 对于冗长、探索性工作,优先使用更小的模型。
准确的技能列表开销公式请参见 技能。