TinkerClaw Grok Bridge

One of dozens of skills and plugins in TinkerClaw — a self-improving OpenClaw fork that's been running 24/7 for months.

You already pay for SuperGrok every month. Your agent still can't use it.

OpenClaw knows exactly one way to reach Grok: an xAI API key, metered, billed per token. A second bill, stacked on top of the subscription sitting idle in your account. Consumer plan on one side, developer plan on the other, and no bridge between them.

Except the official Grok CLI never needed an API key. It just logs you in.

This plugin does the same thing for OpenClaw. You approve it once in a browser, the way you'd sign into any app, and Grok shows up as a model your agent can use, running on the subscription you already pay for. No API key anywhere, nothing metered. A background service quietly renews the login before it lapses, so it keeps working on its own. The part that usually breaks is a version check that rejects any client not shaped like the official one. That's handled for you, and it's a single setting to bump if xAI moves the goalposts again.

Part of TinkerClaw — real-time token tracking, self-improving crons, persistent cognitive memory. This is one piece of that stack; the repo has dozens more.

👉 https://github.com/globalcaos/tinkerclaw

Clone it. Fork it. Break it. Make it yours.

Requirements

• OpenClaw >= 2026.4.27. Built and end-to-end tested on 2026.4.27; the SDK entry points it uses are also present in 2026.7.1-2.
• An active SuperGrok subscription (grok.com) or X Premium+
• The bundled xai provider plugin enabled (it is, by default)

Install

clawhub package install @globalcaos/tinker-grok-bridge

Then enable it in your OpenClaw config:

{
  plugins: {
    entries: {
      "tinker-grok-bridge": { enabled: true },
    },
  },
}

Quick start

openclaw grok login     # approve once in the browser
openclaw grok status    # token, auth profile, provider state

login prints a URL and a short code. Approve it, and the plugin stores the token, publishes it to OpenClaw's auth store, and writes the xai provider block into your config. Grok is then a normal model:

openclaw agent --model xai/grok-4.5

openclaw grok logout deletes the stored token from the machine.

Configuration

All optional — the defaults work. Set under plugins.entries.tinker-grok-bridge.config:

How it works

Four moving parts. Each one is somewhere people get stuck, so they're worth knowing:

1. Device-code login. Standard OIDC device grant against auth.x.ai, the same flow the official Grok CLI uses. Your password never touches this machine; you approve in a browser and the machine receives a token.
2. A different endpoint. The token is a bearer for cli-chat-proxy.grok.com, the OpenAI-compatible endpoint served to consumer subscriptions. It is not api.x.ai, which is the metered pay-per-token API and needs its own key.
3. Token in, profile out. The proxy authenticates with Authorization: Bearer …, exactly what OpenClaw already sends for an api-key profile on an OpenAI-compatible provider. So the rotating access token is published as that profile rather than teaching the transport a new auth mode. OpenClaw watches its auth store, so a renewal applies live with nothing to restart.
4. The version gate. The proxy answers HTTP 426 Upgrade Required to any client that doesn't present the Grok CLI identity headers, no matter how valid the token is. The plugin sends them. When xAI raises the floor, bump clientVersion.

Security

• The token is written to $OPENCLAW_STATE_DIR/xai-oauth.json (default ~/.openclaw/) with 0600 permissions, atomically. It never leaves the host.
• No API keys, no passwords, and no credentials are read from or sent anywhere except xAI's own oauth endpoints.
• clientId is a public identifier — the same one the official CLI ships — not a secret.
• openclaw grok logout removes the stored token.

Honest limits

• A SuperGrok subscription is required. This bridges the plan you already pay for; it does not create free access.
• xAI may gate oauth API access by plan tier. A login can succeed and calls still return 403 on some tiers. No tier gating has been observed on SuperGrok, but xAI controls that and can change it.
• The version gate moves. If xAI raises its minimum client version, calls fail with 426 until clientVersion is bumped. That's a config edit, not a reinstall.
• Costs shown in OpenClaw for this provider are the equivalent API prices, listed so accounting works. A subscription is flat rate — they are not what you actually pay.

Pairs well with

• Model Router — TinkerClaw — once Grok is subscription-billed, the router can prefer it over metered models instead of avoiding it.
• Agent Superpowers — TinkerClaw — verification discipline for the agents you're now running more cheaply.

License

MIT