OpenCode-Tokenscope 安装和使用指南
全面的 OpenCode AI 会话 token 使用分析和成本追踪插件
安装
方法 1: npm (推荐)
步骤 1: 全局安装
bash
npm install -g @ramtinj95/opencode-tokenscope步骤 2: 配置 opencode.json
在以下位置之一创建 opencode.json：
- 项目根目录
~/.config/opencode/opencode.json(全局配置)
json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@ramtinj95/opencode-tokenscope"]
}要始终使用最新版本，使用 @latest：
json
{
"plugin": ["@ramtinj95/opencode-tokenscope@latest"]
}步骤 3: 创建 /tokenscope 命令
创建命令文件 ~/.config/opencode/command/tokenscope.md：
bash
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: 安装脚本
bash
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，永不更新 |
手动更新：
bash
npm update -g @ramtinj95/opencode-tokenscope脚本安装更新
bash
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_writetoken 估算分解 - 工具计数：显示加载的工具数量及其组合 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 文件自定义输出：
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是否存在：bashls ~/.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价格格式说明
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 的价格
bash
# 编辑 models.json 文件
vim ~/.cache/opencode/node_modules/@ramtinj95/opencode-tokenscope/models.json找到 kimi-k2 部分：
json
"kimi-k2": {
"input": 0.60,
"output": 2.50,
"cacheWrite": 0.00,
"cacheRead": 0.00
}修改为：
json
"kimi-k2": {
"input": 0.80, // 改为新价格
"output": 3.00, // 改为新价格
"cacheWrite": 0.00,
"cacheRead": 0.00
}示例 2：修改 Claude Sonnet 4 的价格
json
"claude-sonnet-4": {
"input": 3.00,
"output": 15.00,
"cacheWrite": 3.75,
"cacheRead": 0.30
}修改步骤
-
打开配置文件
bashvim ~/.cache/opencode/node_modules/@ramtinj95/opencode-tokenscope/models.json -
找到要修改的模型
- 使用搜索功能 (
/模型名称) 快速定位 - 或滚动查找对应模型条目
- 使用搜索功能 (
-
修改价格参数
input: 输入 token 每百万价格output: 输出 token 每百万价格cacheWrite: 缓存写入每百万价格（如适用）cacheRead: 缓存读取每百万价格（如适用）
-
保存文件
bash:wq # vim 保存并退出 -
立即生效
- 无需重启 OpenCode
- 直接运行
/tokenscope即可使用新价格
注意事项
⚠️ 重要提醒：
-
插件更新会覆盖 ：当你更新
@ramtinj95/opencode-tokenscope插件时，models.json文件会被重置为默认值 -
建议备份自定义价格：
bash# 创建备份 cp ~/.cache/opencode/node_modules/@ramtinj95/opencode-tokenscope/models.json \ ~/.config/opencode/tokenscope-pricing-backup.json -
更新后恢复价格：
bash# 插件更新后恢复自定义价格 cp ~/.config/opencode/tokenscope-pricing-backup.json \ ~/.cache/opencode/node_modules/@ramtinj95/opencode-tokenscope/models.json -
默认值回退 ：如果某个模型没有在
models.json中找到，会使用default条目：json"default": { "input": 1.00, "output": 3.00, "cacheWrite": 0.00, "cacheRead": 0.00 }
配置完成示例
实际配置文件路径
~/.config/opencode/opencode.json
~/.config/opencode/command/tokenscope.md配置后的 opencode.json 示例
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 命令文件内容
markdown
---
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-tokenscope@latest"到 plugin 数组 - 重启 OpenCode: 完全关闭并重新打开
- 运行分析 : 输入
/tokenscope
输出文件
运行 /tokenscope 后，会在当前目录生成：
token-usage-output.txt- 详细的 token 使用分析报告