OpenCode-Tokenscope 安装和使用指南

OpenCode-Tokenscope 安装和使用指南全面的 OpenCode AI 会话 token 使用分析和成本追踪插件安装方法 1: npm (推荐)步骤 1: 全局安装npminstall-gramtinj95/opencode-tokenscope步骤 2: 配置 opencode.json在以下位置之一创建opencode.json项目根目录~/.config/opencode/opencode.json(全局配置){$schema:https://opencode.ai/config.json,plugin:[ramtinj95/opencode-tokenscope]}要始终使用最新版本使用latest{plugin:[ramtinj95/opencode-tokenscopelatest]}步骤 3: 创建 /tokenscope 命令创建命令文件~/.config/opencode/command/tokenscope.mdmkdir-p~/.config/opencode/commandcat~/.config/opencode/command/tokenscope.mdEOF --- description: Analyze token usage across the current session with detailed breakdowns by category --- Call the tokenscope tool directly without delegating to other agents. Then cat the token-usage-output.txt. DONT DO ANYTHING ELSE WITH THE OUTPUT. EOF步骤 4: 重启 OpenCode完全重启 OpenCode然后运行/tokenscope方法 2: 安装脚本curl-sSLhttps://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/install.sh|bash然后重启 OpenCode 并运行/tokenscope更新npm 安装更新opencode.json 配置行为ramtinj95/opencode-tokenscope使用安装时的版本永不自动更新ramtinj95/opencode-tokenscopelatest每次启动 OpenCode 时获取最新版本ramtinj95/opencode-tokenscope1.4.0固定到确切版本 1.4.0永不更新手动更新npmupdate-gramtinj95/opencode-tokenscope脚本安装更新curl-sSLhttps://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/install.sh|bash-s----update--update标志跳过依赖安装更新更快。使用方法在 OpenCode 中输入/tokenscope插件将分析当前会话统计各类别 token递归分析所有子代理 (Task 工具) 子会话基于 API 遥测计算成本保存详细报告到token-usage-output.txt功能特性全面的 Token 分析特性说明5 类别分解系统提示、用户消息、助手回复、工具输出、推理轨迹可视化图表易读的 ASCII 条形图带百分比和 token 计数智能推断从 API 遥测自动推断系统提示因为会话消息中未暴露上下文分解分析系统提示组件显示基础提示、工具定义、环境上下文、项目树、自定义指令的 token 分布自动估算当系统提示内容不可用时从cache_writetoken 估算分解工具计数显示加载的工具数量及其组合 token 成本工具定义成本估算每个工具估算列出所有启用的工具及其估算的 schema token 成本参数分析从会话中的实际工具调用推断参数数量和复杂度复杂度检测区分简单参数和复杂参数数组/对象缓存效率指标缓存命中率缓存读取 vs 新鲜输入 token 分布的可视化显示成本节省计算提示缓存带来的实际节省有效费率显示实际支付的每 token 成本 vs 标准费率精确成本追踪支持 41 种模型包括Claude 模型Claude Opus 4.5, 4.1, 4Claude Sonnet 4, 4-5, 3.7, 3.5, 3Claude Haiku 4-5, 3.5, 3OpenAI 模型GPT-4, GPT-4 Turbo, GPT-4o, GPT-4o MiniGPT-3.5 TurboGPT-5 及其所有变体其他模型DeepSeek (R1, V2, V3)Llama (3.1, 3.2, 3.3)Mistral (Large, Small)Qwen, Kimi, GLM, Grok等等…子代理成本追踪子会话分析递归分析 Task 工具生成的所有子代理会话汇总总计显示主会话和所有子代理的合并 token、成本和 API 调用每个代理分解列出每个子代理及其类型、token 使用、成本和 API 调用计数可选切换使用includeSubagents参数启用/禁用子代理分析配置选项创建tokenscope-config.json文件自定义输出{enableContextBreakdown:true,enableToolSchemaEstimation:true,enableCacheEfficiency:true,enableSubagentAnalysis:true,enableSkillAnalysis:true}将任何选项设置为false可隐藏该部分输出。输出示例═══════════════════════════════════════════════════════════════════════════ Token Analysis: Session ses_50c712089ffeshuuuJPmOoXCPX Model: claude-opus-4-5 ═══════════════════════════════════════════════════════════════════════════ TOKEN BREAKDOWN BY CATEGORY ───────────────────────────────────────────────────────────────────────── Input Categories: SYSTEM ██████████████░░░░░░░░░░░░░░░░ 45.8% (22,367) USER ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.8% (375) TOOLS ████████████████░░░░░░░░░░░░░░ 53.5% (26,146) Subtotal: 48,888 estimated input tokens Output Categories: ASSISTANT ██████████████████████████████ 100.0% (1,806) Subtotal: 1,806 estimated output tokens Local Total: 50,694 tokens (estimated) TOOL USAGE BREAKDOWN ───────────────────────────────────────────────────────────────────────── bash ██████████░░░░░░░░░░░░░░░░░░░░ 34.0% (8,886) 4x read ██████████░░░░░░░░░░░░░░░░░░░░ 33.1% (8,643) 3x task ████████░░░░░░░░░░░░░░░░░░░░░░ 27.7% (7,245) 4x webfetch █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 4.9% (1,286) 1x CACHE EFFICIENCY ───────────────────────────────────────────────────────────────────────── Cache Hit Rate: 86.2% Cost Savings: $1.4421 (77.6% reduction) ESTIMATED SESSION COST ───────────────────────────────────────────────────────────────────────── Input tokens: 10 × $5.00/M $0.0001 Output tokens: 3,331 × $25.00/M $0.0833 Cache read: 320,479 × $0.50/M $0.1602 Cache write: 51,866 × $6.25/M $0.3242 ───────────────────────────────────────────────────────────────────────── ESTIMATED TOTAL: $0.5677 ═══════════════════════════════════════════════════════════════════════════技能分析技能工作原理技能是通过skill工具加载的按需指令。它们有两个 token 消耗点可用技能列表技能名称和描述嵌入在skill工具的描述中作为 XML。这是系统提示的一部分每次 API 调用都产生成本。加载的技能内容当代理调用skill({ name: my-skill })时完整的 SKILL.md 内容作为工具结果加载。多次调用技能为何增加 Token 成本重要OpenCode不会去重技能内容。每次调用相同的技能完整内容都会作为新的工具结果再次添加到上下文中。例如如果你调用skill({ name: git-release })3 次每次包含 500 token总上下文成本 500 × 3 1,500 tokens这是 OpenCode 设计的行为。技能内容受保护不会被修剪见 compaction.ts 中的PRUNE_PROTECTED_TOOLS: [skill]。建议谨慎调用技能由于每次调用都添加完整内容避免多次调用相同技能监控技能 token 使用使用 TokenScope 查看哪些技能消耗最多 token考虑技能大小大型技能1000 tokens在重复调用时会快速增加上下文故障排除/tokenscope命令未出现验证tokenscope.md是否存在ls~/.config/opencode/command/tokenscope.md如果缺失重新创建见安装步骤 3完全重启 OpenCodeToken 计数不正确插件使用 API 遥测真实数据。如果计数看起来不对预期与 TUI 有约 2K 差异插件在添加自己的响应之前分析模型检测检查输出中模型名称是否被识别隐私与安全所有处理都是本地进行不向外部服务发送会话数据开源可自行审计代码资源链接GitHub: https://github.com/ramtinj95/opencode-tokenscopeNPM: https://www.npmjs.com/package/ramtinj95/opencode-tokenscopeIssues: https://github.com/ramtinj95/opencode-tokenscope/issuesDiscussions: https://github.com/ramtinj95/opencode-tokenscope/discussions文档版本: 基于 opencode-tokenscope v1.5.2修改 Token 费用单价Token 费用单价存储在插件的models.json文件中。你可以通过编辑这个文件来自定义各模型的价格。配置文件路径~/.cache/opencode/node_modules/ramtinj95/opencode-tokenscope/models.json价格格式说明{模型名称:{input:1.00,// 输入 token 每百万的价格美元output:3.00,// 输出 token 每百万的价格美元cacheWrite:0.00,// 缓存写入每百万的价格美元cacheRead:0.00// 缓存读取每百万的价格美元}}支持的模型目前支持 41 种模型包括类别模型Claudeclaude-opus-4, claude-sonnet-4, claude-haiku-4-5, claude-3.7-sonnet, claude-3.5-sonnet, claude-3.5-haiku, claude-3-opus, claude-3-sonnet, claude-3-haikuOpenAIgpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-3.5-turbo, gpt-5 系列DeepSeekdeepseek-r1, deepseek-v3, deepseek-v2Llamallama-3.3, llama-3.2, llama-3.1Mistralmistral-large, mistral-small其他kimi-k2, grok-code, qwen3-coder, glm-4.5 等修改示例示例 1修改 kimi-k2 的价格# 编辑 models.json 文件vim~/.cache/opencode/node_modules/ramtinj95/opencode-tokenscope/models.json找到kimi-k2部分kimi-k2:{input:0.60,output:2.50,cacheWrite:0.00,cacheRead:0.00}修改为kimi-k2:{input:0.80,// 改为新价格output:3.00,// 改为新价格cacheWrite:0.00,cacheRead:0.00}示例 2修改 Claude Sonnet 4 的价格claude-sonnet-4:{input:3.00,output:15.00,cacheWrite:3.75,cacheRead:0.30}修改步骤打开配置文件vim~/.cache/opencode/node_modules/ramtinj95/opencode-tokenscope/models.json找到要修改的模型使用搜索功能 (/模型名称) 快速定位或滚动查找对应模型条目修改价格参数input: 输入 token 每百万价格output: 输出 token 每百万价格cacheWrite: 缓存写入每百万价格如适用cacheRead: 缓存读取每百万价格如适用保存文件:wq# vim 保存并退出立即生效无需重启 OpenCode直接运行/tokenscope即可使用新价格注意事项⚠️重要提醒插件更新会覆盖当你更新ramtinj95/opencode-tokenscope插件时models.json文件会被重置为默认值建议备份自定义价格# 创建备份cp~/.cache/opencode/node_modules/ramtinj95/opencode-tokenscope/models.json\~/.config/opencode/tokenscope-pricing-backup.json更新后恢复价格# 插件更新后恢复自定义价格cp~/.config/opencode/tokenscope-pricing-backup.json\~/.cache/opencode/node_modules/ramtinj95/opencode-tokenscope/models.json默认值回退如果某个模型没有在models.json中找到会使用default条目default:{input:1.00,output:3.00,cacheWrite:0.00,cacheRead:0.00}配置完成示例实际配置文件路径~/.config/opencode/opencode.json ~/.config/opencode/command/tokenscope.md配置后的 opencode.json 示例{$schema:https://opencode.ai/config.json,plugin:[superpowersgithttps://github.com/obra/superpowers.git,oh-my-openagent,ramtinj95/opencode-tokenscopelatest]}注意: 使用了latest标签每次启动 OpenCode 时会自动获取最新版本。tokenscope.md 命令文件内容--- description: Analyze token usage across the current session with detailed breakdowns by category --- Call the tokenscope tool directly without delegating to other agents. Then cat the token-usage-output.txt. DONT DO ANYTHING ELSE WITH THE OUTPUT.使用步骤总结安装插件:npm install -g ramtinj95/opencode-tokenscope创建命令文件:~/.config/opencode/command/tokenscope.md配置 opencode.json: 添加ramtinj95/opencode-tokenscopelatest到 plugin 数组重启 OpenCode: 完全关闭并重新打开运行分析: 输入/tokenscope输出文件运行/tokenscope后会在当前目录生成token-usage-output.txt- 详细的 token 使用分析报告