OpenClaw 🦞

Token 使用与成本

Token 使用与成本

OpenClaw 追踪tokens，而非字符。Tokens 是模型特定的，但大多数 OpenAI 风格的模型对于英文文本平均每 token 约 4 个字符。

系统提示如何构建

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

  • 工具列表 + 简短描述
  • Skills 列表（仅元数据；指令按需使用 read 加载）
  • 自我更新指令
  • 工作区 + 引导文件（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md（新时），以及存在时的 MEMORY.md 和/或 memory.md）。大文件被 agents.defaults.bootstrapMaxChars 截断（默认：20000），总引导注入被 agents.defaults.bootstrapTotalMaxChars 限制（默认：150000）。memory/*.md 文件通过记忆工具按需加载，不会自动注入。
  • 时间（UTC + 用户时区）
  • 回复标签 + 心跳行为
  • 运行时元数据（主机/操作系统/模型/思考）

详见 系统提示 获取完整分解。

上下文窗口中计算什么

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

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

对于图像，OpenClaw 在提供商调用之前缩小转录/工具图像负载。 使用 agents.defaults.imageMaxDimensionPx（默认：1200）来调整：

  • 较低的值通常减少视觉 token 使用量和负载大小。
  • 较高的值为 OCR/UI 密集的截图保留更多视觉细节。

对于实际分解（每个注入文件、工具、skills 和系统提示大小），使用 /context list 或 /context detail。详见 上下文。

如何查看当前 token 使用量

在聊天中使用这些：

  • /status → 表情丰富的状态卡片，显示会话模型、上下文使用量、 上次响应的输入/输出 tokens，以及估算成本（仅限 API 密钥）。
  • /usage off|tokens|full → 为每条回复附加每响应使用量页脚。
    • 每会话持久化（存储为 responseUsage）。
    • OAuth 认证隐藏成本（仅 tokens）。
  • /usage cost → 显示来自 OpenClaw 会话日志的本地成本摘要。

其他表面：

  • TUI/Web TUI： 支持 /status + /usage。
  • CLI： openclaw status --usage 和 openclaw channels list 显示 提供商配额窗口（非每响应成本）。

成本估算（显示时）

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

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

这些是每 1M tokens 的美元，用于 input、output、cacheRead 和 cacheWrite。如果缺少定价，OpenClaw 仅显示 tokens。OAuth tokens 从不显示美元成本。

缓存 TTL 和修剪影响

提供商提示缓存仅适用于缓存 TTL 窗口内。OpenClaw 可以 可选地运行缓存 TTL 修剪：一旦缓存 TTL 过期就修剪会话，然后 重置缓存窗口，以便后续请求可以重用新缓存的上下文，而不是重新缓存完整历史。 当会话空闲超过 TTL 时，这可以保持缓存写入成本较低。

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

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

在多代理设置中，你可以保持一个共享模型配置，并使用 agents.list[].params.cacheRetention 为每个代理调整缓存行为。

对于完整的旋钮指南，详见 提示缓存。

对于 Anthropic API 定价，缓存读取比输入 tokens 便宜得多，而缓存写入以更高的乘数计费。详见 Anthropic 的 提示缓存定价获取最新费率和 TTL 乘数： https://docs.anthropic.com/docs/build-with-claude/prompt-caching

示例：使用心跳保持 1h 缓存温暖

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" # 大多数代理的默认基线
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m" # 为深度会话保持长缓存温暖
    - id: "alerts"
      params:
        cacheRetention: "none" # 避免为突发通知写入缓存

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

示例：启用 Anthropic 1M 上下文 beta 头

Anthropic 的 1M 上下文窗口目前是 beta 门控的。当你在支持的 Opus 或 Sonnet 模型上启用 context1m 时，OpenClaw 可以注入所需的 anthropic-beta 值。

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          context1m: true

这映射到 Anthropic 的 context-1m-2025-08-07 beta 头。

这仅在该模型条目上设置 context1m: true 时适用。

要求：凭据必须符合长上下文使用资格（API 密钥 计费，或启用了额外使用量的订阅）。如果不符合，Anthropic 会响应 HTTP 429: rate_limit_error: Extra usage is required for long context requests。

如果你使用 OAuth/订阅 tokens（sk-ant-oat-*）认证 Anthropic， OpenClaw 会跳过 context-1m-* beta 头，因为 Anthropic 目前 用 HTTP 401 拒绝该组合。

减少 token 压力的技巧

  • 使用 /compact 摘要长会话。
  • 在工作流程中修剪大型工具输出。
  • 为截图密集的会话降低 agents.defaults.imageMaxDimensionPx。
  • 保持 skill 描述简短（skill 列表注入到提示中）。
  • 为冗长、探索性工作偏好较小的模型。

详见 Skills 获取确切的 skill 列表开销公式。