token-pilot

name	token-pilot
description	Automatic token optimization during interaction. Behavioral rules + plugin synergy + workspace analyzer. Pure Node.js, cross-platform. Activate on session start (rules auto-apply) or when user asks about token usage/cost/audit.
version	2.5.0
author	beyou

Token Pilot

🚀 首次加载行动（Agent 必读）

当你第一次加载此技能时（新 session 或刚安装），主动执行以下操作：

1. 检查是否已跑过初始诊断：查看 workspace 下有无 token-pilot-audit.log 文件

   • 有 → 跳过，直接应用规则
   • 没有 → 说明从未跑过诊断，主动告知用户：

     "检测到 token-pilot 首次加载，建议运行一次诊断扫描。我来帮你跑：node C:\Users\Administrator\.openclaw\skills\token-pilot\scripts\audit.js --all"

2. 触发时机：用户说"开始工作"、"帮我做 XX"等开启对话时，如果检测到首次加载，在正式回复前先提示诊断，不要默默跳过

3. Heartbeat cron 自动维护（可选配置，降低长期维护成本）： 如果用户 openclaw.json 中有 cron 配置，建议添加一条每周一次的优化扫描：

   {
     "kind": "agentTurn",
     "schedule": "0 9 * * 1",
     "message": "运行 token-pilot 周度诊断：node C:\\Users\\Administrator\\.openclaw\\skills\\token-pilot\\scripts\\optimize.js --cron。输出建议但不自动修改配置，把结果摘要告诉我。",
     "lightContext": true,
     "model": "Qwen/Qwen3-8B"
   }
   

   这条 cron 会每周一早 9 点跑一次诊断，用轻量模型，不占主会话 token。

---

Auto-Apply Rules

These 6 rules apply every session automatically. No scripts needed.

R1: Smart Read

read(path, limit=30) first. Full read only for files known <2KB. Use offset+limit for surgical reads. Never blind-read >50 lines. Exception: When building ACP context files (coding-lead), read project standards files fully — incomplete context causes ACP failures that waste more tokens than the initial read.

R2: Tool Result Compression

Tool result >500 chars → extract relevant portion only. Summarize, don't echo.

R3: Response Brevity

Query	Length
Yes/No, simple factual	1-3 lines
How-to	5-15 lines
Analysis	As needed

"Done." is a valid reply. Never pad short answers.

R4: No Repeat Reads

Never re-read a file unless modified since last read or explicitly asked.

R5: Batch Tool Calls

Independent calls → one block. read(A) + read(B) + read(C) not three round-trips.

R6: Output Economy

• edit over write when <30% changes
• Show changed lines + 2 context, not full files
• Filter exec output before dumping

R7: Role-Aware Tool Economy

Infer role weight from SOUL.md at session start. No hardcoded role names — works on any team.

Step 1 — Classify self: Read own SOUL.md (if present). Look for keywords:

• 🔴 Heavy role signals: browser, deploy, code, engineer, screenshot, automation, database, full-stack
• 🟡 Medium role signals: product, data, analytics, growth, campaign
• 🟢 Light role signals: research, intel, content, write, report, summarize, search

Step 2 — Apply defaults by weight:

Weight	Default behavior
🔴 Heavy	All tools available, use freely
🟡 Medium	Avoid browser/canvas/tts unless task needs it
🟢 Light	Avoid browser/canvas/tts/sessions_spawn/feishu_bitable unless task needs it

Step 3 — Override always wins: If user explicitly requests it, task clearly requires it, or it's the only available solution → use freely, no need to explain or ask permission.

Fallback: No SOUL.md found → treat as Heavy, all tools available. Never block work due to missing context.

R8: Prompt Cache Awareness

Claude/Anthropic 支持 prompt caching：system prompt 中不变的内容放最前面，变化的内容（用户消息、动态上下文）放后面。缓存命中后 input token 费用降 75%。

实践要点：

• SOUL.md / AGENTS.md / 固定规则 → 优先放 system prompt 最前部分，内容保持稳定
• 动态注入的内容（memory_search 结果、工具输出）→ 放后面，每次不同不影响前面的缓存
• 不要在固定内容里加时间戳、session id 等每次变化的字段，会破坏缓存
• 高频固定事实（用户名、项目代号、常用配置）写进 MEMORY.md 顶部或 SOUL.md 固定位置，不靠语义搜索命中 — 每次 memory_search 注入不同结果会导致 prompt 每轮都变，cache 完全失效
• AGENTS.md 内容拆分：把频繁变动的内容（进行中事项、当前任务状态）移出 AGENTS.md，改为 read(memory/YYYY-MM-DD.md) 按需加载；AGENTS.md 本身只保留稳定的工作规范。来源：Claude Code claudemd.ts 支持按 glob 条件加载 .claude/rules/*.md，证明了"规范与状态分离"的设计价值
• heartbeat every: "55m" 的真实作用：Anthropic cache TTL 是 1h，心跳间隔略小于 TTL，可以在 session 空闲时保持缓存不过期，避免重新 cache write 的额外费用
• per-agent cache 策略：通知/告警类 bursty agent 设 cacheRetention: "none" 避免无意义 cache write；深度工作 agent 设 cacheRetention: "long" 最大化复用

R9: Non-Human Output Compression

Cron 任务、agent-to-agent 消息、自动化流水线中，接收方是机器不是人：

• 不输出装饰性 markdown（表格 header、emoji、分隔线 ---）
• 直接输出结构化数据或纯文本摘要
• 每个 output token 都应有信息量，去掉仅供人阅读的格式开销

判断标准：消息的下一个接收者是人 → 正常格式；是 agent / cron 回调 / 脚本 → 压缩格式。

R10: Dynamic Content Size Cap（动态内容大小上限）

任何动态注入到 context 的内容（工具输出、搜索结果、外部文件）必须按类型分级限制，防止上下文无限膨胀。

来源：Claude Code context.ts 对 git status 设置了 MAX_STATUS_CHARS = 2000 截断并提示"如需完整信息请用 BashTool"——核心思路是上下文只放摘要，完整信息按需工具获取。

分级限制（按内容类型）：

内容类型	建议上限	超出时处理
命令/exec 输出	2000 字符	截取关键部分 + "...（如需完整请...）"
单个工具返回	3000-5000 字符	提取相关部分，丢弃无关行
单个知识文件	10KB	超过用概览版（db-overview.md 而非 db-tables.md）
memory_search 结果	≤ 6 条	已通过 maxResults 配置限制
动态内容总比例	< 30% of context	相对比例比绝对字符数更重要

核心原则： 动态内容越多，固定内容（SOUL/AGENTS/规范）的 prompt cache 命中率越低。宁可截断 + 提示"需要时工具获取"，不要一次性全塞。

其他规则：

• 知识文件加载每次 ≤ 3 个，先读 INDEX.md 判断需要哪些
• 大文件（>10KB）分级读取：先概览，按需深入

---

Plugin Synergy (auto-detect, graceful fallback)

[qmd] Search Before Read

qmd/memory_search("keyword") → exact file+line → read(offset, limit). Fallback: grep / Select-String with targeted patterns.

[smart-agent-memory] Avoid Re-Discovering

memory recall "topic" before investigating → skip if already solved. After solving: memory learn to prevent re-investigation. Fallback: memory_search + MEMORY.md files.

[memory] Read File vs Search

When you need information from memory:

• To analyze/summarize → memory_search("keyword") first → get exact chunk → read(offset, limit) only if needed
• To edit a file → full read is correct (edit needs content in context)
• Never re-read MEMORY.md or daily notes just to "check if you know something" — search first, read only on miss

[memory] MEMORY.md 索引结构规范（来源：Claude Code memdir.ts）

MEMORY.md 应保持索引结构，不直接存放大段内容：

• 每行一条指针：- [标题](memory/topics/file.md) — 一行摘要（<150字符）
• 详细内容放 memory/topics/ 下的 topic 文件，MEMORY.md 只存索引
• 硬上限参考：200行 / 25KB（来源：Claude Code MAX_ENTRYPOINT_LINES=200, MAX_ENTRYPOINT_BYTES=25000）
• 超出上限后会截断，重要内容塞不进去，越早维护索引结构越好
• MEMORY.md 常驻 context，越小越好；topic 文件按需 read，不常驻

[memory] 记忆四分类（来源：Claude Code memoryTypes.ts）

保存记忆时按类型分类，避免只记纠正、忽略成功经验：

类型	内容	注意
user	用户角色/偏好/知识水平	USER.md 对应
feedback	纠正 + 确认成功的方案	⚠️ 确认成功也要记，不只记错误
project	进行中工作/目标/截止日期	日期用绝对值，不用"下周四"
reference	外部系统指针（URL/路径/系统名）	减少每次靠搜索查链接的开销

feedback 类最容易被忽视： 用户说"对，就这样"、"挺好的"时，也要记——只记纠正会让 agent 越来越保守，丢失已经验证成功的方案。

[skills] Solidify Repeating Tasks

If the same investigation/reasoning pattern occurs 2+ times → convert to a Skill. Repeating manually costs O(n) tokens each time; a Skill costs O(1) after creation. Use skill_get before any multi-step task to check if a proven guide already exists. After completing a novel complex task → proactively suggest creating a Skill to capture the pattern.

[coding-lead] Context File Pattern

Write context to disk → lean ACP prompt ("Read .openclaw/context.md") → significant savings vs embedding. Prefer disk context files for large context, but include essential info (project path, stack, key constraint) directly in spawn prompt (~200-500 chars) so ACP agent can bootstrap even if context file is missing.

ACP model awareness: claude-code (complex) → codex (quick) → direct exec (simple <60 lines).

[multi-search-engine] Search Economy

Simple: web_search 3 results. Research: 5 results, web_fetch best one only. Fallback: web_search → web_fetch (tavily 已废弃，不要配置).

[multi-agent teams] Team Awareness

When you detect a multi-agent collaboration structure — for example shared inboxes, a dashboard, shared product knowledge, role-specific SOUL files, or recurring dispatch patterns — apply these defaults:

• Light cron or patrol tasks: lightContext + cheapest viable model
• Cron prompts <300 chars; move methodology into references or stable shared files
• Agent SOUL.md stays lean; detailed procedures belong in references/ or shared workflow files
• Read minimal coordination files first, then task-specific files; avoid reloading whole team docs every turn

[multi-agent dispatch] Spawn Token Economy

• sessions_spawn(runtime="subagent") for standard agents — never include streamTo (causes immediate error, wastes a round-trip)
• sessions_spawn(runtime="acp") only for ACP-configured agents (agents with runtime.type: "acp" in config) — may include streamTo="parent"
• Results arrive via auto-announce; do not poll with sessions_list or subagents list in a loop
• Keep spawn task descriptions lean (<500 chars) — the child agent has its own SOUL.md and context

[tools.allow] 工具白名单是最高性价比的配置优化

当前所有 agent 都是 tools.allow: ["*"]，意味着每个 agent 每次对话都加载全量工具定义（约 4,000–8,000 tok 额外开销）。

操作建议：

1. 先跑 optimize.js --agents 看分层建议
2. 按角色类型设置白名单（参考 Validated Config Patterns 章节的角色白名单表）
3. 从工具最少的轻量 agent（qa/coder）开始改，风险最小

这是一次性配置，长期受益，团队 7 个 agent 全部设好后，预计每天省 3–5 万 tok。

---

新发现：来自 Claude Code 源码（v2.5.0 新增）

A. Autocompact 熔断：cron/subagent 失败不能无限重试（来源：autoCompact.ts）

// Stop trying autocompact after this many consecutive failures.
// 1,279 sessions had 50+ consecutive failures, wasting ~250K API calls/day globally.
MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

规则：cron job / subagent 任务失败后最多重试 3 次，超出后停止并告警。 无限重试"卡住的任务"是 token 浪费最严重的场景之一。

实践：

• Heartbeat cron 任务加 maxRetries: 3 或等价逻辑
• Subagent 卡死超过 5 分钟 → 主动 kill，记录失败，不无脑等

B. Compaction 提前缓冲 13K token（来源：autoCompact.ts）

AUTOCOMPACT_BUFFER_TOKENS = 13_000   // 提前触发压缩的缓冲
WARNING_THRESHOLD_BUFFER_TOKENS = 20_000  // 预警缓冲

Claude Code 不是"满了再压"，而是离上限还有 13,000 token 时就触发 compaction。

当前配置 softThresholdTokens: 4000 偏激进，长对话里一次复杂工具调用就能跨越这 4K 缓冲，导致 memoryFlush 触发太晚。建议调整：

"compaction": {
  "mode": "safeguard",
  "memoryFlush": {
    "enabled": true,
    "softThresholdTokens": 8000
  }
}

C. Compaction 后 token 范围：10K-40K 才是正常区间（来源：sessionMemoryCompact.ts）

DEFAULT_SM_COMPACT_CONFIG = {
  minTokens: 10_000,    // 少于此值 = 压过头，context 流失
  maxTokens: 40_000,    // 超过此值 = 没压到位
}

压缩后不是越小越好，低于 10K token 说明重要对话历史被裁掉了。

实践： 压缩后用 /status 检查当前 token，应在 10K-40K 之间。超出或不足都需要调整压缩配置。

D. Cache Write 比普通 Input 贵 25%（来源：modelCost.ts）

// claude-sonnet-4-6 实际价格
inputTokens: 3,              // $3/Mtok 普通 input
promptCacheWriteTokens: 3.75, // $3.75/Mtok（贵 25%！）
promptCacheReadTokens: 0.3,   // $0.3/Mtok（便宜 90%）

只有同一 prompt 被读取 2+ 次，cache 才合算。第一次 write 付出 25% 溢价，从第二次 read 才开始回本。

推论： bursty/通知类 agent（每次系统提示不同）开 cache 纯亏损：

// 通知/告警类 agent 配置
{ "id": "alerts", "params": { "cacheRetention": "none" } }

稳定 agent（main/architect）保持 "long"：每次 read 只需 write 价格的 8%。

E. Subagent"边际递减"检测：连续 3 轮不足 500 token 增量就停（来源：tokenBudget.ts）

DIMINISHING_THRESHOLD = 500
// 连续 3 轮 token 增量 < 500 → isDiminishing = true → stop

Claude Code 检测"原地转圈"：连续 3 轮产出极少但在消耗 token，说明 agent 已卡死，自动停止。

实践（多 agent 协作时）：

• 给 subagent 设任务时，说明最大 token 预算（如"200K token 内完成"）
• 主 agent 收到 subagent 回报时检查：输出是否实质性增加，还是在重复废话
• 卡死信号：超时无回复、反复重读同一文件、同样的工具调用重复 3+ 次 → 主动 kill

---

Config Change Safety Rules（改配置铁律）

这三条是本次实测中踩坑总结出的，每次修改 openclaw.json 前必须遵守。

R-C1：改配置前先查 schema

gateway config.schema.lookup <path>

字段是否存在、类型、允许值，查完再写。不查盲写=必踩坑。

R-C2：注意字段层级，不要写到顶层

• compaction、bootstrapMaxChars、bootstrapTotalMaxChars 等字段在 agents.defaults 下
• 写到顶层会通过 config 校验报错，导致整个 openclaw 启动失败

R-C3：不盲信第三方技能的"推荐配置" 第三方技能 SKILL.md / README 里写的"推荐 openclaw.json 配置"不等于平台真实支持。 每个字段都要用 config.schema.lookup 验证后再写入。

---

Setup / Config / Scripts

Setup

无需初始化。安装后规则自动生效。

openclaw.json 配置说明

安装此技能无需修改 openclaw.json，行为规则自动生效。

注：heartbeat 如需配置可写入 openclaw.json： "heartbeat": { "every": "55m", "activeHours": { "start": "08:00", "end": "23:00" } }

Recommended tools.allow by role (示例，按实际角色调整)

• 重型角色（实现/交付类）：read/write/edit/exec/web_search/web_fetch/browser/sessions_spawn/memory_*/message
• 中型角色（产品/数据类）：read/write/edit/exec/web_search/feishu_doc/feishu_bitable/feishu_wiki/memory_*/message
• 轻型角色（内容/情报/增长类）：按职责裁剪，尽量不要 [*]

Scripts

# Audit (read-only diagnostics)
node {baseDir}/scripts/audit.js --all             # Full audit
node {baseDir}/scripts/audit.js --config          # Config score (5-point)
node {baseDir}/scripts/audit.js --synergy         # Plugin synergy check

# Optimize (actionable recommendations)
node {baseDir}/scripts/optimize.js                # Full scan: workspace + cron + agents
node {baseDir}/scripts/optimize.js --apply        # Auto-fix workspace (cleanup junk, delete BOOTSTRAP.md)
node {baseDir}/scripts/optimize.js --cron         # Cron model routing + lightContext + prompt compression
node {baseDir}/scripts/optimize.js --agents       # Agent model tiering recommendations
node {baseDir}/scripts/optimize.js --template     # Show optimized AGENTS.md template (~300 tok)

# Catalog
node {baseDir}/scripts/catalog.js [--output path] # Generate SKILLS.md index

Config Recommendations

{
  "bootstrapMaxChars": 12000,
  "bootstrapTotalMaxChars": 20000,
  "compaction": {
    "mode": "safeguard",
    "memoryFlush": { "enabled": true }
  },
  "contextPruning": {
    "toolResults": { "ttl": "5m", "softTrimRatio": 0.3 }
  },
  "heartbeat": { "every": "55m", "activeHours": { "start": "08:00", "end": "23:00"  

memoryFlush（新增）

Compaction 压缩长会话之前，自动把关键信息持久化到本地记忆（smart-agent-memory）。 防止重要决策/信息被 compaction 丢掉。配合 memos-local 插件效果最佳。

contextPruning TTL（新增）

工具调用结果在 context 里保留 5 分钟后自动软裁剪（保留摘要，丢弃原始输出）。 长会话中工具结果积累是 context 膨胀的主要原因之一。

工具白名单（新增）

在 openclaw.json 的各 agent tools.allow 里设置精确白名单，而非 ["*"]。 按角色类型建议（示例，实际角色名按团队调整）：

角色类型	核心工具	可以不要
情报/搜索类	web_search/web_fetch/read/write/edit/exec/memory_*/message	browser/canvas/tts/feishu_bitable/sessions_spawn
数据分析类	read/write/edit/exec/web_search/feishu_bitable/memory_*/message	browser/canvas/tts/feishu_wiki
内容创作类	read/write/edit/exec/web_search/web_fetch/feishu_doc/feishu_wiki/memory_*/message	browser/canvas/tts/feishu_bitable
增长/营销类	read/write/edit/exec/web_search/web_fetch/feishu_doc/feishu_bitable/memory_*/message	browser/canvas/tts/feishu_wiki
产品管理类	read/write/edit/exec/web_search/feishu_doc/feishu_bitable/feishu_wiki/memory_*/message	browser/canvas/tts
交付/运维类	read/write/edit/exec/web_search/web_fetch/browser/sessions_spawn/memory_*/message	canvas/tts/feishu_bitable
实现/开发类	read/write/edit/exec/web_search/web_fetch/browser/sessions_spawn/memory_*/message	canvas/tts/feishu_bitable
预计节省：每个受限 agent 减少 ~4,000-8,000 tok 工具定义开销。

Cron Job 专项优化（lightContext）

OpenClaw 官方支持：agentTurn 类型的 cron job 可以设 lightContext: true，跑轻量 bootstrap context，大幅减少每次定时任务的冷启动 token 开销。

适用场景：消费日报、状态巡检、定时提醒等不需要完整历史上下文的 cron 任务。

配置方式（编辑 cron job payload）：

{
  "kind": "agentTurn",
  "message": "执行消费日报任务",
  "lightContext": true,
  "model": "Qwen/Qwen3-8B"
}

配合建议：

• lightContext: true + 便宜模型（如 Qwen3-8B）组合使用
• Cron prompt 控制在 300 字以内，方法论写到 references 文件里
• 运行 optimize.js --cron 可以批量扫描哪些 job 还没设置 lightContext

Model Routing

Complexity	Model Tier	Examples
Light	Cheapest (gemini/haiku)	inbox scan, status check
Medium	Mid (gpt/sonnet)	web search, content
Heavy	Top (opus)	architecture, briefs

References

• references/workspace-patterns.md — File organization for minimal token cost
• references/cron-optimization.md — Cron model routing guide

Validated Config Patterns (经实测可用)

以下配置来自真实部署验证，非推测。可直接写入 openclaw.json。

agents.defaults.compaction（长会话稳定性）

"agents": {
  "defaults": {
    "compaction": {
      "mode": "safeguard",
      "memoryFlush": {
        "enabled": true,
        "softThresholdTokens": 8000
      }
    }
  }
}

• safeguard：压缩时优先保留近期上下文，减少重要信息丢失
• memoryFlush：距压缩还剩 8000 token 时，自动触发记忆持久化，防止 compaction 丢掉关键决策（来源：Claude Code autoCompact.ts AUTOCOMPACT_BUFFER_TOKENS=13000，4000 缓冲偏小）

agents.defaults.bootstrapMaxChars / bootstrapTotalMaxChars

"agents": {
  "defaults": {
    "bootstrapMaxChars": 12000,
    "bootstrapTotalMaxChars": 20000
  }
}

限制启动时注入的 bootstrap 文件大小，防止 AGENTS.md / MEMORY.md 等文件无限膨胀导致冷启动 token 暴涨。

⚠️ 以上字段放在 agents.defaults 下，不是顶层。顶层写入会导致 config 校验报错。

AGENTS.md 精简原则

• 目标：每个子 agent 的 AGENTS.md 控制在 400 tok 以内
• 只保留：启动规则、记忆规则、安全规则、平台格式化
• 删除：context-mode 使用说明（系统自动注入，写在 AGENTS.md 里是纯重复）、群聊规则、voice storytelling 等无关内容
• 主 workspace 的 AGENTS.md 是维护文档，允许更大，但子 agent workspace 要严格精简

Workspace 根目录文件组织（隐藏的 token 杀手）

workspace 根目录每多一个文件 = 每次对话多一条 bootstrap 注入。

铁律：脚本类文件不要放根目录

文件类型	放哪里
*.js / *.py / *.ps1 脚本	scripts/ 子目录
参考文档、知识文件	docs/ 或 knowledge/ 子目录
临时数据、dump 文件	tmp/ 或 data/ 子目录
AGENTS.md / MEMORY.md / SOUL.md	根目录（必须）

实测：根目录 14 个脚本文件 ≈ 29,500 tok/session 的额外注入开销。 清理后立竿见影，是单次优化收益最大的操作之一。

运行 optimize.js --apply 可自动将根目录脚本移到 scripts/ 子目录。

图片/截图 token 控制

screenshot 或图片工具调用在视觉重度 session 中会大量消耗 token。

"agents": {
  "defaults": {
    "imageMaxDimensionPx": 800
  }
}

• 默认值 1200，降到 800 可减少视觉 token 和 payload 大小
• OCR/UI 截图分析需要高精度时保留 1200 或更高
• 不涉及图片的 agent（如 pm/qa/coder 纯文本工作）可以设成 600 甚至更低

Skill 描述精简（常被忽视的开销）

OpenClaw 系统 prompt 里会注入全部已安装 Skill 的 metadata（名称 + 描述）。 安装的 skill 越多、描述越长，每次对话冷启动开销越大。

优化建议：

• Skill description 控制在 50 字以内，只说"什么场景用"，不写使用步骤
• 不用的 skill 及时卸载（openclaw skills uninstall <skill-name>）
• 用 /context detail 查看当前 skill list 占了多少 token

实时诊断命令（随时可用）

# 查当前 session token 用量 + 模型 + 预估费用
/status

# 每条回复后显示 token 用量
/usage tokens

# 查看 context 分解（各文件/工具/skill 各占多少）
/context list
/context detail

# 手动触发 session 压缩
/compact