人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载TokenDance 是一个多模型网关multi-model gateway其桌面授权流程产出的是一把 API Key 而非可续期的 OAuth 访问令牌。本文以 add-tokendance-oauth-provider 任务规格 与 tokendance-oauth-provider 规则 为骨架结合 ClawX 仓库源码完整剖析这条端到端链路浏览器 OAuth 供给随机端口 loopback S256 PKCE→ Electron Main 密钥交换 → API-key secret 持久化与 OpenClaw 运行时同步 → 中文界面限定发现 → 归因头与恢复动作分类。读完本文你将掌握 ClawX 是如何把桌面 OAuth 授权与纯 API Key 密钥路径这两种模式安全缝合的以及这套方案在 Provider 注册、密钥验证、错误本地化三个层面的落地细节。1. 设计动机为什么 TokenDance 需要一条混合认证路径常规 OAuth provider如 OpenAI Codex授权后拿到的是 access token / refresh tokenClawX 通过oauth类型的 secret 存储并持续续期。TokenDance 不同它的桌面授权流程会在用户授权后直接签发一把 API Key而不是返回可再生令牌。因此 ClawX 必须用浏览器 OAuthBrowser OAuth完成供给provisioning阶段——引导用户在系统浏览器完成授权但把供给结果当作API Key走既有的api_keysecret 路径完成持久化与 OpenClaw 运行时同步。这一设计约束在任务规格的 Background 一节被明确写出并贯穿了所有 acceptance 条款。另一个关键设计是归因attributionTokenDance 用稳定应用 URLhttps://clawx.com.cn标识 ClawX。OAuth 建钥时该值作为app_url参数传入而每一次模型请求又显式携带X-App-URL: https://clawx.com.cn请求头确保请求级归因覆盖密钥级归因语义始终一致。2. Provider 注册三层目录与中文界面限定2.1 共享目录中的 TokenDance 定义ClawX 的 Provider 目录集中在 electron/shared/providers/registry.tsTokenDance 的定义位于该文件 L101-L127{ id: tokendance, name: TokenDance, icon: TD, placeholder: your-tokendance-api-key, model: Multi-Model, requiresApiKey: true, category: compatible, envVar: TOKENDANCE_API_KEY, defaultModelId: qwen3.8-max, isOAuth: true, supportsApiKey: true, showModelId: true, modelIdPlaceholder: qwen3.8-max, apiKeyUrl: https://tokendance.space/keys, supportedAuthModes: [oauth_browser, api_key], defaultAuthMode: oauth_browser, supportsMultipleAccounts: true, providerConfig: { baseUrl: https://tokendance.space/gateway/v1, api: openai-completions, apiKeyEnv: TOKENDANCE_API_KEY, headers: { X-App-URL: https://clawx.com.cn, }, }, }从源码结构可以提炼出这套定义的三个要点双认证模式supportedAuthModes同时包含oauth_browser默认与api_key即用户既可以选择浏览器 OAuth 一键授权也可以手动粘贴在 https://tokendance.space/keys 申请的密钥运行时协议openai-completions协议端点https://tokendance.space/gateway/v1默认模型qwen3.8-max归因内建于 providerConfig.headersX-App-URL头直接写在 provider 后端配置里因此无论 OAuth 还是手动密钥模型请求都会自动携带该头——这正是 acceptance 条款Manual TokenDance API keys use the same runtime attribution header的实现基础。2.2 发现范围限定仅中文界面可见TokenDance 的新增discovery入口只在 ClawX 界面语言解析为中文时出现在添加 Provider对话框中英文、日文、俄文及未支持的回退语言不得展示。但规则文档tokendance-oauth-provider.md特别强调了两点边界该门控必须是声明式且对语言切换响应式的reactive to language changes它不得删除、禁用或隐藏已经配置好的 TokenDance 账户——用户切到英文后仍需管理该账户、接收本地化的恢复指引。也就是说这是一个新增入口层面的 UI 门控而不是运行时可用性层面的开关。2.3 Renderer 侧的配套改动Renderer 侧需要同步注册以便展示任务清单中列出了 src/assets/providers/index.ts官方 Logo 资源与 src/lib/providers.ts。同时 i18n 方面要求 en/zh/ja/ru 四种语言环境下的 settings.json 与 chat.json 都要补充 TokenDance 相关文案aiProviders.oauth.tokenDance*错误文案与acp.tokenDanceRecovery.*恢复指引文案并且对图标有专门要求中文界面使用官网 Logo 且不做暗色反转。3. 核心实现随机端口 Loopback OAuth S256 PKCETokenDance OAuth 的完整实现位于 electron/utils/tokendance-oauth.ts入口为loginTokenDanceOAuth(options)L151-L264。以下按阶段拆解。3.1 常量与 PKCE 材料export const TOKENDANCE_APP_URL https://clawx.com.cn; export const TOKENDANCE_AUTH_URL https://tokendance.space/auth; export const TOKENDANCE_KEY_EXCHANGE_URL https://tokendance.space/portal/api/v1/auth/keys; export const TOKENDANCE_GATEWAY_BASE_URL https://tokendance.space/gateway/v1; export const TOKENDANCE_DEFAULT_MODEL qwen3.8-max; export const TOKENDANCE_APP_HEADER { X-App-URL: TOKENDANCE_APP_URL } as const; const OAUTH_TIMEOUT_MS 10 * 60 * 1_000;PKCE 材料由createTokenDancePkce()L33-L37生成verifier是 64 字节随机数经 Base64URL 编码challenge是 verifier 的 SHA-256 摘要再 Base64URL 编码。verifier 全程只存在于 Electron Main 进程绝不进入 Renderer 状态、日志或除一次性回调码之外的任何 URL。3.2 授权 URL 构造回调服务器监听在127.0.0.1的随机端口server.listen(0, 127.0.0.1)并生成一个不透明的flow_id放进回调 URL。授权 URL 的查询参数L214-L219参数值作用callback_urlhttp://127.0.0.1:随机端口/callback?flow_id不透明标识随机端口 loopback 回调code_challengePKCE challenge证明持有 verifiercode_challenge_methodS256PKCE 挑战方法app_urlhttps://clawx.com.cn稳定归因 URLkey_nameClawX在 TokenDance 侧创建的密钥名称3.3 回调校验与本地化成功页回调处理器L167-L198校验三点任一不符即返回 400路径必须是/callbackflow_id必须与本次流程生成的标识一致防伪回调必须携带一次性code。校验通过后返回 200并附带Cache-Control: no-store、Connection: close与严格 CSP 的 HTML 成功页。成功页内容根据请求的Accept-Language头在 en/zh-CN/ja/ru 四种文案间选择CALLBACK_COPYL63-L88例如中文显示授权成功 / TokenDance 已成功连接到 ClawX。/ 现在可以关闭此页面并返回 ClawX。页面脚本 3 秒后自动window.close()。3.4 超时、取消与连接关闭流程有 10 分钟超时OAUTH_TIMEOUT_MS超时后 rejecttokendanceOAuth.timedOut支持AbortSignal取消取消时 rejectAbortError连接关闭策略closeServerL39-L48回调响应请求关闭连接且回调服务器拆除时调用server.closeAllConnections()因为 Chromium 可能把 loopback 回调 socket 当作 keep-alive 连接保留数秒但一次性 code 交换完成后它已无价值——绝不能让它拖延 OAuth 成功反馈。3.5 密钥交换verifier 只发往唯一端点拿到 code 后L233-L256Main 进程向TOKENDANCE_KEY_EXCHANGE_URL发起一次 POSTbody 为{ code, code_verifier: verifier, code_challenge_method: S256 }。失败抛tokendanceOAuth.exchangeFailed:status响应缺少key字段抛tokendanceOAuth.missingKey。也就是说verifier 仅发送到 TokenDance 密钥交换端点这一个地址不会出现在任何其他 URL、日志或 Renderer 状态中。测试 tests/unit/tokendance-oauth.test.ts 完整覆盖了上述行为校验授权 URL 的 origin/pathname/参数、回调返回本地化成功页、verifier 与 challenge 的 SHA-256 对应关系、密钥只出现在交换响应中expect(rawUrl).not.toContain(td-secret-key)、错误 flow_id 回调返回 400、等待回调期间可取消。4. Main 端流程管理与持久化链路4.1 BrowserOAuthManager单实例、代际安全的事件桥TokenDance OAuth 由 electron/utils/browser-oauth.ts 的BrowserOAuthManager统一调度且与 OpenAI Codex OAuth 共享同一实例。关键机制单实例startFlow()L41-L65中若this.active为真直接忽略重复 start 请求防止双击或对话框重开导致并行回调服务器与重复的运行时同步返回 true 复用当前流程代际安全generation-safe每次流程分配递增的flowIdownsFlow(flowId, signal)要求信号未中止且 flowId 仍是当前流程。完成或取消来自过期流程的回调不得清除/派发当前流程的事件异步阶段间重检onTokenDanceSuccess()L276-L348在建账户 → 存 OpenClaw 密钥 → 设置默认模型 → 设置默认账户每个异步持久化阶段之间都重新检查ownsFlow(flowId, signal)一旦取消立即中断后续的 credential / runtime-config / default-account / success 工作Main 是浏览器 OAuth 事件到 Renderer 的唯一桥Renderer 不直接发起 IPC 或 Gateway HTTP 调用。4.2 密钥以 api_key 存储authMode 记录为 oauth_browseronTokenDanceSuccess的持久化顺序对应 acceptance 条款providerService.createAccount({ ... authMode: oauth_browser, baseUrl: TOKENDANCE_GATEWAY_BASE_URL, apiProtocol: openai-completions, headers: TOKENDANCE_APP_HEADER, model: 既有模型或 qwen3.8-max }, token.apiKey)—— 第二参数即密钥经 Provider 服务落入api_key secret存储即使账户的 authMode 记录为oauth_browser密钥不写入日志、回调 URL 或 Renderer 状态saveProviderKeyToOpenClaw(tokendance, token.apiKey)—— 同步到 OpenClaw 运行时setOpenClawDefaultModelWithOverride(tokendance, tokendance/qwen3.8-max, { baseUrl, api: openai-completions, apiKeyEnv: TOKENDANCE_API_KEY, headers: TOKENDANCE_APP_HEADER }, fallbackModels)—— 配置默认模型与归因头先持久化默认账户再通知成功providerService.setDefaultAccount(nextAccount.id)在emitSuccess之前执行。这样 Renderer 收到oauth:success后的确认路径只是一次廉价 no-op 选择而不是触发第二次完整的 OpenClaw 运行时同步。4.3 即时反馈与删除的乐观更新OAuth 成功反馈与 Provider 列表刷新立即发生不等待后续的运行时同步或快照对账snapshot reconciliation删除 Provider 时卡片在 Renderer 侧乐观移除Main 继续完成运行时与密钥链keychain清理。5. 密钥验证最小请求探针与恢复动作分类5.1 为什么不用/models探活常规 OpenAI 兼容 provider 的验证先请求/models再按需回退。但 TokenDance 的/models是公开接口无法证明某把密钥有效。因此 electron/services/providers/provider-validation.ts 对tokendance特判L335-L341直接用配置的模型发起最小认证请求——POST base/chat/completionsbody 为{ model, messages: [{ role: user, content: hi }], max_tokens: 1 }。验证请求同样携带X-App-URL归因头来自getProviderHeaders合并的 providerConfig.headers。5.2 TokenDance-Recovery-Action 白名单验证响应中读取TokenDance-Recovery-Action响应头但只识别三个文档化取值L21-L32取值含义恢复指引top_up_balance余额不足引导充值reauthorize_api_key需要重新授权 API Keyapi_key_quota周期性配额重置未知或缺失的值一律不分类保留普通 provider 错误行为。识别出的动作以类型化数据返回recoveryAction?: ProviderRecoveryAction类型定义在 shared/host-api/contract.ts供 UI 做本地化指引。5.3 OpenClaw patch 桥接与 Chat 错误横幅由于模型请求由 OpenClaw 运行时发起其错误文本需要把恢复动作带回 Renderer。实现方式是通过被钉住的 OpenClaw 运行时补丁patches/openclaw2026.7.1-2.patch运行时的错误格式化函数只保留已识别的TokenDance-Recovery-Action头为错误文本中的非机密标记形如[TokenDance-Recovery-Action:top_up_balance]未知取值则原样保留错误文本不加标记。测试 tests/unit/tokendance-openclaw-recovery.test.ts 精确验证了这一行为top_up_balance被保留进格式化文本unknown_action不产生标记。Renderer 侧 src/pages/Chat/AcpErrorBanner.tsx 用正则/\s*\[TokenDance-Recovery-Action:(top_up_balance|reauthorize_api_key|api_key_quota)\]\s*/g匹配该标记替换为本地化指引文案acp.tokenDanceRecovery.action并清理多余空白。同时 src/components/settings/ProvidersSettings.tsx 中的getOAuthErrorMessage把tokendanceOAuth.*错误码映射为多语言文案如tokenDanceExchangeFailed附带 HTTP status、tokenDanceCancelled、tokenDanceCallbackUnavailable、tokenDanceTimedOut、tokenDanceMissingKey。6. 验收要点与测试体系任务规格的 acceptance 条款可归纳为可验证的五组行为均已被测试覆盖授权协议授权 URL 含编码 loopback 回调、S256 challenge、app_urlhttps://clawx.com.cn、key_nameClawX回调校验不透明 flow_id、10 分钟超时、支持取消、本地化成功页、verifier 只发密钥交换端点tests/unit/tokendance-oauth.test.ts密钥与秘密交换所得密钥以api_keysecret 存储而 authMode 为oauth_browser密钥不进日志/URL/Renderer 状态且OAuth 归因与手动密钥归因共用同一X-App-URL头界面门控中文界面用官网 Logo不做暗色反转展示于添加对话框非中文目录不出现该 provider验证与恢复Main 拥有验证权Renderer 无直接 IPC/Gateway 调用使用配置模型的极小请求只读取文档化TokenDance-Recovery-Action值并返回类型化动作OpenClaw patch 保留已识别标记Chat 错误横幅替换为本地化指引tests/unit/tokendance-openclaw-recovery.test.ts流程生命周期浏览器 OAuth 每个完成事件只派发一次、流程激活期间忽略重复 start、过期流程的取消清理不能波及当前流程、成功回调关闭连接且回调服务器拆除不等待 Chromium keep-alive 超时、TokenDance 在派发成功前先持久化默认账户tests/unit/browser-oauth.test.ts。端到端层面由 tests/e2e/provider-lifecycle.spec.ts 覆盖 Provider 生命周期单测层面由 tests/unit/providers.test.ts、provider-validation.test.ts、provider-runtime-sync.test.ts、provider-store-init.test.ts 与 acp-chat-components.test.tsx 交叉验证注册、验证、同步与错误渲染各环节。7. 明确的非目标Out of scope任务规格还划定了边界理解这些边界有助于避免误用不在仓库中存放 TokenDance 产品方product-ownerAPI Key不查询合作方分润定价端点除非外部提供产品方密钥不在应用内构建支付结算或轮询支付会话该 provider 预设不支持 TokenDance 的非聊天媒体协议仅接入 OpenAI Chat Completions。结语TokenDance 的接入是 ClawX Provider 体系中一个典型的混合认证案例它在协议层复用 Browser OAuth 的供给体验在存储与运行时层复用 API Key 密钥路径在错误处理层通过补丁标记 前端本地化把服务商的恢复语义变成用户可操作的中文指引。其核心工程经验可以总结为三条可复用的原则敏感材料verifier/API Key只在 Electron Main 流动异步持久化链路必须逐阶段做流程归属与取消重检Provider 元数据默认模型、端点、归因头集中在共享目录定义并由 Main 统一同步到 OpenClaw 运行时。对需要接入桌面授权产密钥类服务的开发者本仓库的 tokendance-oauth.ts 与 browser-oauth.ts 是可直接对照参考的完整实现。赞分享人工智能AI 应用桌面应用交互助手【免费下载链接】ClawXClawX is a desktop app that provides a graphical interface for OpenClaw AI agents. It turns CLI-based AI orchestration into a desktop experience without using the terminal. China website is https://clawx.com.cn.项目地址https://gitcode.com/gh_mirrors/cl/ClawX点击查看免费下载相关推荐ClawX TokenDance OAuth Provider 落地指南Authorization Code S256 PKCE、归因头与恢复动作分类ClawX TokenDance OAuth Provider 落地指南Authorization Code S256 PKCE、归因头与恢复动作分类 T人工智能AI 应用桌面应用交互助手Apereo CAS OAuth 2.0 授权码流程Authorization Code与 PKCE 扩展实战指南Apereo CAS OAuth 2.0 授权码流程Authorization Code与 PKCE 扩展实战指南 导读 授权码Authorization后端认证鉴权单点登录Benchling 平台 API 认证完全指南API Key、OAuth 2.0 与 OIDC 集成方案Benchling 平台 API 认证完全指南API Key、OAuth 2.0 与 OIDC 集成方案 导读 本篇文章以 skills/benchlingAI 技能科研生物信息学数据科学上一篇3分钟解锁网易云音乐隐藏功能BetterNCM安装器完全指南下一篇DB Browser for SQLite让SQLite数据库管理变得简单直观创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考