安装与升级
- 下载
TokenMoney-Setup-0.2.0-preview.3.exe，用页面提供的 SHA-256 校验值核对文件。官网下载器会在下载完成前自动校验。 - 双击安装，选择当前用户目录（默认
%LOCALAPPDATA%\TokenMoney），不需要管理员权限。安装包自带运行环境，无需另装 Node.js。 - 测试版尚未代码签名，Windows SmartScreen 可能提示“未知发布者”。请确认校验值一致后再选择“仍要运行”。
从旧版升级时，请先在托盘菜单退出、卸载旧版，再安装新版。卸载会保留账本与加密凭据，重装后可以继续使用。
托盘与费用卡
运行后，右下角通知区域会出现橙色 T 图标。鼠标停留会展开费用卡，显示今日参考费用、最近一次调用和本月预算进度；单击可固定。右键菜单可以打开完整账单、管理 API Key、切换外观与币种。
外观支持托盘、气泡和天气式卡片三种样式，浮层可拖动并记住位置，全屏应用中自动隐藏。“最近记录”的时间按你在设置中选择的时区显示。
接入自己的应用
TokenMoney 不会自动读取电脑上所有应用的用量。你需要让自己的应用经过本地网关调用模型，网关负责注入真实密钥、转发请求并记账。
- 在“管理本地 API Key”中选择服务商，填写接口地址并保存 Key。Key 使用 Windows DPAPI 按当前用户加密保存。
- 点击账户旁的“接入”，复制接入配置。
- 把配置放进应用的后端配置中。配置里包含本机接入令牌，不要放进浏览器前端或提交到代码仓库。
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:4317/proxy/openai/v1",
api_key="tokenmoney-local", # 占位值，真实 Key 由网关注入
default_headers={
"x-tokenmoney-key": "本机接入令牌",
"x-tokenmoney-account": "保存账户的 ID",
"x-tokenmoney-project": "my-app", # 可选：按项目归类
},
)项目名最长 160 个字符，不能包含换行等控制字符；格式不正确的请求会在发往厂商之前被拒绝，不会产生费用。网关支持流式输出，长时间推理不会因为总时长被截断：只有上游连续 5 分钟没有任何数据时才会判定超时。
自定义服务商
目录里没有的渠道（公司内部网关、私有部署、兼容接口的第三方服务）可以选择“自定义服务商”添加。连接参数与 Key 一起加密保存。
| 字段 | 填写内容 |
|---|---|
| 服务商标识 | 小写英文标识，如 my-company，接入地址中的 /proxy/my-company/v1 即由它决定 |
| Base URL | 完整基础地址，包含版本前缀，不包含 /chat/completions 等具体路径；需使用 HTTPS，本机地址可用 HTTP |
| 接口协议 | openai、anthropic 或 gemini，必须与实际接口格式一致 |
| 认证方式 | Bearer、x-api-key、x-goog-api-key、自定义请求头，或本机无认证 |
| 默认模型 | 可选；调用未指定模型时使用 |
| 单价 | 可选；人民币或美元，每百万 Token 的输入、输出、缓存读取与写入价格。缺少实际产生的分类时，该条费用保持待定价 |
自定义或修改过地址的连接不会沿用原厂的内置价格，避免把第三方渠道误按官方价计算。
上报用量（不经过网关）
如果应用已经直接调用厂商接口，也可以在拿到响应后把用量上报给本地引擎。每条记录必须带唯一的 id，重复上报同一个 id 会被识别为重复而不会重复记账。
POST http://127.0.0.1:4317/api/usage
x-tokenmoney-key: 本机接入令牌
content-type: application/json
{
"id": "req_20261024_0001",
"provider": "openai",
"model": "gpt-6.1-sol",
"project": "my-app",
"response": { ...厂商返回的原始 JSON... }
}优先传厂商原始响应 response，引擎会按协议解析用量和实际服务档位。也可以直接传 usage：input（未命中缓存的输入）、cached、writeShort、writeLong、output、reasoning，各输入分类互不重叠，reasoning 包含在 output 之内。
完整账单
从托盘菜单选择“打开完整账单”，程序会生成一个一次性的登录链接并用默认浏览器打开。链接两分钟内有效、只能使用一次；登录后浏览器只保存一个仅限本机面板使用的会话，接入令牌本身不会出现在浏览器里。
账单面板可以按分钟、小时、日、月查看趋势，按模型和项目拆分，切换展示币种，导出 CSV，并手动刷新参考汇率。统计在本地数据库中完成，记录数量再多也不会丢失历史数据。
如果面板提示“会话已失效”，回到托盘菜单再点一次“打开完整账单”即可。
计价口径
- 价格来源：内置各厂商公开标价，并在每条记录里保存当时使用的价格快照；之后调整价格不会改写历史记录。
- Token 分类：普通输入、缓存读取、缓存写入、输出分别按对应单价计费；推理 Token 属于输出的一部分，只计一次。
- 服务档位：以厂商响应中实际返回的档位为准（如优先、弹性、错峰）；请求头声明的档位只作为补充，冲突时会在记录中标注。
- 精确计算：金额用整数精确累加，不存在浮点误差；换算成本币时按每条记录当时的汇率快照计算。
- 汇率：参考汇率来自公开数据源，可手动刷新，仅用于展示，不代表你的银行或信用卡实际结算汇率。
不完整的调用
| 状态 | 含义 | 是否计入预算 |
|---|---|---|
| 完整 | 厂商返回了最终用量 | 是 |
| 已截断 | 因长度上限等原因提前结束，但厂商已报告用量并计费 | 是 |
| 部分用量 | 流中断前已收到部分用量，按已知部分估算（实际费用只会更高） | 是，按下限计 |
| 用量不完整 | 没有收到可用的用量信息，例如退出程序时仍在进行的请求 | 否，标记为待确认 |
所有金额都是基于公开价格的参考估算，最终以厂商账单为准。工具调用、税费、赠金和折扣未全部纳入。
功能与边界
- 目前只提供 Windows 版本；已在 Windows 11 验证，Windows 10 真机与多屏、各 DPI 的完整验收仍在进行。
- 预算只做提醒，不会拦截调用。
- 超出已核验范围的模型、上下文长度、模态或档位会显示为“待定价”，而不是按猜测的价格计算。
- Embedding、Rerank、实时音视频等暂未纳入计价；AWS SigV4、Google 服务账户等签名认证尚未支持。
- 退出程序会停止本地网关，经它调用模型的应用将无法继续请求。
- DPAPI 能防止其他 Windows 用户和换机后读取密钥，但不能隔离同一登录用户下运行的恶意程序。
常见问题
端口 4317 被占用
在“外观、币种与预算”中修改端口并重新启动引擎，同时更新已接入应用的网关地址。
保存的账户显示“无法解密”
通常是凭据库来自另一台电脑或另一个 Windows 用户。DPAPI 密文只能由原用户解密，请删除该账户后重新添加 Key，其他账户不受影响。
某条记录显示“待定价”
说明该模型或档位不在已核验的价格范围内。Token 数量仍会完整记录；你也可以为该账户填写自定义单价。