桌面客户端完全指南

这是什么

OpenTokenRouter Desktop 是面向网关管理员与开发者的桌面客户端，解决三件事：

多环境管理：在同一个客户端里维护测试、预发、生产或客户实例等多个网关，凭据只进系统钥匙串，可一键切换、克隆、导入导出。
一键配置本机 CLI：把「环境 + 模型 + Codex CLI / Claude Code」组合应用为本机可用状态，切换环境后重新应用即可生效，不覆盖你现有的 OpenAI / Claude 配置。
计价管理：从环境拉取当前计价作为基线，编辑模型价格与分组倍率，试算费用后一键下发到任意环境；任何下发都可回滚。

本文是《客户端配置指南》的进阶篇：那一篇讲手工配置，这一篇讲桌面客户端全流程。

下载与安装

打开官网「下载」页，按平台获取安装包：macOS（DMG）、Windows、Linux。
macOS：打开 DMG，把 OpenTokenRouter 拖入 Applications。若 Gatekeeper 拦截（安装包为未签名预览版），打开 系统设置 → 隐私与安全性，点击「仍要打开」。
Windows：运行安装程序，保持默认的按用户安装。若 SmartScreen 提示，点击 更多信息 → 仍要运行。
安装包来源请以官网下载页为准，不要运行来路不明的副本。

核心概念

概念	说明
环境 Environment	一个网关连接：显示名 + 网关地址 + 端点类型（远程 HTTPS / 本机回环）+ 钥匙串凭据 + 可选默认模型
计价方案 Pricing Profile	一组计价配置的命名快照：模型定价表、分组倍率等；可另存、克隆、加载、对比、删除
目标客户端 Target	可一键配置的本机 CLI：`codex`、`claude`
一键配置	把「环境 + 模型 + 目标客户端」应用为独立 profile / 隔离配置，不触碰你的现有配置
下发 Deploy	把编辑器中的计价写入网关环境，写前预览、写后可回滚

环境管理

添加环境

在「环境管理」页点击 添加环境，填写：

环境名称：例如「生产 / 测试 / 客户 A」。
网关地址：生产环境必须使用 HTTPS；仅 localhost / 127.0.0.1 可使用 HTTP。地址不能包含用户名密码、路径或查询参数。
API Key：只写入系统钥匙串，不会出现在本地文件或导出内容中。
默认模型（可选）：作为该环境的默认值，应用配置时仍可修改。

保存后建议点击探测，客户端会请求服务器信息并显示连通状态、延迟、模型数；探测失败仍可保存，但会标记为「探测失败」。

活动环境

每个环境可设为活动。所有一键配置与计价编辑默认指向活动环境；切换记录会写入本地审计日志。

克隆、导入与导出

克隆：复制一个环境作为新环境，便于快速搭建相似实例。
导出：导出为 JSON，包含名称、地址、类型、默认模型等，不包含 API Key，可安全分享或备份。
导入：粘贴导出的 JSON；凭据不会随文件导入，导入后需为各环境补充 API Key（状态显示「缺凭据」）。

删除环境

删除前请确认：环境将从列表移除，系统钥匙串中的对应凭据也会一并删除。需要保留时先导出。

一键配置 Codex CLI 与 Claude Code

准备工具

在「准备工具」步骤中，客户端会检测本机是否已安装 codex / claude；未安装时可一键安装官方 CLI。

选择模型

选择环境后，客户端拉取该环境可用模型，并按目标客户端端点类型过滤（Codex 需要 openai-response 端点，Claude Code 需要 anthropic 端点），避免选到协议不兼容的模型。

预览与应用

应用前先预览将写入的配置内容，确认后应用。应用方式：

Codex CLI：使用独立 OpenTokenRouter profile，不修改 ~/.codex/config.toml，通过 --profile opentokenrouter 启动。
Claude Code：使用独立的 CLAUDE_CONFIG_DIR，不覆盖现有 Claude 登录。

每次应用前客户端会自动建立本地备份（见「备份与回滚」）。

切换环境

在「环境管理」切换活动环境后，重新执行一次应用即可把 Codex / Claude Code 指向新环境；应用前可以先预览确认目标地址。

计价管理

拉取计价

在「计价管理」页选择目标环境，点击 拉取计价，客户端读取该环境的计费白名单（ModelRatio / ModelPrice / GroupRatio / GroupGroupRatio / QuotaPerUnit 等）。

保存基线方案

拉取结果可直接 保存为基线方案，作为后续批量调整的起点；方案列表支持新建、保存、加载、删除与对比（对比时密钥类字段显示为 REDACTED）。

编辑器

模型定价表：按模型维护单价（$/1M）、倍率、缓存读倍率、缓存写倍率、输出倍率、图像倍率与计费模式。
分组倍率：按分组维护充值倍率与说明。

费用试算

试算器输入：输入 tokens、输出 tokens、缓存命中 tokens、缓存写入 tokens、分组倍率。点击试算得到预估 quota 与预估费用；计算口径与网关 service/text_quota.go 对齐。

下发与回滚

把编辑器中的方案下发到目标环境前，客户端会先展示将写入的配置项；确认后逐 key 下发，失败可重试。每次下发前自动建立计价快照，需要时从「下发与回滚」区域 一键回滚。

备份与回滚

「备份与回滚」页展示配置事务历史：每次应用 / 下发前自动建立本地备份，支持 回滚到此备份。注意：回滚只恢复配置文件，不恢复已撤销的密钥；若当前文件已被外部修改，客户端会提示无法自动覆盖。

连接诊断

「连接诊断」页显示平台与架构、本机工具检测、安全存储与配置路径、固定终端命令，可一键 刷新诊断。诊断信息不包含 API Key，可放心截图发给支持人员。

安全说明

环境凭据只进系统钥匙串，本地存储、导出文件、审计日志与计价快照均不含密钥。
导入导出、方案对比不会泄露密钥（敏感字段显示 REDACTED）。
活动环境切换、下发、回滚等操作写入本地审计日志，便于回溯。

版本更新

客户端会自动检查更新：

启动时静默检查一次；「关于客户端」页也可随时手动点击 检查更新。
发现新版本后点击 下载更新，安装包会下载到 ~/.opentokenrouter/downloads/。
下载完成后点击 打开安装包，由系统安装器完成升级（macOS 拖入应用程序 / Windows 运行安装程序）。

更新服务器默认为官网网关地址，可在「关于客户端」→「版本更新」中修改（需指向 OpenTokenRouter 网关的 /api/status）。

未签名预览版在 macOS 上需要右键打开或「仍要打开」，Windows 在 SmartScreen 中选择「仍要运行」。

常见问题

macOS 打不开 / 提示已损坏

安装包为未签名预览版：系统设置 → 隐私与安全性 → 仍要打开；确认下载来源是官网下载页。

Windows 被 SmartScreen 拦截

点击「更多信息」→「仍要运行」。

添加环境后探测失败

检查网关地址协议（生产必须 HTTPS）、地址是否带路径或查询参数、API Key 是否有权限；也可以用「连接诊断」页核对本机网络与代理设置。

模型列表为空

确认活动环境已保存凭据且探测成功，并检查该环境是否有可调用模型（首页实时价格中标记 Live settlement 的模型）。

应用后 CLI 仍走旧环境

切换活动环境后需要重新执行一次「应用」；应用前先预览，确认目标地址与模型正确。

桌面客户端完全指南：环境、一键配置与计价管理