Tools
Grok Cli
By OpenClaw CLI-backend plugin for the xAI Grok Build CLI — use a Grok/SuperGrok subscription for an OpenClaw agent's own reasoning.
Install
openclaw plugins install /path/to/openclaw-grok-cliREADME
# openclaw-grok-cli
An [OpenClaw](https://docs.openclaw.ai) CLI-backend plugin that registers the
xAI [Grok Build CLI](https://x.ai/cli/install.sh) (`grok`) as a model
provider — `grok-cli/<model>`.
## Why
This lets an agent's own reasoning — the part that reads a message and
decides what to do — run on a Grok/SuperGrok subscription, the same way
`claude-cli` lets it run on a Claude Code subscription and `cursor-cli`
(a sibling plugin, same pattern) lets it run on Cursor.
The practical use case is resilience: add `grok-cli/<model>` as a fallback
(`agents.list.<id>.model.fallbacks`) alongside your primary, and OpenClaw
fails over automatically if the primary runs out of usage.
## Requirements
- [Grok Build CLI](https://x.ai/cli/install.sh) installed and logged in
(`grok login` — OAuth against your xAI/SuperGrok account) on the same
host as the OpenClaw gateway. Install: `curl -fsSL https://x.ai/cli/install.sh | bash`.
- OpenClaw with plugin support (any recent version — built against the
`cliBackends` / `registerCliBackend` plugin API).
## Install
```bash
openclaw plugins install /path/to/openclaw-grok-cli
openclaw plugins enable grok-cli
```
Restart the gateway after enabling — CLI-backend registration needs a
restart to take effect, same as any other plugin enable/disable.
### Required extra step (third-party plugin limitation, not this plugin's bug)
Same root cause documented in the sibling `openclaw-cursor-cli` plugin:
OpenClaw's runtime CLI-backend registry (`resolveRuntimeCliBackends()`)
only picks up **bundled** plugins at model-resolution time — a
third-party/linked plugin like this one registers correctly
(`openclaw plugins inspect` shows it loaded) but resolves to
`Unknown model: grok-cli/<model>` without this extra step. The fix is a
second, independent lookup path OpenClaw does support: statically
declaring the backend's config directly under `agents.defaults.cliBackends`,
which is checked *before* the broken registry-based lookup.
```bash
openclaw config set 'agents.defaults.cliBackends' '{
"grok-cli": {
"command": "grok",
"args": ["-p", "{prompt}", "--output-format", "streaming-messages-json", "--permission-mode", "bypassPermissions"],
"resumeArgs": ["-p", "{prompt}", "--resume", "{sessionId}", "--output-format", "streaming-messages-json", "--permission-mode", "bypassPermissions"],
"output": "jsonl",
"input": "arg",
"modelArg": "--model",
"modelAliases": { "auto": "grok-4.5" },
"sessionMode": "existing",
"sessionIdFields": ["session_id"],
"clearEnv": ["GROK_DEPLOYMENT_KEY", "GROK_CODE_XAI_API_KEY"],
"serialize": true,
"reliability": {
"watchdog": {
"fresh": { "noOutputTimeoutRatio": 0.8, "minMs": 180000, "maxMs": 600000 },
"resume": { "noOutputTimeoutRatio": 0.3, "minMs": 60000, "maxMs": 180000 }
}
}
}
}' --strict-json
```
(If you already have other entries under `agents.defaults.cliBackends` —
e.g. `cursor-cli` — merge rather than overwrite, this sets the whole map.)
Restart the gateway after. This must stay in sync with `src/index.js`'s
`buildGrokCliBackend()` — if you change one, change the other.
## Configure
Optional plugin config, if `grok` isn't on the gateway's `PATH`:
```json5
{
plugins: {
entries: {
"grok-cli": {
enabled: true,
config: { command: "/absolute/path/to/grok" }
}
}
}
}
```
## Use
Set it as a primary or fallback model for any agent, scoped per-agent
(don't use the `--agent` flag on `openclaw models set`/`fallbacks add` —
it doesn't scope the write the way you'd expect; edit the agent's config
path directly):
```bash
openclaw config set 'agents.list[N].model.fallbacks' '["grok-cli/grok-4.5"]' --strict-json
```
Model ids pass straight through to `grok --model`. Run `grok models` for
the current catalog available to your account — it depends on your
subscription tier and will grow with SuperGrok. `grok-cli/grok-4.5` is the
default and currently the only model on a base account.
## How it works
`grok -p "<prompt>" --output-format streaming-messages-json` emits
newline-delimited JSON events in the *exact same wire format* as Claude's
Messages API stream (`type`/`subtype`, `message.content[]`, a final
`result` event with the answer text and token usage) with a `session_id`
field on every line — verified live, byte-for-byte the same shape family
as `claude-cli` and `cursor-agent`'s own stream formats. This plugin
declares that shape to OpenClaw's generic CLI-backend machinery — it's a
small declarative config, not a custom parser.
One real difference from `cursor-agent`: `grok -p` takes the prompt as a
CLI **argument** (`--single <PROMPT>`), not stdin — confirmed live, piping
via stdin with no argument errors `a value is required for '--single
<PROMPT>'`. So this backend uses `input: "arg"` with a `{prompt}`
placeholder in `args`, which OpenClaw's CLI runner substitutes before
spawning.
Session handling matches `cursor-agent`: `grok` assigns its own session id
on the first call and only accepts `-r/--resume <id>` on later calls —
`sessionMode: "existing"`, not `"always"`. Verified live with a two-turn
memory test (a fact stated in turn one was correctly recalled via
`--resume` in turn two).
## Known limitations
- **Requires the `agents.defaults.cliBackends` config step above.** Not
optional, not this plugin's bug — see "Required extra step" under Install.
- **No daemon/server mode used here.** `grok` does ship `agent serve` /
`agent leader` (a persistent backend other clients can share), but this
plugin deliberately uses the simpler one-shot `-p` subprocess-per-turn
model to match how `claude-cli`/`cursor-cli` already work — no protocol-
level session pinning beyond `--resume`.
- **`--permission-mode bypassPermissions` auto-approves everything** within
the run (matches the same risk posture OpenClaw's bundled `claude-cli`
backend already uses) — this is a reasoning backend for an
already-trusted agent, not a sandboxed execution mode.
- **Model aliases are intentionally minimal.** Only `auto` → `grok-4.5` is
hardcoded; use literal model ids from `grok models` for anything else.
- Auth is whatever `grok login` already set up on the host (cached in
`~/.grok/auth.json`) — this plugin doesn't manage credentials itself.
`registerProvider`'s `auth` array is empty and `resolveSyntheticAuth`
returns a placeholder token purely so OpenClaw's "is this provider
authenticated" check passes — no credential is ever read, stored, or
exchanged by OpenClaw.
- **Both `registerCliBackend` *and* `registerProvider` are required** for a
`grok-cli/<model>` ref to resolve at all — see the sibling
`openclaw-cursor-cli` plugin's README for the full trace of why.
## License
MIT
tools
Comments
Sign in to leave a comment