Token Optimizer 的定位是“削减你浪费的 token，保住你会丢失的工作”。据官方说明，它面向 AI 编程助手工作流，在后台自动运行，用户可照常工作，需要完整情况时再运行审计。其口号是：找出幽灵 token、修复它们、在压缩中存活、避免上下文质量衰减。
用途方面，官方强调它不止压缩命令输出。它认为命令输出只占上下文约 15%–25%，其余约 75% 未被覆盖，包括臃肿的配置、未使用的技能、过期记忆、压缩丢失、模型误路由与行为性浪费。官方称每一项节省都是缓存安全且可测量的，仪表盘在每次会话后自动更新。
主要能力分为“自动运行”和“按需运行”两类。自动运行包括：智能压缩（自动压缩前打检查点、压缩后恢复）、会话连续性（跨会话提示、冷恢复、检查点评分）、主动压缩（9 项功能默认开启：增量差异、骨架、bash/搜索压缩、精简输出提示、质量提示、循环检测、活动模式、决策提取）、质量评分（7 个信号、实时、S–F 字母等级）、会话数据库（SQLite、15 张表、完整审计轨迹、零网络）、渐进式披露（大输出归档、按需展开）、上下文情报摘要（压缩后重新定位而不重读）、模型路由提示（引导到合适的层级）。按需运行的命令包括：/token-optimizer 完整审计与引导修复、/token-coach 30 天趋势分析、quick 10 秒健康检查、route 在花费前给出任务所需模型与投入、doctor 安装检查、savings 美元节省报告、report 按组件的 token 细分、dashboard 打开完整仪表盘、memory-review MEMORY.md 结构审计、expand 取回归档的工具结果、resume-lean 重新打开冷会话。
使用方式上，官方给出多种安装路径。Claude Code 推荐通过插件市场安装，然后在 Claude Code 中运行 /token-optimizer；安装后建议开启自动更新（/plugin → Marketplaces 标签 → 选择 alexgreensh-token-optimizer → 启用自动更新，一次性约 10 秒）。安装后运行一次 /token-optimizer 设置 hooks，之后压缩、检查点、质量评分、仪表盘更新都自动运行。Claude Code 云会话（claude.ai/code）在全新容器中运行，不读取本机插件，因此需要为 claude.ai 账户启用，或把配置提交到仓库的 .claude/settings.json；云会话每次状态目录为空，仪表盘和审计历史只覆盖该次会话。Codex 在 TUI 中使用 /plugins 安装（见 docs/codex.md）。OpenCode V2 把 token-optimizer-opencode 加入 opencode.json 的 plugins 数组（V1 1.18.29+ 使用 plugin）。OpenClaw、Hermes 见各自 README。Pi Coding Agent 安装后运行 /token-optimizer enable 选择加入；本机模型成本在活动分支报告，本地工具归档和连续性标记需单独选择加入，命令、隐私、更新、卸载与限制见 pi/README.md。GitHub Copilot、Cursor、Google Antigravity、Grok Build（beta，仅合约）分别见 docs/copilot.md、docs/cursor.md、docs/antigravity.md、docs/grok.md。另有 macOS/Linux 脚本安装作为插件的替代方案；Windows 用户只能用插件安装，不要运行 install.sh，若遇 EBUSY 错误需关闭所有 Claude Code 与 Git Bash 窗口、结束残留 git.exe 进程、删除 C:\Users<you>.claude\token-optimizer 与 C:\Users<you>.claude\plugins\marketplaces\alexgreensh-token-optimizer 后重试。若 install.sh 报 $'\r': command not found（LF 行尾强制前克隆导致 CRLF），去掉回车符再运行一次。
Claude Code 插件还提供 Claude Desktop 应用内的状态栏（mod）：显示质量等级、上下文填充度、缓存保持时长和两个用量限制，一句话提示需关注的内容，一个按钮修复；吉祥物 Clawd 表现会话状态。该状态栏随插件提供，无需额外安装。
与其他工具的区别：官方称 Headroom、RTK、JFrog Boost 等主要压缩 bash 和命令输出，而 Token Optimizer 覆盖输出栈的八个面，并延伸到压缩之外：结构浪费（臃肿配置、未使用技能、过期记忆）、运行时浪费（冗长输出、重复读取）、行为浪费（模型误路由、缓存过期、重试循环）；节省能在压缩中存活；能测量是否有帮助（前后 token 差异、四档定价的美元节省、质量评分）；零基线开销（外部进程、无常驻上下文指令、无 MCP 服务器、无依赖、无遥测）。
主动压缩的 9 项功能默认开启、自动、可从仪表盘或 CLI 切换。其机制是：PreToolUse hooks 在 Read 和 Bash 调用进入上下文前拦截；若文件已读过只返回差异；若代码文件重复读取则用结构骨架替代全文；若为 CLI 命令则压缩输出；PostToolUse hooks 把完整原始内容归档到磁盘并向 SQLite 记录压缩事件，内容可检索。功能包括：增量读取（编辑后重读只返回差异，官方称真实会话中 65%+ 的 Read 是重读，2000 token 文件重读变成 50 token 差异，可用 TOKEN_OPTIMIZER_READ_CACHE_DELTA=0 关闭）；影子读取（重复读取代码文件被替换为结构摘要，720KB Python 文件 180,000 token 变成 250 token 骨架，可用 TOKEN_OPTIMIZER_READ_CACHE_MODE=shadow 关闭）；首次读取骨架（v5.12 起目标文件首次读取始终完整提供，节省来自旁边注入的外围骨架（一跳关系、PageRank 排序），仅适用于代码，Markdown 等散文首次读取不做骨架，可用 TOKEN_OPTIMIZER_FIRST_READ_ACTIVE=0 停止提供、TOKEN_OPTIMIZER_FIRST_READ_SHADOW=0 完全关闭）；Bash 输出压缩（重写常见 CLI 命令返回压缩摘要，覆盖 lint、日志尾部、tree、docker pull、长列表、构建输出、测试运行器，564 token 的 pytest 输出变为 115 token，可用 TOKEN_OPTIMIZER_BASH_COMPRESS=0 关闭）；自定义命令过滤器（TOML，位于 <runtime-home>/token-optimizer/command-filters.toml，可用 TOKEN_OPTIMIZER_COMMAND_FILTERS 覆盖路径；加载器拒绝 shell 解释器、提权包装、破坏性写入子命令或含 shell 元字符的 add 条目，分类排除不可被用户配置覆盖）；搜索结果压缩（grep、rg 或网页搜索返回长列表时压缩为顶部命中加计数，500 行 grep 变 20 行加摘要，与 bash 压缩共用开关）；精简输出提示（上下文填充超过 25% 时提示模型深入推理但保持可见输出精简，仅以填充为条件，节省按 10–15% 估算而非测量）；等等。
仪表盘方面：单个 HTML 页面，由 SessionEnd hook 在每次会话后自动重新生成，无需手动触发。可收藏的 URL http://localhost:24842/token-optimizer 需先运行 python3 skills/token-optimizer/scripts/measure.py setup-daemon 启动本地服务器才可用；在此之前打开 measure.py dashboard 在 Dashboard: 行打印的文件路径。仪表盘包含每轮 token 细分、四档定价成本、缓存分析（TTL 混合与命中率）、叠加在每次会话上的质量评分、子代理成本细分、节省跟踪器（计量与估算分级分开）。
收益数据方面，官方给出一个基于作者最近 30 天、六个杠杆全开、1,698 次会话（快照 2026-09-14）的示例：计量部分“已记录操作”约 126 美元，2,733 个事件带有前后 token 计数；估算部分“避免的重复读取”约 1,124 美元；其他估算约 146 美元。合计约 1,396 美元 API 等价价值，59.6M token 从未发送给模型，约占工作负载 28%（花费 150.8M，不使用则约 210.4M）。官方强调 token 是主要数字，美元取决于所用模型，计量与估算从不合并为一个数字，用户自己的数字由仪表盘基于自己的会话计算。
限制与缺失：上述收益为官方基于作者会话的示例，不代表用户自身结果。部分平台标注为 beta（如 Devin 输出过滤、Grok Build 仅合约），部分集成为文档链接但正文未展开。关于价格、付费模式、平台可用性、具体使用步骤等，资料中暂未提供完整信息，需以各集成对应文档为准。
