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. It is registered by the bundled xai plugin (under the tools contract) and dispatches to the same https://api.x.ai/v1/responses endpoint used by x_search.

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-1-fast
Default timeout	30 seconds
Default maxTurns	unset (xAI applies its own internal limit)

This is different from local exec:

• exec runs shell commands on your machine or paired node.
• code_execution runs Python in xAI's remote sandbox.

Use code_execution for:

• Calculations.
• Tabulation.
• Quick statistics.
• Chart-style analysis.
• Analyzing data returned by x_search or web_search.

Do not use it when you need local files, your shell, your repo, or paired devices. Use exec for that.

Setup

Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription, or store an API key. xAI OAuth uses device-code verification, so it works from remote hosts without a localhost callback. OAuth works for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search config can also power Grok `web_search`.

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

During a fresh install, the same auth choices are available inside
onboarding:

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

Or use 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-...",
          },
        },
      },
    },
  },
}
```

`code_execution` is available when xAI credentials are available. Set `plugins.entries.xai.config.codeExecution.enabled` to `false` to disable it, or use the same block to tune the model and timeout.

```json5
{
  plugins: {
    entries: {
      xai: {
        config: {
          codeExecution: {
            enabled: true,
            model: "grok-4-1-fast", // override the default xAI code-execution model
            maxTurns: 2,            // optional cap on internal tool turns
            timeoutSeconds: 30,     // request timeout (default: 30)
          },
        },
      },
    },
  },
}
```

```bash openclaw gateway restart ```

`code_execution` shows up in the agent's tool list once the xAI plugin re-registers with `enabled: true`.

How to use it

Ask naturally and make the analysis intent explicit:

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.

The tool takes a single task parameter internally, so the agent should send the full analysis request and any inline data in one prompt.

Errors

When the tool runs without auth, it returns a structured missing_xai_api_key error pointing at the auth-profile, env var, and config options. The error is JSON, 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"
}

Limits

• This is remote xAI execution, not local process execution.
• Treat results as ephemeral analysis, not a persistent notebook session.
• Do not assume access to local files or your workspace.
• For fresh X data, use x_search first and pipe the result into 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.