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

1. Provide xAI credentials

   Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription, use the remote-friendly device-code flow, or store an API key. OAuth works for code_execution and x_search; XAI_API_KEY or plugin web-search config can also power Grok web_search.

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

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

   openclaw onboard --install-daemon
   openclaw onboard --install-daemon --auth-choice xai-device-code

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

2. Enable and tune code_execution

   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.

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

3. Restart the Gateway

   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

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.