Grok Local

grok_local runs xAI's Grok Build CLI on the same machine as Paperclip. Use it when you want a local coding agent that resumes the same Grok session across heartbeats, with Paperclip skills staged automatically into Grok's native discovery paths.

When To Use

Grok CLI is installed and authenticated on the machine that runs Paperclip.
You want a local coding agent with resumable sessions across heartbeats via --resume.
You want Paperclip-managed instructions and skills staged into the execution workspace using Grok's native discovery paths (Agents.md and .claude/skills).

When Not To Use

The agent runs behind a webhook or remote endpoint. Use HTTP or OpenClaw Gateway instead.
You only need a one-shot script without a coding-agent loop. Use Process.
Grok CLI is not installed or not authenticated on the host.

Common Fields

Field	Required	Notes
`cwd`	no	Default absolute working directory for the agent process. Paperclip creates the path when permissions allow.
`instructionsFilePath`	no	Absolute path to a markdown instructions file (typically `AGENTS.md`). Paperclip stages it into the execution workspace as `Agents.md` when safe, otherwise falls back to `--rules @file`.
`promptTemplate`	no	Prompt template used for the run.
`model`	no	Grok model id. Defaults to `grok-build`.
`permissionMode`	no	Grok permission mode. Defaults to `dontAsk`.
`reasoningEffort`	no	Grok reasoning effort passed via `--reasoning-effort`.
`maxTurns`	no	Maximum agent turns for the run.
`command`	no	Defaults to `grok`. Override only if Grok lives elsewhere on the host.
`extraArgs`	no	Extra CLI arguments appended to the Grok invocation.
`env`	no	Environment variables passed to Grok. Secret refs are supported.
`timeoutSec`	no	Run timeout in seconds.
`graceSec`	no	SIGTERM grace period in seconds.

Note: Runs use grok --single with --output-format streaming-json. The streaming reasoning channel now keeps line breaks between separate thoughts, so the live Working panel no longer merges them into run-on text.

Session Persistence

Grok Local saves the Grok session id and resumes it on the next heartbeat with --resume <sessionId> — but only when the saved session's cwd matches the current cwd. If the directory has moved, the adapter starts a fresh session.

The session codec preserves the same location hints used by other local adapters:

cwd
workspaceId
repoUrl
repoRef

Tip: Use grok models on the host to confirm authentication and inspect available models before saving the adapter.

Skills Injection

Paperclip stages the runtime skills you've enabled for the agent into .claude/skills inside the execution workspace. Grok discovers them as project skills automatically — there's nothing extra to wire up.

If you supply an instructionsFilePath, Paperclip prefers staging it into the workspace as Agents.md so Grok picks it up natively. When that isn't safe (for example, when the workspace already has an Agents.md that doesn't belong to Paperclip), the adapter falls back to --rules @file.

Example

{
  "adapterType": "grok_local",
  "adapterConfig": {
    "cwd": "/Users/me/projects/paperclip-workspace",
    "model": "grok-build",
    "permissionMode": "dontAsk",
    "reasoningEffort": "medium",
    "instructionsFilePath": "/Users/me/projects/paperclip-workspace/AGENTS.md",
    "env": {
      "XAI_API_KEY": {
        "type": "secret_ref",
        "secretId": "secret-id",
        "version": "latest"
      }
    },
    "timeoutSec": 300,
    "graceSec": 15,
    "maxTurns": 200
  }
}

Everything you need to run Paperclip.