openclaw/docs/tools/code-execution.md

summary, read_when, title

summary	read_when	title
code_execution: run sandboxed remote Python analysis with xAI	You want to enable or configure code_execution You want remote analysis without local shell access You want to combine x_search or web_search with remote Python analysis	Code execution

code_execution runs sandboxed remote Python analysis on xAI's Responses API (https://api.x.ai/v1/responses, same endpoint x_search uses). It is registered by the bundled xai plugin under the tools contract.

`code_execution` runs on xAI's servers. xAI bills $5 per 1,000 tool calls, plus the model's input and output tokens.

Property	Value
Tool name	code_execution
Provider plugin	xai (bundled, enabledByDefault: true)
Auth	xAI auth profile, XAI_API_KEY, or plugins.entries.xai.config.webSearch.apiKey
Default model	grok-4.7
Default timeout	30 seconds
Default maxTurns	unset (xAI applies its own internal limit)

Existing installations that omit the tool model setting also use Grok 4.7. An explicit model setting remains selected.

Use it for calculations, tabulation, quick statistics, and chart-style analysis, including data returned by x_search or web_search. It has no access to local files, your shell, your repo, or paired devices, and it does not persist state between calls, so treat each call as ephemeral analysis, not a notebook session. For fresh X data, run x_search first and pipe the result in.

For local execution, use exec instead.

Setup

OAuth requires an eligible SuperGrok or X Premium subscription (device-code verification, so it works from remote hosts without a localhost callback):

```bash
openclaw models auth login --provider xai --method oauth
```

During a fresh install, the same choice is available in onboarding:

```bash
openclaw onboard --install-daemon --auth-choice xai-oauth
```

Or an API key:

```bash
openclaw models auth login --provider xai --method api-key
export XAI_API_KEY=xai-...
```

Or via config:

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          webSearch: {
            apiKey: "xai-...",
          },
        },
      },
    },
  },
}
```

Any of these three also power `x_search` and Grok `web_search`.

With `enabled` omitted, `code_execution` is exposed only when the active model's provider is `xai` and xAI credentials resolve. For an active model with a known non-xAI provider, set `plugins.entries.xai.config.codeExecution.enabled` to `true` to opt in to cross-provider use. If the active model provider is missing or unresolved, the tool stays hidden. Set `enabled` to `false` to disable it for every provider. xAI credentials are always required.

Use the same block to override the model, turn cap, or timeout:

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true, // required for a known non-xAI model provider
            model: "grok-4.3", // override the default xAI code-execution model
            maxTurns: 2,            // optional cap on internal tool turns
            timeoutSeconds: 30,     // request timeout (default: 30)
          },
        },
      },
    },
  },
}
```

With the default hybrid reload mode, plugin config changes apply automatically.
If the Gateway is offline, start it after configuration. See
[Config hot reload](/gateway/configuration/hot-reload).

Send `/tools` in the target conversation and check for `code_execution` after
the provider, enablement, and auth checks above pass. If you changed the
Gateway service's process environment, restart that service to load it.

How to use it

Make the analysis intent explicit; the tool takes a single task parameter, so send the full request and any inline data in one prompt:

Use code_execution to calculate the 7-day moving average for these numbers: ...

Use x_search to find posts mentioning OpenClaw this week, then use code_execution to count them by day.

Use web_search to gather the latest AI benchmark numbers, then use code_execution to compare percent changes.

Errors

Without auth, the tool returns a structured JSON error (not a thrown exception), so the agent can self-correct:

{
  "error": "missing_xai_api_key",
  "message": "code_execution needs xAI credentials. Run `openclaw onboard --auth-choice xai-oauth` to sign in with Grok, run `openclaw onboard --auth-choice xai-api-key`, set `XAI_API_KEY` in the Gateway environment, or configure `plugins.entries.xai.config.webSearch.apiKey`.",
  "docs": "https://docs.openclaw.ai/tools/code-execution"
}

Related

Local shell execution on your machine or paired node. Allow/deny policy for shell execution. `web_search`, `x_search`, and `web_fetch`. Grok models, web/x search, and code execution config. A separate surface: JavaScript orchestration of enabled tools in OpenClaw's own worker, not this remote Python tool.