dsh-llm-xai-oauth

Use a SuperGrok / X Premium subscription as a native DeepSeek Harness LLM provider. No xAI API key.

中文：README.zh.md. Companion TUI: dsh-ssh-tui.

Three facts that matter

1. This is subscription OAuth, not an API key. After install, dsh talks to https://cli-chat-proxy.grok.com with the access token in ~/.grok-bridge/auth.json.
2. The access token lasts about an hour. While dsh is running, the plugin refreshes five minutes before expiry and again on HTTP 401. If dsh is not running, that refresh does not happen.
3. So you need a refresher that is not the dsh process. Use dsh-llm-xai-oauth daemon. Do not expect the TUI or a headless one-shot to keep the token alive overnight.

/usage returning 401, then chat also 401, almost always means: the token expired and nothing was refreshing it.

Setup in five minutes

You need Node.js ≥ 22.19 and a DeepSeek Harness CLI (npm i -g @deepseek-ai/dsh). On a remote SSH box, install this next to dsh-ssh-tui in the same profile.

1. Add the plugin to a profile

dsh plugin --profile tui add dsh-llm-xai-oauth
dsh plugin --profile headless add dsh-llm-xai-oauth

Web UI as well, if you use it:

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

Confirm the bundle landed:

dsh --profile tui --dump-config | grep llm-xai-oauth

You want id: llm-xai-oauth. Without that line, /model will not have a live SuperGrok route.

A local checkout / GitHub source still works:

git clone https://github.com/cyjyyd/dsh-llm-xai-oauth.git
cd dsh-llm-xai-oauth
bash scripts/install.sh tui

# or
dsh plugin --profile tui add github:cyjyyd/dsh-llm-xai-oauth

2. Log in once (from a machine that can open a browser)

If grok-bridge or the official Grok CLI already left ~/.grok-bridge/auth.json or ~/.grok/auth.json on this machine, this step reuses it and does not open a browser.

Otherwise, from a terminal that can open auth.x.ai:

npx dsh-llm-xai-oauth login
# force a new device-code even when a token already exists:
npx dsh-llm-xai-oauth login --force

The CLI prints a URL and a user code. Authorize SuperGrok / X Premium in the browser. On success it writes:

• token: ~/.grok-bridge/auth.json (0600)
• dsh default model: $DSH_HOME/settings.yaml agent-default-model → xai / grok-4.6
  (if that section is already xai, your grok model and effort are left alone)

Headless / CI hosts without a TTY skip the prompt. Set DSH_XAI_OAUTH_NO_LOGIN=1 to skip it even on a TTY.

Check remaining lifetime:

npx dsh-llm-xai-oauth status

3. Keep the token fresh (this is not dsh)

Access tokens are short. A TUI, headless job, or cron that starts after expiry will read a dead token; /usage and chat then 401.

Recommended: a user systemd unit

npx dsh-llm-xai-oauth daemon --install

That writes ~/.config/systemd/user/dsh-llm-xai-oauth.service and enable --now. The process re-reads auth.json about once a minute and refreshes five minutes before expiry. dsh does not need to be running.

No systemd, or you do not want a user unit:

# foreground
npx dsh-llm-xai-oauth daemon

# or cron every 20 minutes (no-op while the token is still valid)
*/20 * * * * npx --yes dsh-llm-xai-oauth refresh >/tmp/dsh-xai-refresh.log 2>&1

Remove the user unit:

npx dsh-llm-xai-oauth daemon --uninstall

Refresh once by hand:

npx dsh-llm-xai-oauth refresh
npx dsh-llm-xai-oauth refresh --force

4. Run one SuperGrok turn

grep -A3 agent-default-model ~/.dsh/settings.yaml

dsh --profile tui --provider xai --model grok-4.6
dsh --profile headless "Reply with exactly: xai-harness-ok. Do not use tools."

In dsh-ssh-tui: /model picks Grok; /usage reads the SuperGrok weekly remaining quota. The TUI now refreshes a due token before /usage, and on 401 it force-refreshes once and retries. That covers “I opened the TUI just as the token expired”. It does not cover “the machine slept overnight with no refresher”. Step 3 is that refresher.

Switching models later

# $DSH_HOME/settings.yaml
agent-default-model:
  provider: xai
  model: grok-4.6
  reasoningEffort: high

Or pass --provider / --model, or use /model in the TUI. At startup the plugin calls GET {baseURL}/models with the current token; /model prefers that live catalog (currently grok-4.6 with xhigh, grok-4.5 up to high). The static fallback still lists grok-4.3.

max in a DeepSeek-style picker maps to xhigh.

Optional plugin settings live under llm-xai-oauth: in $DSH_HOME/settings.yaml (baseURL, reasoningEffort, models, retry / idle timeout). Change them without restarting; the next request re-resolves.

Long SuperGrok chats can fill the 500K window and then 400 with a generic INVALID_REQUEST because max_tokens no longer fits. From 0.1.3 the adapter projects the next prompt from the last usage sample and, when remaining context cannot hold the requested completion, throws CONTEXT_WINDOW_EXCEEDED so harness overflow compaction can retry. Compaction / title calls still go through, with max_tokens clamped to the remainder.

401 / expiry

npx dsh-llm-xai-oauth status
ls -l ~/.grok-bridge/auth.json
systemctl --user status dsh-llm-xai-oauth.service
journalctl --user -u dsh-llm-xai-oauth.service -n 50

HTTPS_PROXY / HTTP_PROXY apply to login, refresh, and chat.

Override client / endpoints only when xAI changes them:

What it is not

• Not an xAI API-key provider. Metered api.x.ai stays on the generic catalog.
• Not a Codex / Claude / Copilot aggregator.
• Not a Web “one-click login” settings card. Device login is CLI / TTY.
• Does not registerConfigurableProviders('xai'); llm-pi-ai already owns that catalog key. This package owns the live adapter route.

Layout

src/index.ts        Cordis plugin: search / login / register the xai route
src/cli.ts          login / status / refresh / daemon
src/bootstrap.ts    local token search, device login, dsh default model
src/oauth.ts        load / refresh / device-code
src/adapter.ts      fetch + SSE chat-completions adapter (retries once on 401)
src/context-budget.ts  project remaining context and trip harness overflow compaction
cordis.patch.yml    profile bundle insert

License

MIT