前言¶
DeepSeek Harness 提供了插件化架构，允许开发者通过路由接入不同的 LLM 服务。官方的 Grok CLI 虽然支持通过 SuperGrok 或 X Premium 订阅进行 OAuth 登录，但这种登录状态并未直接集成到 Harness 的路由系统中。对于需要使用 Grok 4.x 模型（如 grok-4）的开发者来说，通常需要维护一个独立的 API Key，这与官方 CLI 的订阅机制脱节。
dsh-grok-auth 插件解决了这个问题。它复用了官方 Grok CLI 维护的 ~/.grok/auth.json 认证文件，将 xAI 的订阅 OAuth 登录状态桥接到 Harness 的 xai LLM 路由上。
是什么¶
这是一个自包含的 DeepSeek Harness 插件，由 Gyanano 维护。它不生成新的 API Key，而是复用官方 Grok CLI 的登录流程和凭证。插件激活后，会在 Harness 的设置中增加一个 Grok Auth 卡片，用于管理登录状态和查看使用量，同时自动注册 xai LLM 路由。
核心功能¶
共享 Grok 登录状态¶
插件使用一个 Host 级别的认证协调器。它通过版本绑定的认证文件快照、内存缓存以及提前刷新机制来管理 Token（约 6 小时过期）。为避免与官方 CLI 的锁文件冲突，插件使用 auth.json.dsh.lock 进行进程间锁控制。插件在刷新时会校验刷新令牌的 lineage，确保写入操作的原子性，并将文件权限设为 0600。
双登录流程¶
- 浏览器登录：直接调用官方
grok login，由 CLI 完成整个 PKCE 流程并写入认证文件。 - 设备码登录：在 Host 内部运行 RFC 8628 流程，使用与 CLI 相同的公开客户端 ID，支持无头环境（Headless）。
xai LLM 路由¶
xai 路由包装了安装的 pi-ai xai 目录提供商（api.x.ai/v1）。它将订阅的 OAuth 访问令牌作为 Bearer 凭证注入每个请求，请求的 Wire 协议、工具调用和流式传输均由提供商管理。
实时模型发现¶
安装的 pi-ai 目录是静态快照。启用 liveModels 后，插件会叠加账户的实时 GET api.x.ai/v1/models 列表。它会从精选模板合成未收录的模型（如 grok-4.6），并在模型列表变化时重新声明路由。媒体模型（如 grok-imagine-*）会被跳过。
每周使用量¶
设置卡片会尝试从 Grok 代理后端获取每周积分快照（cli-chat-proxy.grok.com/v1/billing?format=credits）。获取失败时仅显示横杠，不会阻塞登录或请求。
安装与启用¶
推荐安装预构建的发布包。该包包含预构建的 Host 和浏览器 Bundle，无需安装时构建权限。
dsh plugin --profile web add https://github.com/Gyanano/dsh-grok-auth/releases/latest/download/dsh-grok-auth-latest.tgz
安装完成后，重启 dsh web，打开设置页面，在插件列表中选择 Grok Auth。
典型用法¶
安装后，在 Harness 的 Host 配置中会新增一行 llm-grok-auth。所有配置项均为可选：
- 控制路由注册：设置
llmEnabled: false可以仅启用共享登录状态协调器，而不注册xaiLLM 路由。 - 自定义认证文件路径：通过
authJsonPath覆盖默认的$GROK_HOME/auth.json。 - 自定义 API 端点：通过
baseUrl覆盖目录默认的api.x.ai/v1。 - 启用实时模型：保持
liveModels: true以叠加账户的实时模型列表。
适用场景与注意¶
适用场景：需要在 Harness 中使用 Grok 模型，且希望复用 X Premium 订阅额度，不希望维护额外的 API Key。
重要限制与安全：
- 安全性：Token 值永远不会进入浏览器、设置、日志或会话事件中。仅 Host 端请求接收授权头。
- 锁机制：官方 CLI 不参与插件的写锁，插件采用“故障关闭恢复”策略（校验 lineage、采用新状态）而非绝对跨客户端序列化。
- OAuth 客户端：公开的 OAuth 客户端 ID 属于官方 Grok CLI，xAI 未承诺其长期向第三方可用。
- 官方警告：此插件为非官方渠道，仅限个人开发使用。基于账户的订阅表面（auth.x.ai）不受支持、可被撤销，且可能会被限流或更改。
许可证：根据事实，许可证字段未明确在文本中定义（仅提及 LICENSE 文件），请自行查看源码确认。
