Token Optimizer

用于OpenClaw部署的综合性工具包，旨在减少令牌使用量和API成本。结合了智能模型路由、优化的心跳间隔、使用量跟踪和多提供商策略。

快速开始

立即行动（无需更改配置）：

1. 生成优化的AGENTS.md（最大收益！）：

   python3 scripts/context_optimizer.py generate-agents
   # Creates AGENTS.md.optimized — review and replace your current AGENTS.md
   

2. 检查你实际需要的上下文：

   python3 scripts/context_optimizer.py recommend "hi, how are you?"
   # Shows: Only 2 files needed (not 50+!)
   

3. 安装优化的心跳机制：

   cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md
   

4. 为休闲聊天强制使用更便宜的模型：

   python3 scripts/model_router.py "thanks!"
   # Single-provider Anthropic setup: Use Sonnet, not Opus
   # Multi-provider setup (OpenRouter/Together): Use Haiku for max savings
   

5. 检查当前令牌预算：

   python3 scripts/token_tracker.py check
   

预期节省：对于典型工作负载，令牌成本可降低50-80%（上下文优化是最大因素！）。

核心功能

0. 惰性技能加载（v3.0新增 — 最大收益！）

这是目前可用的、影响最大的优化。大多数智能体在每个会话中会浪费3,000至15,000个令牌来加载它们从未使用的技能文件。请首先停止这种行为。

模式：

1. 创建一个轻量级的技能文档工作区中的目录（约300个词元——技能列表 + 加载时机）
2. 仅在任务实际需要时加载单个技能文档
3. 对记忆文件应用相同逻辑——启动时加载记忆文档，日志仅在需要时加载

词元节省：

库大小	之前（积极加载）	之后（惰性加载）	节省量
5项技能	约3,000词元	约600词元	80%
10项技能	约6,500词元	约750词元	88%
20项技能	约13,000词元	约900词元	93%

在代理文档中的快速实现：

## Skills

At session start: Read SKILLS.md (the index only — ~300 tokens).
Load individual skill files ONLY when a task requires them.
Never load all skills upfront.

完整实现（含目录模板 + 优化脚本）：

clawhub install openclaw-skill-lazy-loader

配套技能openclaw-skill-lazy-loader包含一个SKILLS.md.template、一个AGENTS.md.template懒加载部分，以及一个context_optimizer.pyCLI，它能针对任何给定任务精确推荐应加载哪些技能。

懒加载处理上下文加载成本。以下剩余功能则处理运行时成本。它们共同覆盖了完整的令牌生命周期。

---

1. 上下文优化（新功能！）

最大的令牌节省器——仅加载你实际需要的文件，而非一次性加载所有内容。

问题：默认的 OpenClaw 每次会话都会加载所有上下文文件：

• SOUL.md、AGENTS.md、USER.md、TOOLS.md、MEMORY.md
• docs/**/*.md（数百个文件）
• memory/2026-*.md（每日日志）
• 总计：通常在用户甚至还未开口前就已达 5 万+ 令牌！

解决方案：基于提示复杂度的懒加载。

用法：

python3 scripts/context_optimizer.py recommend "<user prompt>"

示例：

# Simple greeting → minimal context (2 files only!)
context_optimizer.py recommend "hi"
→ Load: SOUL.md, IDENTITY.md
→ Skip: Everything else
→ Savings: ~80% of context

# Standard work → selective loading
context_optimizer.py recommend "write a function"
→ Load: SOUL.md, IDENTITY.md, memory/TODAY.md
→ Skip: docs, old memory, knowledge base
→ Savings: ~50% of context

# Complex task → full context
context_optimizer.py recommend "analyze our entire architecture"
→ Load: SOUL.md, IDENTITY.md, MEMORY.md, memory/TODAY+YESTERDAY.md
→ Conditionally load: Relevant docs only
→ Savings: ~30% of context

输出格式：

{
  "complexity": "simple",
  "context_level": "minimal",
  "recommended_files": ["SOUL.md", "IDENTITY.md"],
  "file_count": 2,
  "savings_percent": 80,
  "skip_patterns": ["docs/**/*.md", "memory/20*.md"]
}

集成模式：为新会话加载上下文前：

from context_optimizer import recommend_context_bundle

user_prompt = "thanks for your help"
recommendation = recommend_context_bundle(user_prompt)

if recommendation["context_level"] == "minimal":
    # Load only SOUL.md + IDENTITY.md
    # Skip everything else
    # Save ~80% tokens!

生成优化的 AGENTS.md：

context_optimizer.py generate-agents
# Creates AGENTS.md.optimized with lazy loading instructions
# Review and replace your current AGENTS.md

预期节省：上下文令牌减少 50-80%。

2. 智能模型路由（增强版！）

自动分类任务并路由到合适的模型层级。

新增：通信模式强制实施— 绝不在“嗨”或“谢谢”上浪费 Opus 令牌！

用法：

python3 scripts/model_router.py "<user prompt>" [current_model] [force_tier]

示例：

# Communication (NEW!) → ALWAYS Haiku
python3 scripts/model_router.py "thanks!"
python3 scripts/model_router.py "hi"
python3 scripts/model_router.py "ok got it"
→ Enforced: Haiku (NEVER Sonnet/Opus for casual chat)

# Simple task → suggests Haiku
python3 scripts/model_router.py "read the log file"

# Medium task → suggests Sonnet
python3 scripts/model_router.py "write a function to parse JSON"

# Complex task → suggests Opus
python3 scripts/model_router.py "design a microservices architecture"

强制使用 Haiku 模型的模式（绝不使用 Sonnet/Opus）：

通信：

• 问候语：嗨，嘿，你好，哟
• 感谢语：谢谢，感谢你，thx
• 确认语：好的，当然，明白了，理解
• 简短回应：是，否，是的，不
• 单个词汇或极短短语

后台任务：

• 心跳检查："检查邮件"，"监控服务器"
• 定时任务："计划任务"，"定期检查"，"提醒"
• 文档解析："解析CSV"，"从日志中提取数据"，"读取JSON"
• 日志扫描："扫描错误日志"，"处理日志"

集成模式：

from model_router import route_task

user_prompt = "show me the config"
routing = route_task(user_prompt)

if routing["should_switch"]:
    # Use routing["recommended_model"]
    # Save routing["cost_savings_percent"]

自定义：编辑ROUTING_RULES或COMMUNICATION_PATTERNS在scripts/model_router.py文件中以调整模式和关键词。

3. 心跳优化

通过智能间隔跟踪减少心跳轮询的API调用：

设置：

# Copy template to workspace
cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md

# Plan which checks should run
python3 scripts/heartbeat_optimizer.py plan

命令：

# Check if specific type should run now
heartbeat_optimizer.py check email
heartbeat_optimizer.py check calendar

# Record that a check was performed
heartbeat_optimizer.py record email

# Update check interval (seconds)
heartbeat_optimizer.py interval email 7200  # 2 hours

# Reset state
heartbeat_optimizer.py reset

工作原理：

• 记录每种类型（电子邮件、日历、天气等）的最后检查时间。
• 强制执行重新检查前的最小时间间隔。
• 尊重静默时段（23:00-08:00）——跳过所有检查。
• 返回HEARTBEAT_OK当无需关注任何事项时（节省令牌）。

默认间隔：

• 电子邮件：60分钟
• 日历：2小时
• 天气：4小时
• 社交：2小时
• 监控：30分钟

在HEARTBEAT.md中的集成：

## Email Check
Run only if: `heartbeat_optimizer.py check email` → `should_check: true`
After checking: `heartbeat_optimizer.py record email`

预期节省：心跳API调用减少50%。

模型执行规定：心跳应始终使用Haiku模型——请参阅已更新的HEARTBEAT.template.md了解模型覆盖指令。

4. 定时任务优化（新增！）

问题：Cronjobs 通常会默认使用昂贵的模型（Sonnet/Opus），即使是处理日常任务。

解决方案：对于90%的定时任务，始终指定使用 Haiku 模型。

请参阅： assets/cronjob-model-guide.md获取包含示例的完整指南。

快速参考：

任务类型	模型	示例
监控/警报	Haiku	检查服务器健康状况、磁盘空间
数据解析	Haiku	提取 CSV/JSON/日志
提醒	Haiku	每日站会、备份提醒
简单报告	Haiku	状态摘要
内容生成	Sonnet	博客摘要（质量优先）
深度分析	十四行诗	每周洞察
复杂推理	切勿将Opus用于定时任务

示例（良好）：

# Parse daily logs with Haiku
cron add --schedule "0 2 * * *" \
  --payload '{
    "kind":"agentTurn",
    "message":"Parse yesterday error logs and summarize",
    "model":"anthropic/claude-haiku-4"
  }' \
  --sessionTarget isolated

示例（不佳）：

# ❌ Using Opus for simple check (60x more expensive!)
cron add --schedule "*/15 * * * *" \
  --payload '{
    "kind":"agentTurn",
    "message":"Check email",
    "model":"anthropic/claude-opus-4"
  }' \
  --sessionTarget isolated

节省：每天10个定时任务使用Haiku替代Opus =每个代理每月节省17.70美元。

与model_router集成：

# Test if your cronjob should use Haiku
model_router.py "parse daily error logs"
# → Output: Haiku (background task pattern detected)

5. 令牌预算跟踪

监控使用情况并在接近限制时发出警报：

设置：

# Check current daily usage
python3 scripts/token_tracker.py check

# Get model suggestions
python3 scripts/token_tracker.py suggest general

# Reset daily tracking
python3 scripts/token_tracker.py reset

输出格式：

{
  "date": "2026-02-06",
  "cost": 2.50,
  "tokens": 50000,
  "limit": 5.00,
  "percent_used": 50,
  "status": "ok",
  "alert": null
}

状态级别：

• 正常：低于每日限制的80%
• 警告：达到每日限制的80-99%
• 超出：超过每日限制

集成模式：在开始昂贵操作前，检查预算：

import json
import subprocess

result = subprocess.run(
    ["python3", "scripts/token_tracker.py", "check"],
    capture_output=True, text=True
)
budget = json.loads(result.stdout)

if budget["status"] == "exceeded":
    # Switch to cheaper model or defer non-urgent work
    use_model = "anthropic/claude-haiku-4"
elif budget["status"] == "warning":
    # Use balanced model
    use_model = "anthropic/claude-sonnet-4-5"

自定义：编辑daily_limit_usd和warn_threshold函数调用中的参数。

6. 多提供商策略

参见references/PROVIDERS.md获取关于以下内容的全面指南：

• 替代提供商（OpenRouter、Together.ai、Google AI Studio）
• 成本对比表
• 按任务复杂度的路由策略
• 针对速率限制场景的备用链
• API密钥管理

快速参考：

提供商	模型	成本/MTok	使用场景
Anthropic	Haiku 4	0.25美元	简单任务
Anthropic	Sonnet 4.5	3.00美元	平衡默认
Anthropic	Opus 4	15.00美元	复杂推理
OpenRouter	Gemini 2.5 Flash	0.075美元	批量操作
Google AI	Gemini 2.0 Flash Exp	免费	开发/测试
Together	Llama 3.3 70B	0.18美元	开放替代方案

配置补丁

查看assets/config-patches.json以获取高级优化设置：

通过此技能实现：

• ✅ 心跳优化（功能完整）
• ✅ 令牌预算追踪（功能完整）
• ✅ 模型路由逻辑（功能完整）

原生 OpenClaw 2026.2.15 — 直接应用：

• ✅ 会话剪枝（contextPruning: cache-ttl）— 在 Anthropic 缓存 TTL 过期后自动修剪旧的工具结果
• ✅ 引导大小限制（bootstrapMaxChars/bootstrapTotalMaxChars）— 限制工作空间文件注入大小
• ✅ 长期缓存保留（cacheRetention: "long"针对 Opus）— 分摊缓存写入成本

需要 OpenClaw 核心支持：

• ⏳ 提示缓存（Anthropic API 功能 — 请验证当前状态）
• ⏳ 延迟上下文加载（立即使用context_optimizer.py脚本）
• ⏳ 多供应商回退（部分支持）

应用配置补丁：

# Example: Enable multi-provider fallback
gateway config.patch --patch '{"providers": [...]}'

原生 OpenClaw 诊断（2026.2.15+）

OpenClaw 2026.2.15 版本增加了内置命令，作为此技能 Python 脚本的补充。在求助脚本之前，请首先使用这些命令进行快速诊断。

上下文分解

/context list    → token count per injected file (shows exactly what's eating your prompt)
/context detail  → full breakdown including tools, skills, and system prompt sections

应用前使用bootstrap_size_limits— 查看哪些文件过大，然后相应设置bootstrapMaxChars。

单次响应用量追踪

/usage tokens    → append token count to every reply
/usage full      → append tokens + cost estimate to every reply
/usage cost      → show cumulative cost summary from session logs
/usage off       → disable usage footer

与token_tracker.py—/usage cost命令结合可提供会话总量；token_tracker.py则追踪每日预算。

会话状态

/status          → model, context %, last response tokens, estimated cost

---

缓存 TTL 心跳对齐（v1.4.0 新增）

问题在于：Anthropic对缓存写入的收费大约是缓存读取的3.75倍写入比缓存读取贵。如果你的代理闲置，且1小时缓存TTL过期，下一次请求将重新写入整个提示缓存——这非常昂贵。

解决方案：将心跳间隔设置为55分钟（刚好低于1小时的TTL）。心跳保持缓存处于活跃状态，这样每个后续请求都只需支付缓存读取的费用。

# Get optimal interval for your cache TTL
python3 scripts/heartbeat_optimizer.py cache-ttl
# → recommended_interval: 55min (3300s)
# → explanation: keeps 1h Anthropic cache warm

# Custom TTL (e.g., if you've configured 2h cache)
python3 scripts/heartbeat_optimizer.py cache-ttl 7200
# → recommended_interval: 115min

应用到您的OpenClaw配置：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "55m"
      }
    }
  }
}

谁受益：仅限Anthropic API密钥用户。OAuth配置文件默认已设置为1小时心跳（OpenClaw智能默认设置）。API密钥配置文件默认为30分钟——将其增加到55分钟既更便宜（调用次数更少），又能保持缓存活跃。

---

部署模式

个人使用

1. 安装优化的HEARTBEAT.md
2. 在执行昂贵操作前进行预算检查
3. 仅在需要时手动将复杂任务路由到Opus

预期节省：20-30%

适用于托管服务（xCloud等）

1. 将所有智能体默认设置为Haiku
2. 将用户交互路由至Sonnet
3. 为明确复杂的请求保留Opus
4. 将Gemini Flash用于后台操作
5. 为每位客户实施每日预算上限

预期节省：40-60%

适用于高流量部署

1. 使用多供应商回退机制（OpenRouter + Together.ai）
2. 实施激进路由策略（80% Gemini, 15% Haiku, 5% Sonnet）
3. 部署本地Ollama用于离线/低成本操作
4. 批量心跳检查（每2-4小时一次，而非30分钟）

预期节省：70-90%

集成示例

工作流：智能任务处理

# 1. User sends message
user_msg="debug this error in the logs"

# 2. Route to appropriate model
routing=$(python3 scripts/model_router.py "$user_msg")
model=$(echo $routing | jq -r .recommended_model)

# 3. Check budget before proceeding
budget=$(python3 scripts/token_tracker.py check)
status=$(echo $budget | jq -r .status)

if [ "$status" = "exceeded" ]; then
    # Use cheapest model regardless of routing
    model="anthropic/claude-haiku-4"
fi

# 4. Process with selected model
# (OpenClaw handles this via config or override)

工作流：优化心跳

## HEARTBEAT.md

# Plan what to check
result=$(python3 scripts/heartbeat_optimizer.py plan)
should_run=$(echo $result | jq -r .should_run)

if [ "$should_run" = "false" ]; then
    echo "HEARTBEAT_OK"
    exit 0
fi

# Run only planned checks
planned=$(echo $result | jq -r '.planned[].type')

for check in $planned; do
    case $check in
        email) check_email ;;
        calendar) check_calendar ;;
    esac
    python3 scripts/heartbeat_optimizer.py record $check
done

故障排除

问题：脚本运行失败，提示“找不到模块”

• 修复方法：确保已安装Python 3.7+。脚本仅使用标准库。

问题：状态文件未能持久保存

• 修复方法：检查~/.openclaw/workspace/memory/目录是否存在且可写。

问题：预算追踪显示为$0.00

• 修复方法： token_tracker.py需要与OpenClaw的session_status工具集成。目前仅追踪手动记录的使用情况。

问题：路由建议了错误的模型层级

• 修复方法：根据您的具体使用模式，在model_router.py中自定义ROUTING_RULES。

维护

每日：

• 检查预算状态：token_tracker.py check

每周：

• 审查路由准确性（建议是否正确？）
• 根据活动情况调整心跳间隔

每月：

• 比较优化前后的成本
• 审查并更新PROVIDERS.md新增选项

成本估算

示例：每日10万token的工作负载

无技能时：

• 5万上下文token + 5万对话token = 10万总计
• 全部使用Sonnet模型：10万 × $3/百万token =$0.30/天 = $9/月

策略	上下文	模型	每日成本	月度	节省
基准线（无优化）	50K	Sonnet	0.30美元	9.00美元	0%
仅上下文优化	10K (-80%)	Sonnet	0.18美元	5.40美元	40%
仅模型路由	50K	混合	0.18美元	5.40美元	40%
两者（此技能）	10K	混合	0.09美元	2.70美元	70%
激进优化 + Gemini	10K	Gemini	0.03美元	0.90美元	90%

核心洞察：上下文优化（从5万到1万词元）比模型路由节省更多成本！

xCloud 托管场景（100位客户，每位客户每天5万词元）：

• 基线（全部使用Sonnet模型，完整上下文）：每月450美元
• 使用词元优化器：每月135美元
• 节省：每100位客户每月节省315美元（70%）

资源

脚本（共4个）

• context_optimizer.py— 上下文加载优化与延迟加载（新增！）
• model_router.py— 任务分类、模型建议与通信执行（增强版！）
• heartbeat_optimizer.py— 间隔管理与检查调度
• token_tracker.py— 预算监控与警报

参考资料

• PROVIDERS.md— 替代AI服务商、定价及路由策略

资产（共3项）

• HEARTBEAT.template.md— 采用Haiku强化的即插即用优化心跳模板（增强版！）
• cronjob-model-guide.md— 定时任务模型选择完整指南（全新！）
• config-patches.json— 高级配置示例

未来增强功能

扩展此功能的构想：

1. 自动路由集成— 接入OpenClaw消息管道
2. 实时使用情况追踪— 自动解析session_status
3. 成本预测— 基于近期使用情况预测月度支出
4. 服务商健康度监控— 追踪API延迟与故障率
5. A/B测试— 对比不同路由策略的质量表现

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。