token-optimizer
将会话输入 token 从 10万+ 压缩至 8,000 以内的完整解决方案。
三层索引 + 会话摘要压缩 + 任务隔离，开箱即用，自动使用 OpenClaw AI 配置。
核心原理
输入token来源分析：
系统提示 ~2,000 （固定，不可压缩）
会话历史 ~90,000 ← 主要元凶
记忆文件 ~5,000 ← 可优化
当前消息 ~500 （正常）
优化后：
系统提示 ~2,000
latest-summary ~1,500 ← 替代完整历史
任务记忆 ~1,000 ← 按需加载
近5轮对话 ~3,000 ← 滑动窗口
当前消息 ~500
─────────────────
总计 ~8,000 ✅ 压缩92%
快速开始
1. 安装（从 ClawHub）
claw install token-optimizer
2. 无需配置！
自动使用 OpenClaw 的 AI 配置，开箱即用 🎉
3. 初始化记忆目录
cd ~/.openclaw/workspace/skills/token-optimizer
python3 scripts/new_session.py init
重要： 记忆文件存储在 ~/.openclaw/memory/（OpenClaw全局记忆目录），不在技能目录内。
4. 每次新会话开始时
加载顺序（严格按此顺序，总计<8000 token）：
① INDEX.md （本技能的索引，<1KB，必读）
② latest-summary.md （上次会话压缩摘要，<2KB）
③ 任务专属记忆 （按TaskID按需加载，<1KB）
④ 近5轮对话 （滑动窗口，不加载更早历史）
4. 会话结束时压缩
# 预览压缩效果（不保存）
python3 scripts/compress_session.py --dry-run
# 实际压缩并保存
python3 scripts/compress_session.py
三层索引体系
层1：任务层（TaskID）
格式：{类型}-{日期}-{序号}
示例：STOCK-20260227-001 / DEPLOY-20260227-002
| TaskID前缀 | 场景 | 加载记忆 |
|---|
| STOCK-* | 股票/行情/交易 | stock.md |
| DEPLOY-* | 部署/安装/运维 | ops.md |
| CODE-* | 编写/修改代码 | 无 |
| QUERY-* | 一次性查询 | 无 |
| REMIND-* | 定时提醒 | 无 |
层2：记忆层（按需加载）
~/.openclaw/memory/ # OpenClaw 全局记忆目录
├── index/
│ ├── INDEX.md # 必读，<1KB
│ └── RULES.md # 规则详情
├── sessions/
│ ├── latest-summary.md # 最新压缩摘要，替代完整历史
│ ├── SESSION-RULES.md # 会话规范
│ └── {日期}-summary.md # 历史归档
└── {domain}/ # 领域专属记忆（stock/ops等）
└── {domain}.md
注意： 记忆文件存储在 ~/.openclaw/memory/，不在技能目录内。详见 MEMORY_STRUCTURE.md
层3：内容层（关键词匹配）
匹配度 ≥ 0.8 才纳入上下文：
- 股票/行情/持仓/止损 → 加载 stock.md
- 部署/安装/报错/systemd → 加载 ops.md
- 天气/新闻/彩票 → 仅加载 INDEX.md
压缩规则
保留（必须）
- 关键配置参数（API地址、路径、密钥前缀）
- 已验证的解决方案
- 错误教训（避免重复踩坑）
- 服务状态和部署路径
删除（必须）
- 过程性对话和重复确认
- 调试输出和临时日志
- 格式说明和冗余解释
- 已完成的中间步骤
压缩目标
- 单次压缩率 ≥ 60%
- latest-summary.md ≤ 2KB（约1500 token）
自动触发机制
session_guard.py 会在每次对话时自动检查 token 使用情况：
| 条件 | 触发动作 |
|---|
| 上下文 < 4万 token | 正常，无操作 |
| 上下文 4~7万 token | 自动压缩，静默执行 |
| 上下文 > 7万 token | 自动压缩 + 提示用户新开会话 |
| 会话轮数 > 25 轮 | 自动压缩 + 提示用户新开会话 |
使用方式：
# 每次对话前调用
python3 scripts/session_guard.py check \
--message "用户消息" \
--context-size 当前token数
# 新会话开始后重置状态
python3 scripts/session_guard.py reset
Agent 会自动执行压缩，无需用户手动干预 ✅
脚本说明
| 脚本 | 功能 |
|---|
scripts/session_guard.py | ⭐ 核心：自动判断是否需要压缩/新开会话 |
scripts/compress_session.py | 压缩当前会话摘要，更新 latest-summary.md |
scripts/new_session.py | 初始化新会话，输出本次应加载的记忆清单 |
scripts/status.py | 显示当前token使用估算和记忆文件大小 |
集成到 OpenClaw Agent
在你的 Agent 中集成：
import subprocess
import json
def check_session_health(user_message: str, context_size: int):
"""检查会话健康度"""
result = subprocess.run(
['python3', 'scripts/session_guard.py', 'check',
'--message', user_message,
'--context-size', str(context_size)],
capture_output=True,
text=True,
cwd='~/.openclaw/workspace/skills/token-optimizer'
)
# 解析输出
if 'compress' in result.stdout.lower():
# 执行压缩
subprocess.run(
['python3', 'scripts/compress_session.py'],
cwd='~/.openclaw/workspace/skills/token-optimizer'
)
return 'compressed'
elif 'new_session' in result.stdout.lower():
return 'new_session_needed'
else:
return 'continue'
# 在每次对话前调用
action = check_session_health(user_message, current_token_count)
if action == 'new_session_needed':
print("💡 建议新开会话以获得最佳体验")
高级配置（可选）
虽然默认使用 OpenClaw 配置，但你也可以通过环境变量自定义：
# 自定义阈值
export TOKEN_OPTIMIZER_WARN_TOKENS="40000"
export TOKEN_OPTIMIZER_CRITICAL_TOKENS="70000"
export TOKEN_OPTIMIZER_MAX_ROUNDS="25"
# 自定义任务关键词
export TOKEN_OPTIMIZER_TASK_KEYWORDS='{"MYTASK": ["关键词1", "关键词2"]}'
# 覆盖 AI 配置（高级用户）
export TOKEN_OPTIMIZER_API_KEY="your-key"
export TOKEN_OPTIMIZER_MODEL="gpt-4"
Token节省效果
| 场景 | 优化前 | 优化后 | 节省 |
|---|
| 长会话（50轮） | ~100,000 | ~8,000 | 92% |
| 中等会话（20轮） | ~40,000 | ~6,000 | 85% |
| 新会话 | ~5,000 | ~4,000 | 20% |
为什么选择 token-optimizer？
✅ 开箱即用 - 自动使用 OpenClaw AI 配置，无需额外配置
✅ 智能判断 - 自动检测何时需要压缩或新开会话
✅ 任务隔离 - 避免不同任务的上下文污染
✅ 高效压缩 - 92% token 节省，显著降低成本
✅ 易于集成 - 简单的 Python 脚本，易于集成到任何 Agent
许可证
MIT License - 详见 LICENSE
贡献
欢迎贡献！请访问 GitHub
