## Oxelia51 是什么

Oxelia51 是一个**本地优先的个人 Token 记账本**：只需要改一行环境变量，让模型工具（Claude Code、Cursor、ChatGPT 等）的 API 请求经过一个代理，自动记录每一次调用的 Token、成本与异常，然后在仪表盘上多维度查看。

- **零侵入**：不装 SDK、不改代码，只改环境变量
- **多维统计**：按时间、供应商、Agent 拆解用量与成本
- **本地优先**：桌面应用数据全部保存在本地，账户用于跨设备同步与云端查看
- **开源**：MIT 许可证，代码全开源

> 想了解每个页面的作用、核心功能与计费逻辑，见完整的[使用指南](/docs/usage)；
> 安装时遇到系统提示的解决办法见[桌面应用 → 安装时遇到系统提示怎么办](/docs/desktop)。

## 云平台 5 分钟上手

云平台主要提供已同步数据的查看与跨设备恢复：

1. **注册并登录** → [注册](/auth/sign-up)，登录仅在使用云平台时必需
2. **桌面端接入代理**，把模型工具指向本地代理（见下）
3. **登录同步**：桌面端登录账户后可把本地账本同步到云端
4. **打开云平台仪表盘**，按供应商 / Agent 查看 Token 与成本统计

## 桌面应用（已发布 v0.1.x）

桌面应用已发布，支持 Windows / macOS / Linux，全功能本地使用、无需登录。详见[桌面应用](/docs/desktop)。

## 核心概念

- **供应商**：提供大模型的平台（Claude / DeepSeek / OpenAI / 智谱 …），代理路径里的 slug 决定请求转发给谁
- **Agent**：你使用的客户端软件（Claude Code / Cursor / CC Switch / Trae …），记录会自动按工具识别
- **代理**：介于模型工具与真实 API 之间的转发层，负责自动落账；密钥只转发、不落库


快速开始

> 桌面应用已发布（v0.1.x），支持 Windows / macOS / Linux。下载请前往[下载页](/download)或 GitHub Releases。

## 安装与系统要求

按平台提供以下下载方式（以实际发布为准，下载页只显示已构建验证的安装包）。下载页显示来自 GitHub Releases 的真实累计下载量；拉取失败时可点「重试」重新获取：

| 平台 | 下载方式 | 适用场景 |
| --- | --- | --- |
| Windows | 安装包 (.exe) | 日常使用，开始菜单/桌面快捷方式 |
| Windows | 便携版 (.zip) | 免安装，U 盘 / 绿色使用 |
| macOS | .dmg | Apple Silicon 与 Intel 分别提供 |
| Linux | .deb / .rpm / .AppImage | Debian / Ubuntu、Fedora / RHEL、通用发行版 |

## 安装时遇到系统提示怎么办

桌面应用目前**未购买代码签名证书**，Windows SmartScreen 会提示「未知发布者」；macOS 也会提示「无法验证开发者」。这是操作系统对未签名程序的**默认保护**，不是病毒。按平台处理：

### Windows

1. **「Windows 已保护你的电脑」**（SmartScreen）：
   点 **「更多信息」→「仍要运行」**，即可继续安装。
2. **「打开文件 - 安全警告（未知发布者）」**（浏览器下载后双击出现）：
   点 **「运行」**。
3. **便携版 (.zip)** 解压前如有拦截：右键文件 → **属性** → 勾选 **「解除锁定」** → 确定，再解压。

> 为什么会有这个提示：程序未签名、下载量少，Windows 暂时无法识别。属正常现象。Oxelia51 代码全开源、数据全本地，安装后可放心使用。

### macOS

双击 .dmg 提示「无法打开，因为无法验证开发者」时：
- 到 **系统设置 → 隐私与安全性** → 点 **「仍要打开」**；
- 或右键图标 → **「打开」** → 再点「打开」。

### Linux

- **.AppImage**：先给执行权限再运行：
  ```bash
  chmod +x oxelia51.AppImage && ./oxelia51.AppImage
  ```
- **.deb**：`sudo dpkg -i oxelia51.deb`，或双击用软件中心安装。
- **.rpm**：`sudo rpm -i oxelia51.rpm`。

## 配置本地代理

应用启动后会内置一个**本地代理**（默认端口 `17800`，监听 `127.0.0.1`）。**选择你使用的 LLM 供应商**，把模型工具的 Base URL 指向对应的代理地址：

```bash
# 注意：BASE_URL 必须含 /api/proxy 前缀，否则请求 404、不落账
# 使用 Anthropic（Claude Code / Anthropic SDK）：
export ANTHROPIC_BASE_URL="http://localhost:17800/api/proxy/anthropic"

# 使用 OpenAI 兼容供应商（Cursor / CC Switch / Trae 等），换成对应 slug：
export OPENAI_BASE_URL="http://localhost:17800/api/proxy/deepseek"
export OPENAI_BASE_URL="http://localhost:17800/api/proxy/openai"
export OPENAI_BASE_URL="http://localhost:17800/api/proxy/zhipu"
```

> **供应商 = 提供大模型的平台**，路径里的 slug 决定请求转发给谁。内置 **79 条供应商路由**：
>
> - **国内**：DeepSeek、智谱 GLM、通义千问、Moonshot (Kimi)、Kimi For Coding、豆包、腾讯混元、讯飞星火、MiniMax、百川、零一万物、商汤日日新、阶跃星辰、硅基流动、码云 AI、魔搭、百度千帆
> - **国际**：Claude (Anthropic)、OpenAI、Google Gemini、Mistral、xAI (Grok)、Groq、Cerebras、Cohere、Perplexity、SambaNova、Nebius、AI21、Hyperbolic、FriendliAI、NVIDIA、GitHub Models、MiniMax.io、Z.ai、StepFun AI
> - **第三方 / 聚合**：OpenRouter、Together AI、Fireworks AI、DeepInfra、Novita、Featherless、PPIO；另有第三方平台（API 中转站）33 家已按各官方文档核实接入，目录中标注「未接入」的暂未核实
>
> **Agent = 你使用的软件**（Claude Code / Cursor / CC Switch / Trae …），记录会自动按工具识别，并在「Agent 消耗」中统计。

之后每一次模型调用都会自动落账，无需其他操作。

## 悬浮统计卡片

顶栏的「悬浮统计」按钮可打开一块**钉在桌面上的透明玻璃卡片**，实时显示今日 Token、今日成本、请求数与今日模型 Top5 排名（前三名红色渐变，可在设置页勾选显示字段）。每 2.5 秒自动刷新，始终置顶、不进任务栏；拖动后位置自动记忆，设置页「重置位置」可恢复默认。点右上角 ✕ 隐藏，再次点顶栏按钮重新呼出。详见[使用说明](/docs/usage)。

## 数据与隐私

- 全部数据保存在本地，不经过任何云端
- API Key 只转发、不落库
- **多设备同步**：在「设置 → 多设备同步」登录云平台账户后，可把本地账本上传 / 下载到云端，多设备按事件去重合并；仅在你主动同步时数据上行，本地优先、云端是副本。


桌面应用

云平台是 Oxelia51 的在线版本：主要提供**已同步数据的查看与跨设备恢复**。桌面端负责日常本地记账与代理接入；登录云平台后可查看云端备份的 Token 统计，并在更换设备时恢复历史账本。

## 注册与登录

- **使用云平台需要注册登录**（数据要落云端）；但浏览文档、下载、社区不需要登录
- 注册与登录入口在[登录页](/auth/sign-in)与[注册页](/auth/sign-up)；登录成功后默认进入 /app 个人工作台
- 账户同样用于跨设备同步
- 忘记密码、账户与设备的关系等细节见[账户与登录](/docs/account)

## 数据怎么同步到云端

桌面端「设置 → 多设备同步」登录账户后，可把本地账本上传 / 下载到云端。同步只搬运**统计数据**（模型名、Token 数、成本、时间戳等），**不含 API Key、不含请求/响应内容**。

同步的去重规则：

- 每条账本记录有唯一 **event_id**，上传和下载都按这个 ID 去重，同一条事件不会在云端或本地重复计数
- 上传游标和下载游标分别独立维护，互不影响——上传中断后重试，不会重复上传已成功的部分
- 正常情况下"冲突数"应该恒为 0（冲突指同一 event_id 内容不一致，理论上不该发生，只是一层防御性检测）；如果你看到非 0 的冲突数，属于异常情况，欢迎反馈

多台设备登录同一账户后：**新设备下载 = 合并进本机账本**，不会覆盖已有数据；本机新产生的事件下次同步时上传到云端。

已同步的账本可在云平台「/app 设置 → 同步账本」查看设备列表与近 30 日汇总，并管理同步密钥（可断开某台设备的同步）。

## 按供应商与 Agent 查看

云平台个人工作台与桌面端口径一致：

- **供应商消耗**：按提供大模型的平台（Claude / DeepSeek / OpenAI / 智谱 …）聚合
- **Agent 消耗**：按你使用的客户端软件（Claude Code / Cursor / CC Switch / Trae …）聚合

## 支持的模型与供应商

跟桌面端代理是同一套路由表，完整列表（79 条内置路由 + 分类）见[桌面应用 → 配置本地代理](/docs/desktop)，这里不重复维护第二份列表以免过时。

成本按已配置的模型定价自动换算；未配置定价的模型成本按 0 计，供应商 / Agent 页的成本列会显示「未配置定价」，不虚构。

## 云端告警

云平台的预算超限、异常用量提醒走的是独立的后台批处理管道，跟桌面端本地告警不是同一套机制、触发延迟也不同，详见[设置预算告警](/docs/alerts)。


云平台使用

本文是从下载到精通的完整使用手册：下载安装、逐页界面介绍、核心功能、计费逻辑与常见教学场景。

## 一、下载与安装

到[下载页](/download)下载对应平台的应用并安装。启动后应用会**内置一个本地代理**（默认 `127.0.0.1:17800`），顶栏会显示「代理在线」。

**安装时遇到系统提示**（SmartScreen「Windows 已保护你的电脑」、macOS「无法验证开发者」等）的解决办法，见[桌面应用 → 安装时遇到系统提示怎么办](/docs/desktop)。

## 二、三步上手

1. **指向本地代理**：在「接入」页选择供应商，复制代理地址，配置到你的模型工具（详见下文）。
2. **自动落账**：之后的每一次模型调用，Token 与成本自动记录，无需任何操作。
3. **打开仪表盘**：在「总览」页按供应商 / Agent / 模型查看用量与成本。

## 三、界面总览（逐页介绍）

### 顶栏

- **标签导航**：总览 / 接入 / 供应商 / Agent / 告警 / 设置
- **代理状态**：左侧显示「代理在线 · :17800」；代理未运行时会显示「代理离线」，点击可直接跳转设置排查
- **悬浮统计按钮**（四宫格图标）：打开/隐藏悬浮卡片
- **主题切换**：深色（Cosmos）/ 浅色（Cozy）一键切换
- 右上角为窗口控制（最小化 / 最大化 / 关闭）

### 总览页

打开应用后默认进入总览，是「Token 花在哪」的全局视图：

- **页头**：标题 + 日期范围（全部 / 近7日 / 近30日 / 近90日），切换后下方统计联动
- **统计卡**：今日 / 近7日 / 近30日 / 累计 的 Token、请求数、成本
- **近 14 天用量趋势**：每日 Token 柱状图，定位异常时段
- **排行**：按供应商 / 按 Agent / 按模型三个排行，**前三名红色渐变**（由深到浅）一眼看清主要消耗
- **空态**：全新安装无数据时显示首次接入引导（选择供应商 + 复制地址/命令），不会展示空卡片

### 接入页

把模型工具接上代理的地方：

- **搜索**：按名称/简称搜索供应商（如 deepseek、kimi、zai）
- **三分类**：国外主流 / 国内主流 / 第三方平台，共 **80+ 个预设接入项**（内置 **79 条路由**，其余待接入）
- **自定义供应商**：预设之外的平台可在设置/接入页自填 API 地址与协议（openai / anthropic），地址只需填域名/路径部分、自动补全 `https://`，本地存储、即加即用；字段规则与常见报错见[自定义供应商接入](/docs/custom-provider)
- **每张卡片**：
  - **「复制地址」**（红色主按钮）：复制该供应商的本地代理地址
  - **「官网」**：跳转该供应商官网，核对最新价格与文档

### 供应商页

按 **LLM 平台**（Claude / DeepSeek / OpenAI / 智谱 …）聚合用量与成本。每一行显示：Token、请求数、成本、涉及模型数、最近使用时间。**点击某供应商**可下钻：该供应商被哪些 Agent 使用、各模型明细。

### Agent 页

按**你使用的软件**（Claude Code / Cursor / CC Switch / Trae …）聚合用量与成本。记录会自动按工具识别。**点击某 Agent** 可下钻：该 Agent 用了哪些供应商 × 模型。

> **供应商 = 提供大模型的平台；Agent = 你使用的客户端软件。** 这是 Oxelia51 统计的两个核心维度。

### 告警页

设置预算阈值，防止费用失控：

- **预算列表**：每条独立，显示每日预算、今日已用、使用比例与触发状态
- **添加预算**：维度可选 **全局 / 单个供应商 / 单个 Agent / 单个模型**，各自独立
- 超限时触发**系统通知**

### 设置页

- **本地代理**：监听地址说明（`127.0.0.1:17800` 固定，本地优先）
- **外观主题**：深色 Cosmos / 浅色 Cozy
- **悬浮卡片显示内容**：勾选卡片显示哪些数据（今日 Token / 今日成本 / 请求数 / 模型 Top5）；「重置位置」可恢复悬浮卡片的默认位置
- **模型定价**：成本核算用的单价表（USD / 1M tokens），可增删改、一键填入参考价、保存
- **模型价格参考**：**77 个模型**的参考价表（详见下节）
- **多设备同步**：登录云平台账户后上传 / 下载本地账本，多设备按事件去重合并
- **关于**：版本、官网、下载、反馈、GitHub、MIT 许可证

### 悬浮统计卡片

顶栏「悬浮统计」打开的桌面悬浮小窗：

- **始终置顶**、无边框、不进任务栏，可拖到屏幕任意角落，位置自动记忆（设置页「重置位置」可恢复默认位置）
- **实时刷新**：每 2.5 秒更新一次
- 显示今日 Token、今日成本、请求数、今日模型 Top5 排名（前三名红色渐变）；可在设置页勾选要显示哪些
- 点右上角 ✕ 隐藏，再点顶栏按钮重新呼出

## 四、核心功能详解

### 日期范围

总览、供应商、Agent 页顶部都可切换时间范围（全部 / 近7日 / 近30日 / 近90日），统计与排行随之联动。排行只统计所选范围内的数据。

### 排行红色高亮

所有排行的前三名用品牌红渐变标注（第1名最深 → 第3名最浅），第 4 名起恢复主题色。

### 模型价格参考与币种切换

设置页的「模型价格参考」是一张**选型参考表**：

- **77 个模型**，覆盖 Anthropic / OpenAI / DeepSeek / Kimi / 智谱 / 通义 / 豆包 / Gemini / xAI / Mistral / MiniMax / 阶跃 / 百川 / Meta 等
- 按 **输入价** 或 **综合成本**（= 输出×0.6 + 输入×0.4）排序，可升序/降序
- 可按供应商筛选
- **美元 / 人民币一键切换**：人民币按每日更新的汇率换算（来源：欧央行基准；离线回退上次成功值 / 内置参考值），汇率来源与日期标注在表下方
- 价格为**参考价**，以各厂商官网为准

### 模型定价与成本核算（计费逻辑）

**不同模型单价不同，按模型精确计费。** 具体逻辑：

```text
成本 = Σ( 该模型的 prompt_tokens ÷ 1M × 它的输入单价
          + 该模型的 completion_tokens ÷ 1M × 它的输出单价 )
```

- 每次请求记录 `model`（请求里的模型名）+ `prompt_tokens` + `completion_tokens`
- **按模型名精确匹配**「设置 → 模型定价」里的单价；供应商 slug 只决定转发给谁，计费与供应商无关
- **没配置定价的模型：成本按 0 计，界面显示「未配置定价」**，不虚构
- 「模型价格参考」表只是选型参考，**不会自动套到成本**；要算成本，需在「模型定价」里保存（可点「填入常见模型参考价」再改）

### 四维告警

预算可按 **全局 / 供应商 / Agent / 模型** 四个维度分别设置，每条独立生效。超限时触发系统通知（桌面本地，不依赖云端）。

### 悬浮卡片字段配置

设置页「悬浮卡片显示内容」可勾选卡片显示：今日 Token、今日成本、请求数、今日模型 Top5。勾选即时生效并保存。

### 多设备同步

在设置页「多设备同步」用云平台注册邮箱+密码登录，即可把本地账本上传到云端或从云端下载；换新设备时登录同一账户、从云下载即可恢复账本。多设备数据按事件去重合并；仅在你主动点同步时数据上行，本地优先、云端是副本。已同步的账本可在云平台「/app 设置 → 同步账本」查看设备列表与近 30 日汇总，并管理同步密钥（可断开）。

## 五、使用教学

### 首次接入（3 分钟）

1. 打开「接入」页，搜索你使用的供应商（如 deepseek）
2. 点**「复制地址」**，得到 `http://127.0.0.1:17800/api/proxy/deepseek`
3. 把地址配置到你的模型工具：
   - 支持环境变量的工具（Claude Code 等）：`export OPENAI_BASE_URL="http://127.0.0.1:17800/api/proxy/deepseek"`
   - 支持自定义 Base URL 的工具（CC Switch 等）：把地址粘进输入框
   > 地址**必须含 `/api/proxy/<供应商slug>` 前缀**，否则请求 404、不落账。
4. 发一条真实请求，回「总览」看是否落账

### 日常查看

- 总览页看今日/累计消耗与趋势，切换日期范围定位异常时段
- 想知道哪个平台最烧钱 → 供应商页；哪个工具最烧钱 → Agent 页
- 点某供应商/Agent 下钻看具体模型明细

### 成本核算

1. 设置页「模型定价」→「填入常见模型参考价」→ 按需修改 →「保存定价」
2. 之后总览、供应商、Agent 各处的成本都按这些单价实时换算
3. 想看美元还是人民币 → 在「模型价格参考」或总览成本处切换币种

### 设置告警

1. 告警页 → 添加预算
2. 选维度（如「模型」= deepseek-chat），填每日 Token 上限
3. 保存后，今日用量达到上限会弹系统通知

## 六、常见问题

- **没有数据**：确认请求真的走了代理（`BASE_URL` 是否含 `/api/proxy`），先用一条真实请求验证
- **成本显示「未配置定价」**：该模型还没在「模型定价」里填单价，填好并保存即可
- **供应商没有**：预设目录覆盖 80+ 接入项（内置 79 条路由）；遗漏的可提需求，或在设置/接入页添加自定义供应商（自填 API 地址与协议）
- **安装被系统拦截**：见[桌面应用 → 安装时遇到系统提示怎么办](/docs/desktop)
- 更多问题见[FAQ](/docs/faq)，报错信息对照见[常见错误排查](/docs/troubleshooting)


使用指南

内置 79 条供应商路由覆盖不到的平台，可以在「接入」页手动添加自定义供应商——填几个字段，本地保存，立即生效。

## 什么时候需要自定义供应商

- 你用的是某个内置目录里没有的中转站 / 自建网关
- 你自己搭了一个 OpenAI 兼容或 Anthropic 兼容的服务（比如本地跑的模型网关）
- 内置路由的上游地址变了，想临时用自定义的顶一下

## 怎么添加

在「接入」页或设置页找到「自定义供应商」区块，填四个字段：

| 字段 | 说明 | 规则 |
| --- | --- | --- |
| **名称** | 展示用的名字，随便填 | 1–50 个字符 |
| **Slug** | 代理路径里的标识，比如 `myapi` → 代理地址是 `/api/proxy/myapi` | 只能用小写字母、数字、连字符，2–31 位，不能和内置供应商的 slug 重名（重名会报 409 冲突） |
| **API 地址** | 上游服务的地址 | 只需要填域名/路径部分（如 `api.example.com/v1`），会自动补全 `https://`；如果已经带协议前缀会原样保留 |
| **协议** | `openai` 或 `anthropic` 二选一 | 决定代理**怎么解析响应来记账**（提取 token 用量、模型名的字段格式不同）；不影响请求本身的转发方式 |

保存后立即生效，不需要重启应用。

## 关于「协议」字段的一个常见误解

**协议字段只影响记账时怎么解析响应，不会把你的请求从一种协议"翻译"成另一种协议。** 代理对请求本体是纯透传——路径、method、body、query 原样转发给上游，不做任何协议转换。

也就是说：如果上游服务本身不支持某个端点（比如没实现 OpenAI 较新的 Responses API `/v1/responses`，只支持 Chat Completions `/v1/chat/completions`），选哪个协议字段都救不了——上游会直接因为端点不存在而报错。这种情况要去检查客户端（如 Codex / CC Switch）的协议模式设置是否匹配上游实际支持的端点，跟 Oxelia51 这边的配置无关。详见[常见错误排查](/docs/troubleshooting)。

## API 地址的限制

出于安全考虑（防止代理被用来访问内网地址），自定义供应商的地址有几条硬性规则：

- 必须是 `https://`；`http://` 只允许 `127.0.0.1` 或 `localhost`（给本机自建服务用的例外）
- 地址不能解析到内网 / 回环 / 链路本地地址（写入时会做校验并拒绝），本机例外除外
- 地址里不能带用户名密码、query 参数或 fragment

如果保存时提示地址无效，先检查是不是踩了这几条规则之一。

## 保存失败怎么办

| 报错 | 原因 | 解决 |
| --- | --- | --- |
| Slug 格式错误 | 用了大写字母、下划线，或长度不对 | 改成小写字母/数字/连字符，2–31 位 |
| Slug 冲突（409） | 跟某个内置供应商的 slug 重名 | 换一个没被占用的 slug |
| 地址无效 | 不是合法的 `https://`（或本机 `http://`）地址，或带了不允许的部分 | 按上面「API 地址的限制」核对 |
| 地址被拒绝（内网地址） | 解析出来的 host 是私有/回环地址，但又不是 `127.0.0.1`/`localhost` | 确认你填的是真实可从公网访问的上游地址 |

## 删除

自定义供应商可以随时删除；内置供应商不能通过这个入口删除（也不需要，内置的不占用你的自定义额度）。


自定义供应商接入

统计页把每一次模型调用的 Token 与成本，按多个维度整理，方便看清"Token 花在哪"。想先了解每个页面长什么样，见[使用指南](/docs/usage)；这篇专注讲**怎么读懂这些数字**。

## 成本是怎么算出来的（实操例子）

Oxelia51 按模型精确计费，公式：

```text
成本 = prompt_tokens ÷ 1,000,000 × 该模型输入单价
     + completion_tokens ÷ 1,000,000 × 该模型输出单价
```

举个例子：假设 `deepseek-chat` 的单价是输入 $0.14 / 1M、输出 $0.28 / 1M（USD，每 1M tokens），一次请求消耗 `prompt_tokens=50000`、`completion_tokens=20000`：

```text
成本 = 50000 / 1,000,000 × 0.14 + 20000 / 1,000,000 × 0.28
     = 0.007 + 0.0056
     = $0.0126
```

几个关键点：

- **按模型名精确匹配单价**，供应商只决定转发给谁，跟计费无关（同一个供应商下不同模型价格可以完全不同）
- 单价来自「设置 → 模型定价」里你自己保存的值；**没配置的模型成本按 0 计，界面显示「未配置定价」**，不会用参考价瞎凑
- 「模型价格参考表」只是选型时看的市场参考价，**不会自动套用到你的成本计算**——要让某个模型真正参与计费，得先在「模型定价」里保存它的单价

## 趋势图怎么看

总览页的「近 14 天用量趋势」是按天聚合的 Token 柱状图。几个读图技巧：

- 某天突然冒高 → 大概率是跑了批量任务或某个 Agent 密集调用，可以切到「Agent 页」按当天时间范围核对
- 连续几天是 0 → 检查代理是否在线、`BASE_URL` 有没有失效（比如系统重启后忘记重新 export 环境变量）
- 只看某个时间段异常 → 切换日期范围到「近 7 日」，排行会跟着联动，只统计该范围内的数据

## 为什么某个供应商 / 模型不在排行里

排行只展示**有真实用量**的条目：0-token 的内置路由占位不会出现在用量排行里（避免"用过的"和"没用过但内置支持的"混在一起，误导判断）。如果你确实用了某个供应商但排行没显示，先检查请求是否真的落账了（见下节）。

## 下钻操作

- **供应商页**点某一行 → 展开该供应商被哪些 Agent 使用、各模型的明细
- **Agent 页**点某一行 → 展开该 Agent 用了哪些供应商 × 模型
- 下钻明细里同样支持按日期范围筛选

## 币种切换

- 「模型价格参考表」和总览的成本展示都支持 **USD / CNY 一键切换**
- 人民币汇率**每日从欧央行基准更新**；离线或拉取失败时，回退到上次成功获取的汇率，再不行则用内置参考值兜底
- 汇率来源与更新日期标注在价格表下方，可以自行核对

## 为什么数据是空的

刚接入代理、还没有任何请求经过时，统计页为空属正常。请依次检查：

1. 环境变量是否正确指向代理地址（`BASE_URL` 必须含 `/api/proxy/<供应商slug>` 前缀）
2. 请求是否真的走了代理——顶栏「代理在线」不代表请求经过了它，得看你的模型工具配置是否生效
3. 时间范围是否覆盖了请求发生的时间（默认视图可能是"近 7 日"，更早的测试数据切不到对应范围会看不到）

> 排障时建议先用一条真实请求验证，再看仪表盘是否出现数据。更多故障排查见[常见错误排查](/docs/troubleshooting)。


查看统计数据

告警用于在 Token 消耗超出预算或出现异常时及时提醒，避免费用失控。桌面端和云平台走的是两套完全独立的告警管道，触发的**实时性不一样**——这篇讲清楚差别，避免设完预算之后困惑"为什么没有立刻收到通知"。

## 设置预算阈值

在告警页添加预算，可选四个维度，各自独立生效：

- **全局**：所有请求每日累计 Token 不超过某个数
- **供应商**：某个平台（如 deepseek）每日消耗上限
- **Agent**：某个客户端工具（如 Claude Code）每日消耗上限
- **模型**：某个具体模型（如 deepseek-chat）每日消耗上限

同一个维度可以设多条（比如给两个不同模型分别设阈值），互不影响。

## 桌面端：近实时（约 15 秒）

桌面应用的预算检查完全在本地进行，不依赖网络：

- 告警页停留时**每 15 秒自动轮询一次**，实时对比「今日已用 Token」与预算阈值
- 一旦某条预算的使用量达到阈值，立刻触发**系统通知**（桌面本地通知，不经过云端）
- 添加/删除预算后会立即刷新一次，不用等到下一个 15 秒周期

也就是说，桌面端预算超限后，最多 15 秒左右就能看到通知——不是秒级实时，但足够及时。

## 云平台：批处理，间隔 5 分钟

云平台的预算检查、异常检测跑在一个独立的后台分析引擎里，**每 5 分钟处理一次**（系统定时任务，带随机延迟打散负载），不是请求发生时立刻计算的。具体做了什么：

1. **聚合**：把这 5 分钟内新增的 Token 事件按模型汇总
2. **计算成本**：按模型定价换算成本
3. **异常检测**：把当天用量和昨天同一模型/项目的用量对比，超过默认阈值（3 倍）视为异常
4. **预算检查**：累计本月成本，达到预算阈值的比例即触发
5. **分发通知**：站内消息 + 邮件（如果绑定了邮箱并开启通知）

**这意味着**：云平台的告警最坏情况下会有几分钟延迟——设完预算阈值后跑一次超限请求，不会立刻收到邮件/站内通知，等下一个 5 分钟周期跑完才会触发，属正常现象，不是故障。

## 云平台告警怎么看

- **站内通知**：登录云平台后，在站内消息中心查看
- **邮件**：账户设置里绑定邮箱、开启邮件通知后，触发时会发送邮件

## 该用桌面端还是云平台告警

- 只用桌面应用、不关心多设备同步 → 桌面端预算告警就够了，近实时、不用联网
- 需要多设备同步、或者希望不开电脑也能收到邮件提醒 → 需要登录云平台账户同步账本，配合云端告警
- 两者可以同时开——桌面端管本机实时提醒，云端管跨设备汇总后的预算/异常提醒

> 如果设了预算却完全没收到过通知，先确认对应维度确实产生了达标的用量，再看[常见错误排查](/docs/troubleshooting)。


设置预算告警

## 为什么需要账户

使用 Oxelia51 **不强制注册**：桌面应用全功能本地使用，文档、下载、社区全部匿名开放。

账户仅在以下场景需要：

- **跨设备使用 / 同步**：桌面端登录账户后，多台设备之间同步账本（按事件去重合并）
- **云平台**：数据落云端时，账户用于识别数据归属

## 注册

在[注册页](/auth/sign-up)填邮箱和密码即可完成注册。注册后系统会发一封验证邮件到你的邮箱，建议尽快点击链接完成验证。

## 忘记密码

在[登录页](/auth/sign-in)点击「忘记密码」，输入注册邮箱后会收到一封重置密码邮件：

1. 点击邮件里的链接进入重置页面
2. 设置新密码
3. 用新密码重新登录

重置链接具有时效性，过期需要重新发起一次。

## 修改密码

已登录状态下，在云平台的账户设置里输入旧密码并设置新密码即可，不需要走邮箱验证。

## 账户与设备的关系

一个账户可以在**多台设备**上登录桌面端。每台设备都有独立的本地账本，登录同一账户后：

- **上传**：把本机的账本事件同步到云端
- **下载**：把云端已有的事件（含其他设备上传的）合并进本机

账本事件用唯一 ID 去重，多台设备之间不会重复计数，也不会互相覆盖。详见[云平台使用](/docs/cloud)。


账户与登录

汇总排查代理接入过程中最常遇到的报错和现象，按"症状 → 原因 → 解决"整理。更基础的问题先看 [FAQ](/docs/faq)。

## 404：模型名称不存在 / 分组下暂无可用渠道

**症状**：用 Codex 之类走 Responses API 的客户端接第三方中转站时，报类似「当前无法提供该模型：模型名称不存在，或您所在分组下暂无可用渠道」的 404。

**原因**：本地代理对请求做纯透传，不会自己生成这类报错——这是**上游供应商自己的网关**返回的。常见情况是客户端用的协议模式（如 OpenAI 较新的 Responses API `/v1/responses`）上游没有实现，只支持更早的 Chat Completions（`/v1/chat/completions`），上游网关找不到匹配的渠道就会报这种"听起来像模型问题、实际是端点问题"的错。

**解决**：在客户端（如 CC Switch）里把该供应商的协议格式从「responses 原生」切换成「Chat Completions」。这不是某一家供应商的个例——任何不支持 Responses API 的上游都会这样，跟代理本身无关。

## 请求发了，但总览页没有数据

排查顺序：

1. **`BASE_URL` 是否含 `/api/proxy/<供应商slug>` 前缀**——少了这个前缀，请求会 404，也不会落账
2. **代理是否在线**——桌面顶栏应显示「代理在线 · :17800」，显示离线的话检查应用是否在后台运行
3. **请求是否真的发出去了**——先用一条肯定会成功的真实请求测试，而不是直接怀疑统计有问题
4. **总览页的日期范围**——默认可能是"近 7 日"，更早的测试数据切不到对应范围会看不到

## 非 2xx 响应（如限流、鉴权失败）为什么没被记账

这是设计如此，不是 bug：**只有正常返回的调用才会落账**，429 限流、401/403 鉴权失败这类非 2xx 响应不会写入统计——避免这些错误请求污染你的用量数据。如果你的调用大量失败，问题出在上游（比如 API Key 或额度），而不是代理没记账。

## 成本显示「未配置定价」

该模型还没有在「设置 → 模型定价」里保存单价。去设置页把它的单价填上（可以先点「填入常见模型参考价」再按需修改），保存后旧记录和新记录都会按新单价重新计算显示。

## 自定义供应商保存失败

见[自定义供应商接入 → 保存失败怎么办](/docs/custom-provider)，常见原因是 slug 格式不对、跟内置供应商重名，或者地址不满足安全校验规则。

## 设了预算，但没收到通知

- **桌面端**：预算检查大约每 15 秒轮询一次，正常情况下超限后很快会有系统通知；先确认对应维度（全局/供应商/Agent/模型）确实产生了达标的用量
- **云平台**：走的是独立的后台批处理，**每 5 分钟**才处理一次，收到通知有延迟属正常现象，不是故障

详见[设置预算告警](/docs/alerts)。

## 悬浮卡片数据看起来没更新

悬浮卡片每 2.5 秒自动刷新一次；如果长时间没变化，先确认代理在线、且这段时间内确实有请求发生。卡片位置跑丢了可以在设置页点「重置位置」恢复。

## 多设备同步后数据对不上

同步基于事件唯一 ID 去重，正常情况下"冲突数"应该恒为 0。如果你观察到明显的数据缺失或重复，先确认两台设备用的是同一个账户登录，再检查同步时是否有网络错误提示；仍然异常的话，欢迎带上设备信息反馈给我们（见 [FAQ → 怎么反馈问题](/docs/faq)）。

## 安装被系统拦截（SmartScreen / 无法验证开发者）

不是病毒，是应用未购买代码签名证书导致的默认保护。详细处理步骤见[桌面应用 → 安装时遇到系统提示怎么办](/docs/desktop)。


常见错误排查

## 基础

**Q：Oxelia51 和 Langfuse 是什么关系？**
A：Oxelia51 的云平台基于 Langfuse（MIT）fork 并深度定制，融合了 Helicone 的代理记账理念，形成自己的产品。桌面应用为全新本地应用。

**Q：一定要注册才能用吗？**
A：不需要。桌面应用全功能本地使用；文档、下载、社区匿名开放。登录仅在跨设备同步、云平台时出现。

**Q：数据安全吗？**
A：桌面应用数据全部本地；云平台数据加密存储。API Key 只转发、不落库。

**Q：桌面应用什么时候发布？**
A：已发布 v0.1.x，支持 Windows / macOS / Linux。在下载页或 GitHub Releases 获取。

## 使用

**Q：改一行环境变量具体改哪里？**
A：在模型工具的配置文件里设置 `ANTHROPIC_BASE_URL` 或 `OPENAI_BASE_URL` 指向本地代理的对应供应商地址即可，见[桌面应用](/docs/desktop)。例如 DeepSeek 用 `export OPENAI_BASE_URL="http://127.0.0.1:17800/api/proxy/deepseek"`（Base URL 必须含 `/api/proxy/<供应商slug>` 前缀）。

**Q：会不会影响我的模型调用？**
A：代理只做转发与落账，不改写请求内容，正常调用不受影响。

**Q：支持哪些模型？**
A：内置 79 条供应商路由，覆盖国内（DeepSeek、智谱、通义、Kimi、豆包、混元、星火、MiniMax、硅基流动…）、国际（Anthropic、OpenAI、Gemini、Mistral、Grok、Groq…）与聚合平台（OpenRouter、Together…），另有 33 家第三方平台（API 中转站）已接入；内置 77 个模型参考价，支持美元/人民币切换。

**Q：用 Codex 接第三方中转站，报 404「模型名称不存在，或您所在分组下暂无可用渠道」，是代理的问题吗？**
A：不是，是上游供应商自己返回的——常见原因是客户端用了 OpenAI 较新的 Responses API，但上游只支持 Chat Completions。把客户端的协议格式切换成 Chat Completions 即可解决。完整排查过程见[常见错误排查](/docs/troubleshooting)。

**Q：多台设备怎么同步账本？**
A：在桌面端「设置 → 多设备同步」用云平台注册邮箱+密码登录，即可上传 / 下载本地账本；多设备按事件去重合并，仅在你主动点同步时数据上行，本地优先、云端是副本。已同步的账本可在云平台「/app 设置 → 同步账本」查看，并管理同步密钥（可断开）。

## 部署

**Q：可以自己部署吗？**
A：暂不支持一键自托管；源码可自行构建部署（生产运维配置见仓库 deploy/ 目录）。

**Q：桌面应用和自托管有什么区别？**
A：桌面应用是面向个人、零部署的本地应用；自托管是自己部署云平台。两者数据模型一致，通过账户同步互通。

## 反馈

**Q：怎么反馈问题或提需求？**
A：站内反馈、邮箱 receive@oxelia51.com，或 GitHub Issues / Discussions。
