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

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

1. Provide xAI credentials

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

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

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

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

   Or an API key:

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

   Or via config:

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

   Any of these three also power x_search and Grok web_search.

2. Enable and tune code_execution

   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:

   {
     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)
             },
           },
         },
       },
     },
   }
   
3. Restart the Gateway

   openclaw gateway restart
   

   code_execution appears in the agent’s tool list once the xAI plugin re-registers and the provider, enablement, and auth checks above pass.

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

Exec tool

Local shell execution on your machine or paired node.

Exec approvals

Allow/deny policy for shell execution.

Web tools

web_search, x_search, and web_fetch.

xAI provider

Grok models, web/x search, and code execution config.