OpenClaw Token Optimizer

# Token Optimizer

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

## 快速开始

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

1. **生成优化的 AGENTS.md（最大的收益点！）：** ```bash python3 scripts/context_optimizer.py generate-agents # Creates AGENTS.md.optimized — review and replace your current AGENTS.md ```

2. **检查你实际需要的上下文：** ```bash python3 scripts/context_optimizer.py recommend "hi, how are you?" # Shows: Only 2 files needed (not 50+!) ```

3. **安装优化的心跳：** ```bash cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md ```

4. **强制在随意聊天中使用更便宜的模型：** ```bash 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. **检查当前的 token 预算：** ```bash python3 scripts/token_tracker.py check ```

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

## 核心功能

### 1. 上下文优化 (NEW!)

**最大的节省项** —— 仅加载你实际需要的文件，而不是提前加载所有内容。

**问题：** 默认的 OpenClaw 在每次会话中加载所有上下文文件： - SOUL.md, AGENTS.md, USER.md, TOOLS.md, MEMORY.md - docs/**/*.md（数百个文件） - memory/2026-*.md（每日日志） - 总计：通常在用户开口前就有 50K+ 的 token！

**解决方案：** 基于提示词复杂度的延迟加载。

**用法：** ```bash python3 scripts/context_optimizer.py recommend "<user prompt>" ```

**示例：** ```bash # 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 ```

**输出格式：** ```json { "complexity": "simple", "context_level": "minimal", "recommended_files": ["SOUL.md", "IDENTITY.md"], "file_count": 2, "savings_percent": 80, "skip_patterns": ["docs/**/*.md", "memory/20*.md"] } ```

**集成模式：** 在为新会话加载上下文之前： ```python 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：** ```bash context_optimizer.py generate-agents # Creates AGENTS.md.optimized with lazy loading instructions # Review and replace your current AGENTS.md ```

**预期节省：** 上下文 token 减少 50-80%。

### 2. 智能模型路由 (ENHANCED!)

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

**新增：通信模式强制** —— 永远不要在打招呼或感谢时浪费 Opus 的 token！

**用法：** ```bash python3 scripts/model_router.py "<user prompt>" [current_model] [force_tier] ```

**示例：** ```bash # 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）：**

*通信：* - 问候：hi, hey, hello, yo - 感谢：thanks, thank you, thx - 确认：ok, sure, got it, understood - 简短回复：yes, no, yep, nope - 单词或非常简短的短语

*后台任务：* - 心跳检查："check email", "monitor servers" - 定时任务："scheduled task", "periodic check", "reminder" - 文档解析："parse CSV", "extract data from log", "read JSON" - 日志扫描："scan error logs", "process logs"

**集成模式：** ```python 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"] ```

**自定义：** 编辑 `scripts/model_router.py` 中的 `ROUTING_RULES` 或 `COMMUNICATION_PATTERNS` 来调整模式和关键词。

### 3. 心跳优化

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

**设置：** ```bash # Copy template to workspace cp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md

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

**命令：** ```bash # 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`（节省 token）

**默认间隔：** - 邮件：60 分钟 - 日历：2 小时 - 天气：4 小时 - 社交：2 小时 - 监控：30 分钟

**集成到 HEARTBEAT.md：** ```markdown ## 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. 定时任务优化 (NEW!)

**问题：** 定时任务即使对于常规任务也经常默认使用昂贵的模型（Sonnet/Opus）。

**解决方案：** 对于 90% 的计划任务，始终指定 Haiku。

**参见：** `assets/cronjob-model-guide.md` 查看包含示例的综合指南。

**快速参考：**

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

**示例（好）：** ```bash # 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 ```

**示例（坏）：** ```bash # ❌ 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 集成：** ```bash # Test if your cronjob should use Haiku model_router.py "parse daily error logs" # → Output: Haiku (background task pattern detected) ```

### 5. Token 预算跟踪

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

**设置：** ```bash # 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 ```

**输出格式：** ```json { "date": "2026-02-06", "cost": 2.50, "tokens": 50000, "limit": 5.00, "percent_used": 50, "status": "ok", "alert": null } ```

**状态级别：** - `ok`：低于每日限制的 80% - `warning`：每日限制的 80-99% - `exceeded`：超过每日限制

**集成模式：** 在开始昂贵的操作之前，检查预算： ```python 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` 了解关于以下内容的综合指南： - 替代供应商 - 成本对比表 - 按任务复杂度的路由策略 - 限流场景的回退链 - API 密钥管理

**快速参考：**

| 供应商 | 模型 | 成本/百万Token | 用例 | |----------|-------|-----------|----------| | 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 | FREE | 开发/测试 | | Together | Llama 3.3 70B | $0.18 | 开源替代 |

## 配置补丁

参见 `assets/config-patches.json` 进行高级优化：

**由此技能实现：** - ✅ 心跳优化（功能完整） - ✅ Token 预算跟踪（功能完整） - ✅ 模型路由逻辑（功能完整）

**OpenClaw 2026.2.15 原生支持 —— 直接应用：** - ✅ 会话修剪 (`contextPruning: cache-ttl`) —— 在 Anthropic 缓存 TTL 过期后自动修剪旧的工具结果 - ✅ 引导大小限制 (`bootstrapMaxChars` / `bootstrapTotalMaxChars`) —— 限制工作区文件注入大小 - ✅ 长缓存保留 (`cacheRetention: "long"` for Opus) —— 摊销缓存写入成本

**需要 OpenClaw 核心支持：** - ⏳ 提示词缓存（Anthropic API 功能 —— 验证当前状态） - ⏳ 延迟上下文加载（今天使用 `context_optimizer.py` 脚本） - ⏳ 多供应商回退（部分支持）

**应用配置补丁：** ```bash # 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）。心跳使缓存保持热状态，因此每个后续请求支付缓存读取费率。

```bash # 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 配置：** ```json { "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%

## 集成示例

### 工作流：智能任务处理 ```bash # 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) ```

### 工作流：优化的心跳 ```markdown ## 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 ```

## 故障排除

**问题：** 脚本失败并提示 "module not found" - **修复：** 确保已安装 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`

## 成本估算

**示例：100K tokens/天 工作负载**

不使用此技能： - 50K 上下文 token + 50K 对话 token = 100K 总计 - 全部 Sonnet：100K × $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%** |

**核心洞察：** 上下文优化（50K → 10K tokens）节省的成本比模型路由更多！

**xCloud 托管场景**（100 个客户，50K tokens/客户/天）： - 基准（全部使用 Sonnet，完整上下文）：$450/月 - 使用 token 优化器：$135/月 - **节省：每 100 个客户每月 $315（70%）**

## 资源

### 脚本（共 4 个） - **`context_optimizer.py`** — 上下文加载优化和懒加载（新增！） - **`model_router.py`** — 任务分类、模型建议和通信强制执行（增强！） - **`heartbeat_optimizer.py`** — 间隔管理和检查调度 - **`token_tracker.py`** — 预算监控和警报

### 参考资料 - `PROVIDERS.md` — 备选 AI 提供商、定价和路由策略

### 资产（共 3 个） - **`HEARTBEAT.template.md`** — 即插即用的优化版 heartbeat 模板，强制使用 Haiku（增强！） - **`cronjob-model-guide.md`** — 在 cronjobs 中选择模型的完整指南（新增！） - **`config-patches.json`** — 高级配置示例

## 未来增强

扩展此技能的想法： 1. **自动路由集成** — 接入 OpenClaw 消息管道 2. **实时使用情况跟踪** — 自动解析 session_status 3. **成本预测** — 根据近期使用情况预测月度支出 4. **提供商健康监控** — 跟踪 API 延迟和故障 5. **A/B 测试** — 比较不同路由策略下的质量