XwX Deck 用户手册
最后核对日期：2026-10-14 适用版本：XwX Deck 1.1.1
本文对应 main 当前源码。 本轮修改尚未发布安装包。 已发布包的功能以对应标签为准。
页面
- Trace：开始或停止追踪，查看累计 Token、费用、吞吐和客户端接入状态。
- 模型：管理 Claude / ChatGPT 使用的模型服务与模型选择。
- 仪表盘：在独立原生窗口中查看请求详情、会话和筛选结果。
- 设置：管理服务连接、主题、Trace 外观、数据目录、日志目录、开机启动与版本信息。
独立版不提供客户端配置同步、工具页、ChatGPT 对话诊断或 Excel 转 Markdown。
设置页底部的“诊断与修复”集中显示当前问题、最近一次失败与处理操作，也可检查 Trace 记录、恢复客户端连接或重置应用数据。重置会清理设置、缓存、Trace 和日志；Claude / ChatGPT 核心配置默认保留，只有额外确认时才处理。
在“诊断与修复”的 Trace 记录 行点击“检查”，只有发现索引缺失或损坏时才提供“修复”。先停止 Gateway，再手动修复；原索引和修复清单会备份，从原始记录重建记录列表与用量统计，不修改原始 JSONL。它用于 Deck 的 Trace 数据，不是客户端会话历史修复。
导入已有配置
本机已有配置会自动检测并平铺展示，来源显示在配置旁边。勾选后点击右下角「导入」；「取消」返回配置目录，不写入配置。刷新保留本次勾选选择，重复连接只展示一次，已添加的项目不可重复导入。
「从文件导入」用于配置存放在其他目录或电脑的情况，会自动识别文件格式，无需先从其他工具导出。问号「文件说明」按需展示支持的文件：
| 来源 | 选择的原文件（macOS 示例） |
|---|---|
| Magpie | ~/.config/magpie/providers.json |
| CC Switch | ~/.cc-switch/cc-switch.db；旧版 config.json |
| Claude CLI | ~/.claude/settings.json |
| ChatGPT / Codex CLI | ~/.codex/config.toml；若 API Key 在 auth.json 中，需保留在同一目录 |
| 旧版 XwX Deck | settings.json |
目前支持原配置文件，不支持 Magpie 的加密 .magpie-backup 文件或 CC Switch 的 SQL 导出备份。这些备份不能直接替代上表的原文件。
首次引导提供客户端检测和配置导入。 可从添加配置窗口再次打开导入页。 支持的 API 服务、密钥和明确模型选择可导入。 已授权的本机官方账号也可由用户明确选择。 账号导入保留原登录文件，并引用对应身份。 不会复制来源刷新令牌或自动切换客户端。
相同连接跳过，同名不同连接另存。 写入前备份 Deck 配置。 来源或目标变化时，须重新检测再选择。 未知认证、环境变量和额外请求头需手动核对。 无法验证的登录状态提供重新授权入口。
服务切换
新安装没有预置 API 连接。已有单连接会迁移到本地 Provider registry；每个连接分别保存 ChatGPT 模型、窗口与 Claude 模型映射。两种客户端可选择不同连接。连接失败后仍可在设置中编辑；没有模型目录时可填写模型 ID。点击设置中的配置行，卡片左侧切换已保存连接，右侧编辑。卡片仅编辑名称、URL 与 Key，已有协议和模型配置保留。左侧底部统一提供新增和导入；新增目录可返回原配置，保存或导入后留在管理卡片，不改变客户端正在使用的服务。右侧「配置／模型」页签分别编辑连接与查看目录；进入模型页自动读取目录，每个模型可单独测试，测试不修改默认模型或服务选择。目录较多时提供筛选，列表内部滚动；保存不自动测试，未保存修改需先保存才能测试。标题旁的「删除配置」确认后执行，使用中的连接需先停止 Trace 并切换客户端。
客户端自带登录开启 Trace 时，仅将模型地址 openai_base_url 指向本地 Gateway，账户与工作区地址 chatgpt_base_url 保持官方 HTTPS。保留官方登录不会绕过客户端的工作区地址校验。
官方目录来自 Codex home 的模型缓存。外部配置变化会保留并提示；明确切换服务后才更新受管字段和目录指针，外部目录文件不会删除。切换连接时不会把旧模型目录当作新服务返回的目录。
模型目录先使用同一连接的缓存，再后台刷新。离线或目录超时不会撤销已保存的服务和模型选择；前台目录等待最多占用总计 2 秒。连接显示名称支持中文、空格及其他 Unicode 字符。名称最多 80 个字符，不能为空白或包含控制字符。连接使用独立且稳定的 ID；同名连接不会相互覆盖，改名不改变已有身份。已有名称保持原值。Claude Desktop 接入是默认关闭的模型连接选项，不包含规则、技能或文件同步。
设置页「模型配置」同一行的「添加配置」打开 API 服务、订阅账号、我的配置、客户端管理四个平级标签。点击已保存配置直接进入「我的配置」中的编辑页；API 和 Coding Plan 按保存的名称列出；同一平台的订阅账号合并为一个入口，例如「ChatGPT 订阅」，面板内统一管理账号用量、暂停或退出、添加账号与轮换策略；平台支持时提供改名；新增配置默认展示服务商目录，选择后在同一窗口填写名称、URL 和 Key。「导入已有配置」与「自定义」一起列在目录中；自定义直接进入统一编辑面板，保存前不创建服务。切换页签保留未保存输入，「我的配置」左侧继续提供新增配置和导入配置入口。模型页标签右侧的「客户端管理」打开同一张卡片并选中客户端管理页，可添加、移除客户端，并自动检测已有安装；安装完成后可点击「重新检测」，未检测到时提供官方下载入口。移除只隐藏标签，保留模型配置，不卸载软件；ChatGPT / Codex CLI 和 Claude / Claude Code 共用各自的模型配置标签，客户端下载仍分别提供官方安装页面与已核实的镜像。镜像默认折叠，点击系统和架构直接下载桌面安装包；OpenCode 和 Qwen Code 优先提供 Desktop，CLI 只跳转官方安装页面，不在应用内展示安装命令。
官方服务与各个兼容连接使用独立的续接状态。Gateway 会把其他连接记住的旧模型名转成当前连接所选模型，目标目录已有的有效模型和手填的未知模型名保持原样；HTTP、WebSocket 与压缩请求沿用相同规则。正在运行的客户端可能缓存旧连接；切换后当前任务未生效时，重新打开客户端即可。XwX Deck 不会为了切换服务自动关闭或启动 ChatGPT。
Trace 数据
Trace 新配置默认上限为 1 GB，并开启「超出上限自动清理」，从最旧的完整对话开始清理，保留正在记录的对话。已有用户保存的容量及自动清理选择保留。在设置的 Trace 分组中可调整上限或关闭自动清理，关闭后上限仅用于提醒。将上限设为 0 GB 会切换为仅用量模式，确认后清理详细 Trace，保留用量统计。自动清理只删除详细记录，Token 用量和费用统计继续保留。仪表盘手动删除也默认保留统计；只有额外勾选“同时删除对应的 Token 用量和费用统计”时，才删除对应统计。将容量设为 0 GB 时，也可在确认框中额外勾选清空已有统计。索引损坏时停止写入和删除，先检查并手工修复。
Trace 保存在本地数据目录，可能包含完整提示词、上下文、工具参数、工具结果和模型响应。认证请求头会脱敏，但正文中的业务数据不会自动删除。共享日志前应人工检查。
用量按客户端请求的模型名归档。 上游返回不同模型名时，保留实际服务模型供核对。 分档、时段、短回复与缓存 TTL 需有对应计费证据。 已知费用正常显示，已知 0 与未知值分开。 未知字段显示“—”，不增加部分或未计价说明。
模型能力除了随包注册表和外部目录，还可以采用“当前 Gateway 实测”结果。实测层只覆盖真正观察到的字段，例如模型是否实际产生 reasoning token；不会用一次请求猜测上下文长度或价格。未实测的新模型继续按保守能力处理。
退出
- 关闭窗口：隐藏管理器；必要时 Gateway 继续服务客户端。
- 托盘、菜单栏、Dock 和 Cmd+Q 的退出：先恢复受管配置，再停止 Gateway。
- 连接恢复为所选 Provider 的远端配置与专属凭据；不会自动切换官方。需要协议转换的模型仍依赖本地 Gateway，界面会提示开启 Trace。
- 恢复仅处理 XwX Deck 实际写过且未被外部修改的字段；冲突保留并提示，写入失败回滚。配置仍依赖本地端口时取消退出，保留 Gateway 与恢复记录。
- 有正在生成的回复或工具续接时：先显示确认，避免静默中断。
排障顺序
- 检查客户端是否启用以及 Trace 是否开始。
- 检查服务地址、密钥和模型是否有效。
- 查看运行日志与 Trace 最终上游地址。
- 若服务刚切换且当前任务仍走旧连接，重新打开客户端后再试。
更新
启动后会检查新版，也可以在设置中点击版本号检查。Windows 下载后可重启更新；保持运行时，会在 02:00–05:00、系统空闲至少 15 分钟且没有需确认的活动会话时自动安装。取消某个版本后，重启也不会自动安装它，主动重新下载可恢复。
macOS 下载后校验 DMG。点击“打开安装包”会进入安全退出流程；等旧应用退出，再拖入“应用程序”并选择替换，从“应用程序”打开新版。不要从安装映像直接运行；安装完成并核对一致后会尝试推出映像。没有运行新版、映像仍被其他程序占用等情况下，需在 Finder 手动推出。
检查失败不代表已是最新。发布内容变化时请重新检查。Windows 已替换文件但自动启动失败时，新版和 .previous 备份均保留，按提示手动打开原路径程序。
界面语言
“设置 → 应用 → 语言”通过中／英开关选择语言。首次启动按系统界面语言选择，中文系统显示简体中文，其他语言显示英文。手动选择立即生效并跨重启保留；配置名、账号名、模型 ID 不变。