Grok CLI + ACP as OpenClaw Agent Backend — Complete Setup Guide

Wiring Grok CLI into OpenClaw via Agent Client Protocol

If you're running OpenClaw and want to use your Grok subscription (not xAI API credits) as an agent backend, here's how to set it up through the local Grok CLI and ACP (Agent Client Protocol).

What This Gives You

• Grok CLI model route (grok-cli/grok-build) — one-shot agent turns via local Grok CLI
• Grok ACP runtime (grok agent stdio) — multi-turn persistent sessions over JSON-RPC
• All billing through your Grok subscription, zero xAI API key usage

Architecture

OpenClaw agent
  → @openclaw/acpx runtime
    → grok agent stdio
      → local Grok CLI auth/session
        → Grok subscription-backed model

Prerequisites

1. Install and authenticate Grok CLI:

   grok login
   grok -p "Say GROK_OK and nothing else"
   

2. OpenClaw with ACPX enabled

OpenClaw Config

Add the ACPX agent target:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "grok": {
              "command": "grok",
              "args": ["agent", "stdio"]
            }
          },
          "probeAgent": "grok",
          "timeoutSeconds": 240
        }
      }
    }
  }
}

⚠️ Critical Dispatch Rule

When spawning Grok agents as sub-agents, always use ACP runtime, not the CLI model route:

❌ Wrong (returns empty):

{ "task": "...", "model": "grok-cli/grok-build" }

✅ Correct (works reliably):

{ "task": "...", "runtime": "acp", "agentId": "grok" }

The Compatibility Bug

Grok ACP doesn't support session/set_config_option. OpenClaw forwards runtime values (timeout, model, reasoning) that Grok rejects with -32601 Method not found.

The fix: patch the ACPX runtime to drop unsupported config keys before they reach Grok. This is a node_modules hot patch — re-verify after OpenClaw updates.

Post-Update Verification

bash scripts/check-grok-acp-patches.sh

Full Setup Guide

Complete walkthrough with smoke tests, patch details, and troubleshooting: [GitHub repo coming soon]

---

Squad using this route: Elon ⚡ (Coder), Frozone 🧊 (Reviewer), Voyd 🌀 (Research), Edna ✂️ (Design) — all running on Grok Super Heavy subscription.