token-pilot

# Token Pilot

## 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

---

## 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.

### [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 (s...

# Token Pilot

OpenClaw Agent 自动省 Token 技能。纯 Node.js，跨平台，零依赖。

## 5 分钟快速优化

### 第 1 步：安装

```bash
clawhub install token-pilot
```

### 第 2 步：扫描当前状态

```bash
node ~/.openclaw/skills/token-pilot/scripts/optimize.js
```

脚本会自动扫描你的**所有 workspace**、cron 任务、agent 配置，输出每项的优化建议和预估节省量。

### 第 3 步：一键清理（安全）

```bash
node ~/.openclaw/skills/token-pilot/scripts/optimize.js --apply
```

自动执行：
- 把 workspace 根目录的 .js/.txt/.log/.cmd 等临时文件移到 `scripts/` 子目录
- 删除已完成 bootstrap 后遗留的 BOOTSTRAP.md

**只做安全操作，不改配置文件，不改 SOUL.md。**

### 第 4 步：替换臃肿的 AGENTS.md（最大收益！）

```bash
node ~/.openclaw/skills/token-pilot/scripts/optimize.js --template
```

会输出一个 ~300 token 的精简版 AGENTS.md 模板。复制后替换你的 `~/.openclaw/workspace/AGENTS.md`。

默认 AGENTS.md 约 2000 tok，替换后**每次会话省 ~1700 tok**。

### 第 5 步：按建议手动调整（如适用）

**有 cron 任务？**
```bash
node ~/.openclaw/skills/token-pilot/scripts/optimize.js --cron
```
会告诉你哪些 job 该加 `lightContext`、哪些该用便宜模型、哪些 prompt 太长。

**有多个 agent？**
```bash
node ~/.openclaw/skills/token-pilot/scripts/optimize.js --agents
```
会建议 main agent 用最好模型，团队 agent 降到中档。

**查配置是否到位？**
```bash
node ~/.openclaw/skills/token-pilot/scripts/audit.js --config
```
5 项评分：bootstrapMaxChars、bootstrapTotalMaxChars、heartbeat interval、activeHours、compaction。

### 第 6 步：完成

装好后 **6 条行为规则自动生效**，Agent 会在交互中自动：
- 先 peek 再全读（省读取量）
- 压缩工具返回结果（省输出）
- 简短回答简单问题
- 不重复读已读文件
- 批量发起独立工具调用
- 用 edit 代替 write

无需额外配置，无需记住任何命令。

---

## 预期效果

| 场景 | 节省 |
|------|------|
| 首次优化（替换 AGENTS.md + 清理） | **~2000-5000 tok/session** |
| 6 条运行时规则 | **15-30% 运行时 token** |
| cron 模型分层（如有） | **cron 费用 -70~90%** |
| agent 模型分层（如有多 agent） | **交互费用 -70~80%** |...