前言¶
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 的手动同步机制。
