跳转至

Token 使用与成本

OpenClaw 跟踪的是 token，而不是字符。Token 因模型而异，但大多数 OpenAI 风格的模型对英文文本平均约 4 个字符对应 1 个 token。

系统提示词是如何构建的

OpenClaw 在每次运行时都会组装自己的系统提示词。它包含：

  • 工具列表 + 简短描述
  • 技能列表（仅元数据；指令通过 read 按需加载）。在受管捆绑应用服务器上，Native 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）限制。
  • 当该工作区有可用的记忆工具时，Native 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 根据有效的模型上下文窗口推导实时工具结果上限：低于 100K token 时为 16000 字符，100K+ token 时为 32000 字符，200K+ token 时为 64000 字符。运行时上下文共享保护还会将单个工具结果限制为上下文窗口的 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 -> 显示富含 emoji 的状态卡片，包含会话模型、上下文使用情况、上一次响应的输入/输出 token，以及来自记录账单或活动模型本地定价的成本。
  • /usage off|tokens|full -> 为每次回复附加一个按响应计的使用信息页脚。该设置按会话持久化（存储为 responseUsage）。
  • /usage reset（别名：inherit、clear、default）清除会话覆盖，使其重新继承已配置的默认值。
  • /usage tokens 显示回合 token/缓存详细信息。
  • /usage full 显示紧凑的模型/上下文/成本详细信息。成本来自已记录金额或带有活动模型本地定价的使用元数据。自定义 messages.usageTemplate 布局可以包含 token/缓存字段。
  • /usage cost -> 来自 OpenClaw 会话日志的本地成本摘要。

其他界面：

  • Control UI： 工作指示器和已运行回合摘要显示该次运行的累计输出 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 解析器读取 assistant 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 密钥凭据。

Assistant 转录条目会持久化相同的规范化用量结构，包括当运行时计算出估算值或提供商报告计费金额时的 usage.cost。这为 /usage cost 和基于转录的会话状态提供了稳定来源，即使实时运行时状态已不存在也是如此。

OpenClaw 将提供商用量核算与当前上下文快照分开保存。提供商的 usage.total 可能包含缓存输入、输出以及多次工具循环模型调用，因此它对于成本和遥测很有用，但可能高估实时上下文窗口。上下文显示和诊断使用最新的提示词快照（promptTokens，或当没有提示词快照时使用最后一次模型调用）作为 context.used。

原生 Codex 轮次用量会对每个唯一已完成的模型响应所报告的数量求和，包括重试或取消之前的响应。缺失的响应计数保持未知；它们不会抹去已观察到的用量。缺失最终响应快照会使上下文用量不可用。

成本估算（显示时）

成本根据你的模型定价配置估算：

models.providers.<provider>.models[].cost

这些是 input、output、cacheRead 和 cacheWrite 的 USD / 1M tokens 价格。如果定价和记录金额都缺失，/usage full 会省略成本；当你需要在每次回复中查看 token/缓存详情时，请使用 /usage tokens 或自定义的 messages.usageTemplate。成本显示不仅限于 API 密钥认证：非 API 密钥提供商（如 aws-sdk）在其配置的模型条目包含本地定价且提供商返回用量元数据时，也可以显示估算成本。

当模型发布 tieredPricing 时，每个请求使用其提示词输入总量（未缓存输入加上缓存读取和缓存写入）来选择一个层级。输出 token 不参与选择层级。所选费率适用于该请求中的每个 token 桶，而不仅仅是超过阈值的 token。区间为半开区间 [start, end)；无上限的最终区间使用 [start]。

轮次总计会对每个模型请求计算出的成本求和，并在工具循环和重试之间保留层级和模型边界。如果较旧或外部运行时只提供聚合 token，则仍可使用统一费率估算。没有完整逐请求成本的层级聚合会省略成本，而不是将求和后的 token 视为一个大型请求。提供商计费的总计（包括零）优先于目录估算，并且即使 token 计数不可用也仍然可见。未知的 token 计数不会从计费金额中推断出来。

转录报告会保留有效的已记录逐调用总计和分配，包括 priority/flex 调整；仅对缺失成本或未知价格的零占位符使用当前目录定价。 Anthropic 快速模式估算会同样乘以基础费率和层级费率，保留层级阈值以及混合的 5 分钟/1 小时缓存写入定价。

省略 cost 或将其设为 {} 会继承目录定价方案。显式的统一费率或全零模型价格不会继承目录层级方案。省略的统一费率字段仍可继承目录默认值。显式的 tieredPricing 方案优先于目录方案。

定价更新随模型元数据一起通过托管模型目录发布。其发布者读取公开定价来源，包括当提供商声明原生来源时的 OpenCode 官方目录和 Venice 公开模型 API。基础费率和上下文层级来自同一来源；用量渲染不会发起网络请求。托管更新会在下次 Gateway 重启后生效。在离线或受限网络上，设置 models.catalogRefresh.enabled: false 可禁用托管目录流量；内置定价仍然有效。Agent 本地的 models.json 价格优先于显式的 models.providers.*.models[].cost 条目，而这两者都覆盖目录估算，包括显式的统一费率和零费率。

当 Gateway 写入更新后的 agent 本地 models.json 价格时，后续本地估算会使用这些费率，无需重启。已记录的逐调用成本保持其原始金额。

当精确快捷方式没有价格时，OpenRouter 的 :nitro 和 :floor 路由快捷方式使用基础模型的目录估算。已记录成本和显式价格保持其优先级。私有端点和其它模型变体不使用此回退。Priority 和 flex 计费可能与基础估算不同。

缓存 TTL 与剪枝影响

提供商提示词缓存仅在缓存 TTL 窗口内生效。OpenClaw 可以选择运行缓存 TTL 剪枝（cache-ttl pruning）：一旦缓存 TTL 过期，它会修剪会话，然后重置缓存窗口，使后续请求复用新缓存的上下文，而不是重新缓存完整历史记录。这可以在会话空闲超过 TTL 时降低缓存写入成本。

在 Gateway 配置 中配置它，并在 会话修剪 中查看行为详情。

心跳可以在空闲间隔期间让缓存保持温热。如果你的模型缓存 TTL 为 1h，将心跳间隔设置为略低于该值（例如 55m），可以避免重新缓存完整 Prompt，从而降低缓存写入成本。

在多智能体设置中，你可以保留一个共享的模型配置，并通过 agents.entries.*.params.cacheRetention 按智能体调整缓存行为。

如需完整的逐项配置指南，请参阅 Prompt 缓存。

就 Anthropic API 定价而言，缓存读取比输入 Token 便宜得多，而缓存写入按更高的乘数计费。请参阅 Anthropic 的 Prompt 缓存定价，了解最新的费率和 TTL 乘数： 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。

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        alias: opus

旧配置可以保留 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