前言¶
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 文件），請自行查看源碼確認。
