token-optimizer#

将会话输入 token 从 10万+ 压缩至 8,000 以内的完整解决方案。 三层索引 + 会话摘要压缩 + 任务隔离，开箱即用，自动使用 OpenClaw AI 配置。

---

核心原理#

text

输入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）#

bash

claw install token-optimizer

2. 无需配置！#

自动使用 OpenClaw 的 AI 配置，开箱即用 🎉

3. 初始化记忆目录#

bash

cd ~/.openclaw/workspace/skills/token-optimizer
python3 scripts/new_session.py init

重要： 记忆文件存储在 ~/.openclaw/memory/（OpenClaw全局记忆目录），不在技能目录内。

4. 每次新会话开始时#

text

加载顺序（严格按此顺序，总计<8000 token）：
① INDEX.md          （本技能的索引，<1KB，必读）
② latest-summary.md （上次会话压缩摘要，<2KB）
③ 任务专属记忆       （按TaskID按需加载，<1KB）
④ 近5轮对话         （滑动窗口，不加载更早历史）

4. 会话结束时压缩#

bash

# 预览压缩效果（不保存）
python3 scripts/compress_session.py --dry-run

# 实际压缩并保存
python3 scripts/compress_session.py

---

三层索引体系#

层1：任务层（TaskID）#

text

格式：{类型}-{日期}-{序号}
示例：STOCK-20260227-001 / DEPLOY-20260227-002

TaskID前缀场景加载记忆STOCK-*股票/行情/交易stock.mdDEPLOY-*部署/安装/运维ops.mdCODE-*编写/修改代码无QUERY-*一次性查询无REMIND-*定时提醒无

层2：记忆层（按需加载）#

text

~/.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 轮自动压缩 + 提示用户新开会话

使用方式：

bash

# 每次对话前调用
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.mdscripts/new_session.py初始化新会话，输出本次应加载的记忆清单scripts/status.py显示当前token使用估算和记忆文件大小

---

集成到 OpenClaw Agent#

在你的 Agent 中集成：

python

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 配置，但你也可以通过环境变量自定义：

bash

# 自定义阈值
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,0008,00092%中等会话（20轮）40,0006,00085%新会话5,0004,00020%

---

为什么选择 token-optimizer？#

✅ 开箱即用 - 自动使用 OpenClaw AI 配置，无需额外配置

✅ 智能判断 - 自动检测何时需要压缩或新开会话

✅ 任务隔离 - 避免不同任务的上下文污染

✅ 高效压缩 - 92% token 节省，显著降低成本

✅ 易于集成 - 简单的 Python 脚本，易于集成到任何 Agent

---

许可证#

MIT License - 详见 LICENSE

---

贡献#

欢迎贡献！请访问 GitHub