--- 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 ``` 字段是否存在、类型、允许值，查完再写。不查盲写=必踩坑。 **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 `） - 用 `/context detail` 查看当前 skill list 占了多少 token ### 实时诊断命令（随时可用） ```bash # 查当前 session token 用量 + 模型 + 预估费用 /status # 每条回复后显示 token 用量 /usage tokens # 查看 context 分解（各文件/工具/skill 各占多少） /context list /context detail # 手动触发 session 压缩 /compact ```

Token Pilot

Description

Latest Changes

Install Token Pilot with One Click