Token 使用量和费用

OpenClaw 跟踪的是 token，而不是字符。token 因模型而异，但大多数 OpenAI 风格模型在英文文本中平均约为每个 token 4 个字符。

系统提示词的构建方式

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

• 工具列表 + 简短描述
• Skills 列表（仅元数据；指令会按需通过 read 加载）。原生 Codex 轮次会将紧凑 Skills 块作为该轮次范围内的协作 developer instructions；其他 harness 会把它放在普通提示词表面。 受 skills.limits.maxSkillsPromptChars 限制，并可在每个 Agent 的 agents.list[].skillsLimits.maxSkillsPromptChars 中选择性覆盖。
• 自更新指令
• 工作区 + 引导文件（AGENTS.md、SOUL.md、TOOLS.md、 IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md，如果是新的， 还包括存在时的 MEMORY.md）。大型注入文件会按 agents.defaults.bootstrapMaxChars 截断（默认值：20000）；总引导 注入受 agents.defaults.bootstrapTotalMaxChars 限制（默认值： 60000）。
  • 当某个工作区可用记忆工具时，原生 Codex 轮次不会粘贴原始 MEMORY.md；它们会在该轮次范围内的协作 developer instructions 中获得一个小型记忆指针，并按需使用记忆工具。如果工具被禁用、 记忆搜索不可用，或活动工作区不同于 Agent 记忆工作区，MEMORY.md 会回退到普通的有界轮次上下文路径。
  • 小写根目录 memory.md 永远不会被注入。它是 openclaw doctor --fix 的旧版修复输入，会被迁移到 MEMORY.md。
  • memory/*.md 每日文件不是普通引导提示词的一部分；它们在普通轮次中 通过记忆工具按需保留。重置/启动模型运行可以为第一轮预置一个一次性 启动上下文块，其中包含最近的每日记忆，由 agents.defaults.startupContext 控制。纯聊天 /new 和 /reset 会在不调用模型的情况下得到确认。
  • 压缩后的 AGENTS.md 摘录是独立的，并且需要显式选择加入 agents.defaults.compaction.postCompactionSections。
• 时间（UTC + 用户时区）
• 回复标签 + Heartbeat 行为
• 运行时元数据（主机/OS/模型/thinking）

完整拆解见 System Prompt。

记录凭据或认证片段时，请使用 Secret Placeholder Conventions， 以避免仅文档变更触发 secret-scanner 误报。

上下文窗口中包含哪些内容

模型收到的所有内容都会计入上下文限制：

• 系统提示词（上面的所有部分）
• 对话历史（用户 + 助手消息）
• 工具调用和工具结果
• 附件/转录（图像、音频、文件）
• 压缩摘要和剪枝产物
• 提供商包装器或安全头（不可见，但仍会计入）

运行时较重的表面在 agents.defaults.contextLimits 下有自己的显式上限 （每个 Agent 的覆盖项在 agents.list[].contextLimits 下）：

这些是有界运行时摘录和运行时拥有的注入块，独立于引导限制、启动上下文限制 和 Skills 提示词限制。

toolResultMaxChars 默认未设置，因此 OpenClaw 会根据有效模型上下文窗口推导 实时工具结果上限：低于 100K token 时为 16000 个字符，100K+ token 时为 32000 个字符，200K+ token 时为 64000 个字符。即使配置了更大的显式上限， 运行时上下文份额保护仍会将单个工具结果限制为上下文窗口的 30%。

对于图像，OpenClaw 会在调用提供商之前缩小转录/工具图像载荷。可通过 agents.defaults.imageMaxDimensionPx 调整（默认值：1200）：

• 较低值会减少视觉 token 用量和载荷大小。
• 较高值会为 OCR/UI 密集型截图保留更多视觉细节。

如需实用拆解（按注入文件、工具、Skills 和系统提示词大小），请使用 /context list 或 /context detail。参见 Context。

如何查看当前 token 用量

在聊天中：

• /status -> 带丰富表情的状态卡片，包含会话模型、上下文用量、 上次响应的输入/输出 token，以及当活动模型配置了本地定价时的估算成本。
• /usage off|tokens|full -> 为每条回复追加每次响应的用量页脚。 按会话持久化（存储为 responseUsage）。
  • /usage reset（别名：inherit、clear、default）会清除会话覆盖项， 使其重新继承已配置的默认值。
  • /usage tokens 显示轮次 token/缓存详情。
  • /usage full 显示紧凑的模型/上下文/成本详情；估算成本只会在 OpenClaw 拥有活动模型的用量元数据和本地定价时出现。自定义 messages.usageTemplate 布局可以包含 token/缓存字段。
• /usage cost -> 来自 OpenClaw 会话日志的本地成本摘要。

其他表面：

• TUI/Web TUI： 支持 /status 和 /usage。
• CLI： openclaw status --usage 和 openclaw channels list 会显示 标准化的提供商配额窗口（X% left，而不是每次响应成本）。 当前用量窗口提供商：Claude（Anthropic）、ClawRouter、Copilot （GitHub）、DeepSeek、Gemini（Google Gemini CLI）、MiniMax、OpenAI、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/缓存计数器和活动运行时模型标签。现有非零实时值仍优先于 转录回退值；当已存储总量缺失或较小时，较大的面向提示词的转录总量可以胜出。

提供商配额窗口的用量认证会首先来自提供商特定钩子；如果某个提供商没有钩子 （或该钩子未解析出 token），OpenClaw 会回退到从认证配置、环境或配置中匹配 OAuth/API-key 凭据。

助手转录条目会持久化相同的标准化用量形状，包括当活动模型配置了定价且提供商 返回用量元数据时的 usage.cost。这为 /usage cost 和基于转录的会话状态提供了 稳定来源，即使实时运行时状态已经消失。

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

成本估算（显示时）

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

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

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

在 sidecar 和渠道到达 Gateway 网关 ready 路径后，OpenClaw 会为已配置但尚无本地 定价的模型引用启动可选的后台定价引导。该引导会获取远程 OpenRouter 和 LiteLLM 定价目录。在离线或受限网络中，可设置 models.pricing.enabled: false 跳过这些 目录获取；显式 models.providers.*.models[].cost 条目仍会驱动本地成本估算。

缓存 TTL 和剪枝影响

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

在 Gateway 配置 中配置它，并在 Session pruning 中查看行为详情。

Heartbeat 可以在空闲间隔期间保持缓存 warm。如果你的模型缓存 TTL 是 1h， 将 Heartbeat 间隔设置得略低于它（例如 55m）可以避免重新缓存完整提示词，从而 降低缓存写入成本。

在多 Agent 设置中，你可以保留一个共享模型配置，并通过 agents.list[].params.cacheRetention 按 Agent 调整缓存行为。

完整的逐项旋钮指南见 Prompt Caching。

对于 Anthropic API 定价，缓存读取明显比输入 token 便宜，而缓存写入会按更高倍率 计费。最新费率和 TTL 倍率请参见 Anthropic 的提示词缓存定价： https://docs.anthropic.com/docs/build-with-claude/prompt-caching

示例：用 Heartbeat 保持 1h 缓存 warm

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 notifications

agents.list[].params 会合并到所选模型的 params 之上，因此你可以只覆盖 cacheRetention，并保持其他模型默认值不变。

Anthropic 1M 上下文

OpenClaw 会为 Opus 4.8、Opus 4.7、Opus 4.6 和 Sonnet 4.6 等支持 GA 的 Claude 4.x 模型设置 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/订阅令牌（sk-ant-oat-*）对 Anthropic 进行身份验证，OpenClaw 会保留 OAuth 所需的 Anthropic beta 标头，同时移除已停用的 context-1m-* beta（如果它仍存在于旧配置中）。

降低 token 压力的技巧

• 使用 /compact 总结长会话。
• 在你的工作流中裁剪大型工具输出。
• 对截图密集型会话，降低 agents.defaults.imageMaxDimensionPx。
• 保持技能描述简短（技能列表会注入到提示中）。
• 对冗长的探索性工作，优先使用较小的模型。

查看 Skills 了解精确的技能列表开销公式。

相关内容

• API 使用量和费用
• 提示缓存
• 使用量跟踪