前言¶
DeepSeek Harness (DSH) 的設計理念是“一切皆插件”。對於開發者而言，在本地或私有環境中集成多樣化的模型能力是常見需求。dsh-llm-grok 插件解決了將 X.AI 的 Grok 訂閱額度接入 DSH 作爲統一 LLM 提供方的問題，使得開發者可以在 DSH 的生態內直接使用 Grok 的推理與多模態能力。
插件介紹¶
該插件由用戶 clarkzhao 維護，採用 MIT 開源許可證。目前項目在 GitHub 上獲得 1 star。
插件的核心功能是將 Grok 訂閱額度接成 DSH 的 LLM 提供方。
核心功能¶
- 原生多模態：支持用戶貼圖和 tool-result 裏的圖，隨同
/chat/completions發送。圖像不是先 OCR 成字再交給文本模型，也不作爲單獨的識圖工具。 - 支持的模型：支持 Grok 4.6、4.5、4.7、4.7-build-fast。
- 思考強度：支持 low / medium / high / xhigh 四檔推理強度設置。
- 網絡代理：走本機 HTTP 代理，默認配置爲 Clash 的
127.0.0.1:7890。
安裝¶
安裝前請確保已安裝 DSH。執行以下命令將插件添加到指定的 profile（默認爲 web）：
dsh plugin --profile web add dsh-llm-grok
如果未全局安裝 dsh，可以使用 npx：
npx @deepseek-ai/dsh plugin --profile web add dsh-llm-grok
安裝後，bundle 會寫入 llm-grok 並註冊 grok provider。如果此前在 llm-pi-ai 中添加過同名 grok，需先刪除以避免路由衝突。
配置與憑據¶
插件不讀 ~/.grok/auth.json，也不會自動續期。它只解析 DSH 憑據引用 GROK_SESSION_TOKEN。
Grok CLI 的 access token 有效期約 6 小時，過期後會導致 401 錯誤，需要手動同步進 DSH。
同步憑據步驟¶
- 獲取 Token：在終端執行
grok login，將 token 落到~/.grok/auth.json。 - 寫入 DSH：執行同步腳本將 token 寫入 DSH 的憑據文件（默認爲
~/.dsh/.credentials.yaml）：
python3 scripts/sync-grok-credential.py
- 自動化同步（推薦）：爲了應對 6 小時的過期週期，可以使用腳本安裝 launchd 任務，實現每 5 分鐘自動同步：
chmod +x scripts/install-launchd.sh
./scripts/install-launchd.sh
環境變量配置¶
也可以在啓動 DSH 進程前設置環境變量 GROK_SESSION_TOKEN。環境變量的優先級高於憑據文件：若啓動時環境變量已存在，文件同步無法覆蓋其值，需 unset GROK_SESSION_TOKEN 後重啓。
憑據文件格式¶
同步腳本會將憑據寫入如下格式的 YAML 文件：
version: 1
refs:
GROK_SESSION_TOKEN: <token>
注意：不要在已有 version: 1 的文件頂層再添加扁平的 GROK_SESSION_TOKEN: 鍵，否則可能導致 dsh web 啓動失敗。
限制與注意事項¶
- 不自動續期：插件不負責 token 的刷新，依賴外部腳本或環境變量維護。
- API 實現：只走
chat-completions接口，不實現官方 CLI 默認的Responses API。 - 圖片處理：會話日誌只存儲附件引用（
sha256:），像素數據只在發請求時從ctx.attachments讀取。 - 報錯處理：如果缺少附件服務，或者圖片出現在
system/assistant消息中，會返回UNSUPPORTED_CONTENT錯誤。 - 無惰性刷新：不做
refresh_token惰性刷新機制（方案 B 未實施）。 - 權限：插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼與許可證。
總結¶
dsh-llm-grok 提供了一條將 Grok 訂閱接入 DSH 的可行路徑，特別是其原生多模態支持爲特定場景提供了便利。使用時需注意 token 的手動同步機制。
