Code Execution Tool for Sandboxed Python Analysis

code_execution executes remote Python code in a sandboxed environment through xAI's Responses API (https://api.x.ai/v1/responses, the same endpoint x_search relies on). The bundled xai plugin registers it under the tools contract.

Warning

code_execution operates on xAI infrastructure. Each 1,000 tool calls incur a $5 charge from xAI, in addition to the model's input and output token costs.

Property	Value
Tool name	`code_execution`
Provider plugin	`xai` (included, `enabledByDefault: true`)
Auth	xAI authentication profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey`
Default model	`grok-4.3`
Default timeout	30 seconds
Default `maxTurns`	not set (xAI enforces its own internal cap)

Apply this tool to calculations, tabulation, quick statistics, and chart-style work, including data produced by x_search or web_search. It cannot reach local files, your shell, your repository, or paired devices, and no state carries over between invocations, so treat each call as an isolated analysis rather than a notebook session. For current X data, first run x_search and feed the output into this tool.

For execution on your own machine, choose exec instead.

Setup

Provide xAI credentials

OAuth requires a qualifying SuperGrok or X Premium subscription (device-code flow is used, so remote hosts work without a localhost callback):

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

During a first-time setup, the same option appears in onboarding:

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

Or supply an API key:

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

Or through configuration:

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

Any of these three also enable x_search and Grok web_search.

Enable and tune code_execution

When enabled is absent, code_execution is only visible if the active model's provider is xai and xAI credentials are available. For an active model backed by a known non-xAI provider, set plugins.entries.xai.config.codeExecution.enabled to true to permit cross-provider usage. If the active model's provider is unknown or cannot be resolved, the tool remains hidden. Set enabled to false to turn it off for every provider. xAI credentials are mandatory in all cases.

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

{
  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)
          },
        },
      },
    },
  },
}

Restart the Gateway

openclaw gateway restart

Once the xAI plugin re-registers and the provider, enablement, and authentication checks described above pass, code_execution appears in the agent's tool list.

How to use it

Make the analysis goal clear; the tool accepts a single task parameter, so include the entire 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 authentication, the tool returns a structured JSON error (not a raised exception), allowing the agent to correct itself:

{
  "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"
}

Exec tool, Runs shell commands locally on your machine or a paired node.
Exec approvals, Policy to allow or deny shell execution.
Web tools, web_search, x_search, and web_fetch.
xAI provider, Configuration for Grok models, web/x search, and code execution.