1. 本地 OpenCode 用量看板到底解决什么问题如果你用 OpenCode 写过一段时间代码大概率会遇到一个很具体的困惑这个月到底烧了多少 token哪个模型最费钱缓存命中率有没有提升项目 A 和项目 B 谁更耗量OpenCode 本身把每次会话的用量都写进了本地的opencode.db但那个 SQLite 文件对普通用户来说并不友好直接打开只能看到一堆字段名和数字没有聚合、没有图表、没有按天按模型的对比。oc-usage就是冲着这个场景来的。一句话定义它读取本机~/.local/share/opencode/opencode.db用 Node.js 原生node:sqlite做只读查询把 token 用量、成本、缓存命中按天/模型/项目/代理/会话五个维度聚合再通过 React 渲染成一个本地 Web 看板。整个过程数据不出本机不连第三方数据库不上传任何日志。它适合谁三类人最直接受益。第一类是长期用 OpenCode 做编码 Agent 的开发者需要知道自己的 token 消耗趋势判断是不是该换模型或者调 prompt。第二类是团队里负责成本的人想按项目维度看用量分布。第三类是像我这样对数据流向比较敏感的人不愿意把本地会话日志传到任何云端服务只想要一个纯本地、只读、零配置的统计工具。核心检索词先摆出来OpenCode 用量统计、oc-usage 看板、SQLite 本地聚合、Node.js 只读读取、React 可视化。这几个词基本覆盖了从数据源到展示层的完整链路。下面我会按「问题场景 → 前置准备 → 可复制配置 → 验证请求 → 常见报错 → 接入通道」的顺序展开每一步都给能直接粘贴的命令和配置。先说清楚它不做什么它不修改你的opencode.db不写任何数据回数据库不发起外部网络请求。后端server.js是单文件没有 Express、没有 Koa用的是 Node 内置的http模块加原生node:sqlite。前端只有react和react-dom两个运行时依赖路由是自己写的 hash 路由图表是手写的 SVG 和 div没有引入 ECharts 或 Recharts 这类重型库。这种「能省就省」的设计换来的是启动快、依赖少、审计简单——你打开server.js从头读到尾能确认它确实只读本地文件。2. 前置准备Node.js 版本、opencode.db 路径与 TaoToken 统一 Key 通道在跑看板之前有两件事必须先确认Node.js 版本够不够以及 OpenCode 的数据库文件在不在预期位置。Node.js 版本是硬门槛。oc-usage后端依赖原生node:sqlite模块这个模块在 Node.js 22.5.0 才作为实验特性引入低于这个版本会直接报Cannot find module node:sqlite。先查版本node -v # 期望输出 v22.5.0 或更高例如 v22.11.0如果版本不够用 nvm 切换nvm install 22 nvm use 22 node -v数据库路径默认是~/.local/share/opencode/opencode.db。在 macOS 和 Linux 上直接确认ls -lh ~/.local/share/opencode/opencode.db # 期望看到文件存在大小随使用量增长如果这个路径下没有文件程序会自动回退到~/.local/share/opencode/storage/子目录里找。Windows 用户的路径通常在%USERPROFILE%\.local\share\opencode\opencode.db可以用 PowerShell 确认Test-Path $env:USERPROFILE\.local\share\opencode\opencode.db接下来是 TaoToken 统一 Key 通道。看板本身只读本地数据库不参与模型调用但你的 OpenCode 要产生用量数据就得有可用的模型通道。TaoToken 在这里的角色是统一 Key 入口一个 Key 覆盖多个模型OpenCode 侧只需要配置 Base URL 和 Model ID不用为每个模型单独管理凭证。这样看板统计出来的byModel维度才有意义——你能清楚看到同一个 Key 下不同模型各自的消耗占比。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数。模型对话入口在https://taotoken.net/models控制台在https://taotoken.net/consoleAPI Key 管理在https://taotoken.net/api-keys。如果你用 Claude Code 或 Codex 这类工具接入文档在https://taotoken.net/docClaude Code 专项说明在https://taotoken.net/claude-code-anthropic。这里要强调一个安全边界看板读取的是 OpenCode 已经落库的用量记录它不接触你的 API Key也不发起模型请求。Key 的配置发生在 OpenCode 那一侧看板只是把结果可视化。所以「数据不出本机」和「Key 通道正常」是两件独立的事前者由看板的只读设计保证后者由 OpenCode 的配置保证。前置检查清单检查项命令期望结果Node 版本node -v≥ v22.5.0数据库存在ls ~/.local/share/opencode/opencode.db文件存在npm 可用npm -v正常输出版本号端口空闲lsof -i :8787无输出表示 8787 可用端口那一条如果 8787 被占用后面用OC_PORT环境变量换一个就行不用改代码。3. 可复制配置零配置启动命令与 settings 片段这一节给的是能直接复制粘贴的内容。先克隆或下载oc-usage项目进入目录后安装依赖cd oc-usage npm installnpm install只会装react、react-dom以及构建期的 Vite不会拉数据库驱动因为后端用的是 Node 原生模块。装完之后生产模式启动npm start # 服务监听 http://localhost:8787开发模式Vite 热更新/api代理到 8787npm run dev零配置的含义是不设任何环境变量程序自动定位opencode.db自动选 8787 端口。如果你需要自定义用环境变量覆盖OC_PORT9000 OC_DB/path/to/opencode.db npm start两个变量的默认值和说明变量默认值说明OC_PORT8787HTTP 服务监听端口OC_DB~/.local/share/opencode/opencode.db数据库路径自动回退storage/子目录如果你用 Claude Code 或 Codex并且希望把模型通道统一到 TaoToken配置片段如下。Claude Code 的 settings 文件通常放在~/.claude/settings.json写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Codex 的auth.json一般在~/.codex/auth.json对应片段{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: gpt-5-codex }Cline 的 MCP 配置如果是走 OpenAI 兼容通道settings.json里对应{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: sk-你的TaoTokenKey, cline.openAiModelId: claude-sonnet-4-5 }三件套记牢Base URL 填https://taotoken.net/apiKey 填你在https://taotoken.net/api-keys生成的Model ID 按你要用的模型填。这三样配好OpenCode 或 Claude Code 产生的会话才会写进opencode.db看板才有数据可读。看板的字段映射关系也在这里说清楚方便你对照数据库字段理解界面看板字段数据库来源含义Cache Hittokens_cache_read缓存命中的输入 tokenCache Misstokens_input未命中缓存的输入 tokenOutputtokens_output模型输出 tokenReasoningtokens_reasoning推理 token部分模型有Costcost该会话记录的成本时间time_created/time_updated会话创建与更新时间后端server.js查询session表并左连接project表每次请求/api/summary时实时重算聚合所以你看板上的数字永远和最新的opencode.db一致不需要手动刷新数据库。4. 验证请求curl 健康检查与 /api/summary 成功结果服务起来之后第一件事是打健康检查确认数据库路径和会话数量curl http://localhost:8787/api/health期望返回类似{ok:true,db:/Users/you/.local/share/opencode/opencode.db,sessions:42}ok为true说明数据库以只读模式成功打开db是实际使用的路径sessions是读到的会话条数。如果sessions是 0要么是数据库里确实还没有记录要么是路径指错了。接着拉聚合数据curl http://localhost:8787/api/summary返回结构包含totals、byDay、byModel、byProject、sessions五部分。totals是总览{ totals: { sessions: 42, cost: 1.87, input: 128400, output: 39200, reasoning: 5100, cacheRead: 88400, cacheWrite: 12000 } }byDay是按天聚合适合画堆叠柱状图{ byDay: [ {date: 2026-07-15, input: 8200, output: 2400, cacheRead: 6100, cost: 0.12} ] }byModel是按模型聚合看板用它渲染甜甜圈图{ byModel: [ {model: claude-sonnet-4-5, input: 62000, output: 18000, cost: 1.42}, {model: kilo-auto/free, input: 4100, output: 900, cost: 0} ] }byProject按项目聚合带directory字段{ byProject: [ {project: oc-usage, directory: /Users/you/code/oc-usage, input: 22000, cost: 0.51} ] }sessions是原始会话列表会话页用它做搜索和过滤{ sessions: [ {id: sess_abc123, model: claude-sonnet-4-5, cost: 0.08, tokens_input: 3200, tokens_output: 1100} ] }浏览器打开http://localhost:8787左侧侧边栏在概览、每日、模型、项目、代理、会话之间切换。概览页顶部是总 token 大数和分桶条中间是模型和代理的占比甜甜圈每日页是堆叠柱状图加逐日明细表模型页是甜甜圈加逐模型明细项目页是排行条形图会话页支持按标题、项目、模型、id 搜索并按模型与代理过滤。验证「数据不出本机」有个简单办法启动看板后断开网络刷新页面所有图表照常渲染。因为前端静态资源和 API 都走 localhost没有任何外部请求。你也可以在浏览器开发者工具的 Network 面板里过滤只会看到localhost:8787的请求。关于成本显示 0 的情况要提前说明如果你用的是免费模型比如kilo-auto/freeOpenCode 在数据库里记录的cost字段本身就是 0看板如实展示不是统计错误。付费模型会正常显示金额。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。看板本身不涉及鉴权但你的 OpenCode 通道配置错了会间接导致数据库里没有新数据或者你在配置 Claude Code / Codex 时遇到下面这些错误。401 Unauthorized。这个报错出现在模型调用侧不是看板侧。原因通常是 Key 填错、Key 过期或者 Base URL 写成了带路径的形式。检查三件套Base URL 必须是https://taotoken.net/api不要多加/v1或结尾斜杠Key 从https://taotoken.net/api-keys重新复制注意前后不要有空格Model ID 要和通道支持的模型名一致。改完配置后重启 OpenCode 或 Claude Code让新配置生效。local proxy failed。这个报错一般出现在本地代理层说明请求根本没发出去。先确认网络能通到https://taotoken.net/apicurl -I https://taotoken.net/api如果这条命令超时是网络层问题不是配置问题。如果返回 200 或 401说明通道可达问题在客户端配置。另外检查是否有本地环境变量覆盖了 Base URL比如ANTHROPIC_BASE_URL被设成了别的值。reading choices 相关报错。这类错误通常出现在响应解析阶段提示读取choices字段失败。原因是客户端按 OpenAI 格式解析但返回结构不匹配或者 Model ID 填成了不兼容的模型。确认你用的 Model ID 和通道支持的格式一致Claude 系列走 Anthropic 格式GPT 系列走 OpenAI 格式不要混用。OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 报错说明它还在走默认的登录流程没有切到 API Key 模式。需要在settings.json里显式设置ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL覆盖掉 OAuth 路径。设置完可以用claude --version确认配置加载正常。看板侧Cannot find module node:sqlite。这是 Node 版本不够回到第 2 节升级到 22.5.0 以上。看板侧sessions: 0。数据库路径不对或者 OpenCode 还没产生记录。用OC_DB显式指定路径OC_DB/your/actual/path/opencode.db npm start端口被占用EADDRINUSE。换端口OC_PORT9000 npm start排查顺序建议先curl /api/health确认看板能读到数据库再确认 OpenCode 侧三件套配置正确最后看模型调用是否成功。看板和模型通道是两条独立的链路分开定位会快很多。6. 把看板接进你的日常编码流程看板跑起来之后我习惯把它挂在后台每天收工前扫一眼概览页。缓存命中率这个指标特别值得盯如果cacheRead占比持续偏低说明 prompt 结构可能不利于缓存复用调整系统提示词的写法往往能明显改善。项目维度的排行也能帮你发现哪个仓库的 Agent 调用最频繁从而判断是不是该给那个项目单独优化 prompt。如果你还没配 TaoToken 通道先去https://taotoken.net/api-keys生成 Key再按第 3 节的 settings 片段写进 Claude Code 或 Codex 配置。长期做编码 Agent 的话Coding Plan 入口在https://taotoken.net/coding-plan适合需要稳定调用量的场景。想先验证模型效果用模型对话页https://taotoken.net/models试几个 prompt确认返回正常再落到 OpenCode 里。看板本身不需要任何账号不依赖 TaoToken 也能跑——它只读本地数据库。TaoToken 的作用是让你的 OpenCode 有稳定、统一的模型通道从而持续产生可统计的用量数据。两者配合起来你既能看到消耗全貌又能控制调用入口数据始终留在本机。