前言¶

在 DeepSeek Harness（DSH）里走 llm-pi-ai 的 xai 路由时，常见做法是自己申请 xAI API key，再写进环境变量或凭据配置。对已经持有 SuperGrok 或 X Premium 订阅、希望直接用订阅身份调用 Grok 的开发者来说，多维护一把 API key 并不必要，也容易和订阅账号脱节。

下面介绍社区插件 dsh-xai-oauth（维护者 tonylee2022）：在 DSH Web 侧完成 xAI 设备码（RFC 8628）授权，把 access token 注入 DSH 凭据 XAI_OAUTH_TOKEN，并在接近过期时自动 refresh，使 xai provider 每次请求都能解析到有效令牌。

这是什么¶

dsh-xai-oauth 是面向 DSH 的 admin-security 类插件，当前 npm 包版本 0.1.5，许可证 MIT。它不做 Grok 模型封装，只负责 OAuth 登录、令牌持久化与续期，并通过 bundle patch 让 llm-pi-ai 的 xai 路由使用 apiKeyEnv: XAI_OAUTH_TOKEN。

仓库：https://github.com/tonylee2022/dsh-xai-oauth
社区目录页：https://www.skillhub.cn/plugins/tonylee2022/dsh-xai-oauth（独立站点，与 DeepSeek / 幻方无官方从属关系）

核心功能¶

1. 设备码授权：向 https://auth.x.ai/oauth2/device/code 申请设备码；客户端 id 与 scope（含 grok-cli:access、api:access）与 xAI CLI / pi-ai 一致。
2. 轮询换票：轮询 https://auth.x.ai/oauth2/token，用户批准后得到 access token 与 refresh token，原子写入 $DSH_HOME/xai-oauth.json（文件权限 0600，目录 0700）。
3. 凭据注入：通过 ctx.credentials 将当前 access token 写入 XAI_OAUTH_TOKEN；对 llm-pi-ai 的 xai 路由 patch apiKeyEnv: XAI_OAUTH_TOKEN，请求时解析最新值。
4. 自动续期：每 60 秒检查一次，距过期不足 5 分钟时用 refresh token 续期并重新写入。

Web UI 在 设置 → 模型提供方 旁提供 xAI（Grok/X） 设置页：登录 xAI → 复制用户码 → 打开授权页在 xAI 官方页面批准 → 自动完成授权。

安装与启用¶

插件面向 web profile，安装后需重启 web profile（dsh --profile web）。

从 npm 安装（推荐）：

dsh plugin --profile web add dsh-xai-oauth

或从 GitHub 安装：

dsh plugin --profile web add github:tonylee2022/dsh-xai-oauth

本地源码安装（开发调试用）：

dsh plugin --profile web add ./dsh-xai-oauth

安装前建议自行查看仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行，令牌会落在 Host 侧文件中。

典型用法¶

1. 执行上述任一安装命令。
2. 重启：dsh --profile web。
3. 在 Web UI 设置 → 模型提供方 进入 xAI（Grok/X），点击「登录 xAI」。
4. 复制界面上的用户码，点击「打开授权页」，在 xAI 官方页面用 SuperGrok 或 X Premium 账号登录并批准。
5. 授权完成后，在 DSH 中照常选用走 xai provider 的模型路由即可，无需再配置 xAI API key。

可选配置（写入插件 config）：

- id: xai-oauth
  config:
    path: /secure/path/xai-oauth.json   # 默认 $DSH_HOME/xai-oauth.json
    controlPort: 1457                    # 本机状态服务端口

兼容性与安全边界¶

兼容性

• dsh web / 普通浏览器：页面 origin 为 http://127.0.0.1:<port>。
• DSH Desktop 0.2.1 起：Web UI 从 dsh-app://app 加载；插件自 0.1.5 起接受该 origin。更早的 DSH 版本可能在登录时出现 CORS 预检失败，界面表现为 “Failed to fetch”。

安全边界

• 令牌只保存在 Host 侧 owner-only 文件；Web 页面不直接接触令牌。
• 本机控制服务仅监听 127.0.0.1:1457，只接受本地 DSH Web origin（http://127.0.0.1:*、http://localhost:*、http://[::1]:*，以及 Desktop 的 dsh-app://app）；登出请求带 CSRF token。
• access token 等效于该订阅的 API 凭据，请勿外泄或提交到版本库。

适用场景与注意¶

适合已在 xAI 侧拥有 SuperGrok 或 X Premium 订阅、希望在 DSH 里统一走 OAuth 而非自管 API key 的开发者。不适合需要企业级 API 配额独立计费、或无法在浏览器完成设备码授权的环境。

DSH 生态强调「一切皆插件」；选用社区插件时，以 README 与源码为准核对行为，勿假设目录站与官方产品存在绑定关系。

结尾¶

dsh-xai-oauth 把 xAI 订阅 OAuth、令牌续期与 XAI_OAUTH_TOKEN 注入串成一条可复现路径，降低在 DSH 中使用 Grok 的凭据维护成本。进一步了解可访问 SkillHub 目录页 或 GitHub 仓库 README。