Automatic token optimization during interaction. Behavioral rules + plugin synergy + workspace analyzer. Pure Node.js, cross-platform. Activate on session st...
---
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: 3.6.0
author: beyound87
---
# Token Pilot
## 🚀 首次加载行动(Agent 必读)
**当你加载此技能时,立即按顺序执行:**
**Step 1 — 检查是否已初始化**
```bash
ls ~/.openclaw/skills/token-pilot/.initialized 2>/dev/null
```
- **文件存在** → 已初始化,跳过,进入 Step 2
- **文件不存在** → 执行以下流程
**Step 1b — 读取当前内容,告知用户将要做什么**
注入前先了解现状:
```bash
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
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"等开启对话时,在正式回复前先完成以上检查,不要默默跳过。
3. **Heartbeat cron 自动维护**(可选配置,降低长期维护成本):
如果用户 openclaw.json 中有 cron 配置,建议添加一条每周一次的优化扫描:
```json
{
"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 额外开销)。
**操作建议:**
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)
```ts
AUTOCOMPACT_BUFFER_TOKENS = 13_000 // 提前触发压缩的缓冲
WARNING_THRESHOLD_BUFFER_TOKENS = 20_000 // 预警缓冲
```
Claude Code 不是"满了再压",而是**离上限还有 13,000 token 时就触发 compaction**。
**当前配置 `softThresholdTokens: 4000` 偏激进**,长对话里一次复杂工具调用就能跨越这 4K 缓冲,导致 memoryFlush 触发太晚。建议调整:
```json
"compaction": {
"mode": "safeguard",
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 8000
}
}
```
### C. Compaction 后 token 范围:10K-40K 才是正常区间(来源:sessionMemoryCompact.ts)
```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)
```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 纯亏损:
```json
// 通知/告警类 agent 配置
{ "id": "alerts", "params": { "cacheRetention": "none" } }
```
稳定 agent(main/architect)保持 `"long"`:每次 read 只需 write 价格的 8%。
### E. Subagent"边际递减"检测:连续 3 轮不足 500 token 增量就停(来源:tokenBudget.ts)
```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 执行步骤:
1. 读取 MEMORY.md,识别临时性条目(已过时的任务状态、单次事件记录)
2. 将详情移入 `memory/topics/` 子文件,MEMORY.md 只保留一行指针
3. 合并相似条目,删除超过2周且无长期价值的记录
4. 目标: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 额外开销)
**快速诊断命令**:
```bash
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` 验证后再写入。
---
## OpenClaw Bootstrap 机制(源码分析)
> 来源:`workspace-DGJIk8rw.js` `loadWorkspaceBootstrapFiles()`
**白名单加载,不是全目录扫描!** 只注入以下 8 个文件:
```
AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md BOOTSTRAP.md MEMORY.md
```
`.js`、`.txt`、`.json` 等**不在白名单中,不会被注入**。
**注入流程**:读白名单文件 → 子 agent/cron 只保留最小 5 个 → 按 `bootstrapMaxChars`(单文件上限,默认 6000 字符)和 `bootstrapTotalMaxChars`(总和上限,默认 12000 字符)裁剪,顺序加载,预算用完即止。
### R11: AGENTS.md 大小红线(新增)
- AGENTS.md 是最危险文件 — 注入规则(security-hardening、token-pilot 等)后极易超 6000 字符被**静默截断**
- 注入前先检查当前字节数:`wc -c AGENTS.md`
- 注入后总大小 ≤ 4800 字符(`bootstrapMaxChars` 的 80%,留安全余量)
- 超限 → 把低频规则移到 `references/` 子目录,按需 read 加载
- `audit.js` 现在只检查白名单文件,不再误报所有文件大小
---
## Setup / Config / Scripts
### Setup
**安装后执行一次注入脚本**,将核心规则写入所有 Agent 底层记忆(自动生效,无需触发词):
```bash
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
```bash
# 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
```json
{
"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):
```json
{
"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(长会话稳定性)
```json
"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
```json
"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。
```json
"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
### 实时诊断命令(随时可用)
```bash
# 查当前 session token 用量 + 模型 + 预估费用
/status
# 每条回复后显示 token 用量
/usage tokens
# 查看 context 分解(各文件/工具/skill 各占多少)
/context list
/context detail
# 手动触发 session 压缩
/compact
```
don't have the plugin yet? install it then click "run inline in claude" again.