Token Pilot

v3.7.0

Automatic token optimization during interaction. Behavioral rules + plugin synergy + workspace analyzer. Pure Node.js, cross-platform. Activate on session st...

⭐ 0· 600·3 current·3 all-time

by@beyound87

OpenClaw Prompt Flow

Install with OpenClaw

Best for remote or guided setup. Copy the exact prompt, then paste it into OpenClaw for beyound87/token-pilot.

Previewing Install & Setup.

Prompt PreviewInstall & Setup

Install the skill "Token Pilot" (beyound87/token-pilot) from ClawHub.
Skill page: https://clawhub.ai/beyound87/token-pilot
Keep the work scoped to this skill only.
After install, inspect the skill metadata and help me finish setup.
Use only the metadata you can verify from ClawHub; do not invent missing requirements.
Ask before making any broader environment changes.

Command Line

CLI Commands

Use the direct CLI path if you want to install manually and keep every step visible.

OpenClaw CLI

Canonical install target

openclaw skills install beyound87/token-pilot

ClawHub CLI

Package manager switcher

npx clawhub@latest install token-pilot

Security Scan

VirusTotal

Benign

View report →

OpenClaw

Suspicious

medium confidence

ℹ

Purpose & Capability

The skill claims 'Pure Node.js' and cross-platform behavior and its scripts clearly operate on ~/.openclaw, agents' AGENTS.md, openclaw.json and cron jobs — this is coherent with a 'token optimization across workspace/agents' purpose. However the package metadata is inconsistent (SKILL.md frontmatter version 3.6.0, registry version 3.7.0, _meta.json version 2.0.6) and the skill does not declare Node.js or node/npm as a required binary even though its runtime scripts (audit.js/optimize.js/catalog.js) require node. Those omissions are sloppy and make the package harder to reason about.

Instruction Scope

SKILL.md and scripts instruct the agent (and user) to read many files under the user's home (~/.openclaw/*), scan all agents, and inject a 36-line rule block into every agent's AGENTS.md (creating AGENTS.md where missing). The audit/optimize scripts also examine openclaw.json and cron/jobs.json and optimize.js supports a --apply mode that moves/deletes files (e.g., moves 'junk' into scripts/, deletes BOOTSTRAP.md). Those actions are within the stated goal (global token-cost rules), but they are wide-reaching and persistent — you should not run init.sh or optimize.js --apply without review and backing up affected files. The SKILL.md instructs prompting the user before injection, but the init.sh supports --yes to skip confirmation (automation risk).

ℹ

Install Mechanism

No install spec is declared (instruction-only in registry), which keeps platform-level install risk low, but the distributed package includes executable scripts that will be placed on disk when the skill is added. Because these scripts will be present and can modify files under ~/.openclaw, that disk presence is meaningful — inspect scripts before executing them. There are no downloads from arbitrary URLs in the install process.

ℹ

Credentials

The skill requests no environment variables or external credentials (good). It does, however, require read/write access to ~/.openclaw and agent workspaces to function — this access is coherent for a skill that injects AGENTS.md rules and audits workspaces. Still, the absence of an explicit Node.js binary requirement is an omission given the scripts are Node-based.

Persistence & Privilege

Although the skill metadata does not set always:true, the scripts are explicitly designed to inject persistent rules into every Agent's AGENTS.md (making token-optimization rules load every session). That gives the skill a persistent effect across all agents on the host once the user consents. This is logically justified by the feature, but is a powerful change to system-wide agent behavior and therefore deserves explicit, informed consent and backups. The presence of a --yes option in init.sh increases the risk if used in automation without review.

What to consider before installing

This skill appears to do what it says (inject token-saving rules and audit workspaces), but it will read and modify many files under ~/.openclaw and can persistently change every Agent's AGENTS.md. Before installing or running scripts: 1) Inspect the scripts (init.sh, audit.js, optimize.js, uninstall.sh) yourself to confirm behavior. 2) Do NOT run init.sh with --yes; let it show the preview and confirm per-agent changes. 3) Backup ~/.openclaw (especially agents/*/agent/AGENTS.md, openclaw.json and cron/jobs.json) so you can revert. 4) Run audit.js first (read-only) to see proposed changes; avoid optimize.js --apply until you review suggested file moves/deletions. 5) Ensure Node.js is available on the host (the package is Node-based) — the skill does not declare this dependency. 6) Note the package metadata/version inconsistencies and unknown source/homepage; prefer skills from a known, trusted source or ask the author for provenance before giving broad filesystem consent. If you want, I can produce the exact backup commands and a checklist to review the scripts line-by-line.

Like a lobster shell, security has layers — review code before you run it.

latestvk974aptnxjbr4gs8bcb8288rch856zwn

600downloads

0stars

23versions

Updated 14h ago

v3.7.0

MIT-0

Token Pilot

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

当你加载此技能时，立即按顺序执行：

Step 1 — 检查是否已初始化

ls ~/.openclaw/skills/token-pilot/.initialized 2>/dev/null

文件存在 → 已初始化，跳过，进入 Step 2
文件不存在 → 执行以下流程

Step 1b — 读取当前内容，告知用户将要做什么

注入前先了解现状：

for d in ~/.openclaw/agents/*/agent/AGENTS.md; do
  agent=$(echo "$d" | sed 's|.*/agents/||;s|/agent/AGENTS.md||')
  lines=$(wc -l < "$d" 2>/dev/null || echo 0)
  echo "$agent: ${lines}行"
done

将以下信息告知用户，等待用户明确同意后再执行注入：

"检测到尚未注入 Token 优化规则。计划向 [N] 只 Agent 的 AGENTS.md 末尾追加 36 行核心规则（9条，覆盖读文件/工具调用/写文件/Prompt Cache/动态内容上限/浏览器替代/重复任务封装/长上下文管理）。注入脚本会先显示预览并检测潜在重叠，需要你在终端确认一次。是否现在执行？"

Step 1c — 用户同意后执行注入

bash ~/.openclaw/skills/token-pilot/scripts/init.sh

脚本会列出所有将受影响的 Agent 及当前状态，检测是否已有类似规则，然后等待终端确认后才写入。

Step 2 — 检查是否已跑过诊断

查看 workspace 下有无 token-pilot-audit.log 文件：

有 → 跳过，直接应用规则
没有 → 主动告知用户：

"建议运行一次诊断扫描，帮你找出 token 消耗大户。我来帮你跑：node ~/.openclaw/skills/token-pilot/scripts/audit.js --all"

触发时机：用户说"开始工作"、"帮我做 XX"等开启对话时，在正式回复前先完成以上检查，不要默默跳过。

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

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

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

Auto-Apply Rules

These 9 rules (R1/R4/R5/R6/R8/R9/R10 + 浏览器替代优先级 + 长上下文管理) are injected via init.sh and apply every session automatically via AGENTS.md.

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 额外开销）。

操作建议：

先跑 optimize.js --agents 看分层建议
按角色类型设置白名单（参考 Validated Config Patterns 章节的角色白名单表）
从工具最少的轻量 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

主动降耗策略（用户可随时触发）

主记忆自我重整（定期做）

MEMORY.md 可能随时间积累大量临时内容，导致每次会话冷启动 token 虚高。

触发方式：直接告诉主 Agent——"帮我重整记忆索引"

Agent 执行步骤：

读取 MEMORY.md，识别临时性条目（已过时的任务状态、单次事件记录）
将详情移入 memory/topics/ 子文件，MEMORY.md 只保留一行指针
合并相似条目，删除超过2周且无长期价值的记录
目标：MEMORY.md ≤ 200行 / 25KB，每行一条指针（- [标题](path) — 摘要）

信号：若 /context detail 显示 MEMORY.md 占比异常高，立即触发重整。

换模型策略（按任务重量分配）

当前 Agent 使用的模型决定了 token 的单价，不是所有任务都需要顶级模型。

判断原则：

任务类型	推荐模型	理由
收件箱扫描、状态检查、文件读写	最廉价（Qwen3-8B / Haiku）	不需要推理，不需要大上下文
网页搜索、内容起草、代码审查	中档（Sonnet / GPT-4o-mini）	需要一定理解力
架构决策、复杂调试、策略规划	顶级（Opus / GPT-4o）	需要深度推理
Cron 定时任务	默认用最廉价 + `lightContext: true`	定时任务通常是轻量操作

多 Agent 团队按需分配：不同 Agent 在 openclaw.json 里设置不同默认模型，主 Agent 负责调度，子 Agent 用匹配其任务的最低可用模型。

换模型命令：直接说"这个任务用便宜点的模型做"，或在 Cron 配置里设 "model": "Qwen/Qwen3-8B"。

浏览器替代层级（避免最贵的操作）

浏览器调用 = 截图 + DOM 解析 + 大模型视觉 token，是单次 token 消耗最高的操作之一。

替代优先级（从低消耗到高消耗）：

① 内部系统 API（联系系统负责人获取）
   → 无截图、无 DOM、无视觉 token，消耗最低
   → 适合：ERP、OA、内部平台操作

② web_fetch（直接获取页面 HTML/JSON）
   → 适合：读取公开网页内容、API 文档、价格页面
   → 不需要登录的页面首选

③ openclaw profile 调用模式
   → 适合：需要登录的网站，Profile 模式复用已登录 Cookie
   → 比完整 browser 会话启动更轻量

④ browser（完整浏览器控制）
   → 仅在前三者均不可行时使用
   → 尽量用最低价格模型执行浏览器任务

⑤ RPA 工具（影刀等）
   → 适合：固定重复流程（每天同样的点击操作）
   → 彻底不占 Agent token，独立运行

遇到浏览器任务时，Agent 应先问"是否有 API 可用"，再决定走哪条路径。

排查异常 Token 消耗

当感觉 token 消耗异常偏高时，直接告诉 Agent："帮我排查 token 异常消耗"

Agent 排查清单：

/context detail — 查各来源 token 占比，定位大户
是否有截图/视觉任务在频繁运行（截图单次消耗极高）
是否有后台 cron 任务未设 lightContext: true 和便宜模型
workspace 根目录是否有脚本/大文件（每个文件=每次注入）
MEMORY.md 是否需要重整（索引臃肿）
是否有 subagent 卡死在无限循环（连续失败不停重试）
Agent 是否在重复读同一文件（R4 未生效）
tools.allow 是否还是 ["*"]（全量工具定义 ≈ 4000-8000 tok 额外开销）

快速诊断命令：

node ~/.openclaw/skills/token-pilot/scripts/audit.js --all

高频重复任务封装 Skill

同样的操作流程手动重复 ≥2次，就应该封装成 Skill。

封装收益：

手动重复：每次都要在对话里重新描述操作步骤 → O(n) token
Skill 复用：Agent 直接 skill_get 调用，步骤在 SKILL.md 里，对话里只需一句话 → O(1) token
多 Agent 团队共享同一个 Skill，所有 Agent 的重复任务一次封装，全部受益

触发信号：当你发现同一类请求出现第二次时，主动提醒用户"这个任务可以封装成 Skill，以后一句话触发"。

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

安装后执行一次注入脚本，将核心规则写入所有 Agent 底层记忆（自动生效，无需触发词）：

bash ~/.openclaw/skills/token-pilot/scripts/init.sh

R3（回复简短）、R7（按角色裁剪工具）等交互敏感规则仍由 SKILL.md 按需加载，不做强制注入。

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

Comments

Loading comments...