OpenCode-Tokenscope 安装和使用指南

关注

原创最新推荐文章于 2026-10-31 10:19:15 发布 951 阅读 AI 写同款· GEO 优化 ›

OpenCode插件实战：实时显示Token生成速度与DSH样式管理 Token是语言模型处理文本的最小计量单位，其生成速度（TPS）直接影响AI编程工具的使用体验和成本控制。在模型流式输出过程中，实时监测TPS能帮助开发者区分模型思考、网络延迟还是上下文过长导致的性能下降。掌握Token消耗规律，对优化提示词、控制API费用和评估模型性能都有重要参考价值。随着AI辅助编码工具普及，如何直观感知生成速度成为开发者关注的焦点。本文基于OpenCode插件机制，介绍一种实时显示Token生成速度的方案，并通过DSH样式管理系统定制输出面板，涵盖采样窗口、滑动平均、多Provide 阅读详情

OpenCode-Tokenscope 安装和使用指南

全面的 OpenCode AI 会话 token 使用分析和成本追踪插件

安装

方法 1: npm (推荐)

步骤 1: 全局安装

npm install -g @ramtinj95/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-tokenscope@latest"]
}

步骤 3: 创建 /tokenscope 命令

创建命令文件 ~/.config/opencode/command/tokenscope.md：

mkdir -p ~/.config/opencode/command
cat > ~/.config/opencode/command/tokenscope.md << 'EOF'
---
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 -sSL https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/install.sh | bash

然后重启 OpenCode 并运行 /tokenscope

更新

npm 安装更新

opencode.json 配置	行为
`"@ramtinj95/opencode-tokenscope"`	使用安装时的版本，永不自动更新
`"@ramtinj95/opencode-tokenscope@latest"`	每次启动 OpenCode 时获取最新版本
`"@ramtinj95/opencode-tokenscope@1.4.0"`	固定到确切版本 1.4.0，永不更新

手动更新：

npm update -g @ramtinj95/opencode-tokenscope

脚本安装更新

curl -sSL https://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_write token 估算分解
工具计数：显示加载的工具数量及其组合 token 成本

工具定义成本估算

每个工具估算：列出所有启用的工具及其估算的 schema token 成本
参数分析：从会话中的实际工具调用推断参数数量和复杂度
复杂度检测：区分简单参数和复杂参数（数组/对象）

缓存效率指标

缓存命中率：缓存读取 vs 新鲜输入 token 分布的可视化显示
成本节省：计算提示缓存带来的实际节省
有效费率：显示实际支付的每 token 成本 vs 标准费率

精确成本追踪

支持 41+ 种模型，包括：

Claude 模型

Claude Opus 4.5, 4.1, 4
Claude Sonnet 4, 4-5, 3.7, 3.5, 3
Claude Haiku 4-5, 3.5, 3

OpenAI 模型

GPT-4, GPT-4 Turbo, GPT-4o, GPT-4o Mini
GPT-3.5 Turbo
GPT-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）
完全重启 OpenCode

Token 计数不正确

插件使用 API 遥测（真实数据）。如果计数看起来不对：

预期与 TUI 有约 2K 差异：插件在添加自己的响应之前分析
模型检测：检查输出中模型名称是否被识别

隐私与安全

所有处理都是本地进行：不向外部服务发送会话数据
开源：可自行审计代码

资源链接

GitHub: https://github.com/ramtinj95/opencode-tokenscope
NPM: https://www.npmjs.com/package/@ramtinj95/opencode-tokenscope
Issues: https://github.com/ramtinj95/opencode-tokenscope/issues
Discussions: 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+ 种模型，包括：

类别	模型
Claude	claude-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-haiku
OpenAI	gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-3.5-turbo, gpt-5 系列
DeepSeek	deepseek-r1, deepseek-v3, deepseek-v2
Llama	llama-3.3, llama-3.2, llama-3.1
Mistral	mistral-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": [
    "superpowers@git+https://github.com/obra/superpowers.git",
    "oh-my-openagent",
    "@ramtinj95/opencode-tokenscope@latest"
  ]
}

注意: 使用了 @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.