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.

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 an xAI API key

   Set XAI_API_KEY in the gateway environment, or configure the key under the xAI plugin so the same credential covers code_execution, x_search, web search, and other xAI tools:

   export XAI_API_KEY=xai-...
   

   Or via config:

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

2. Enable and tune code_execution

   The tool is gated on plugins.entries.xai.config.codeExecution.enabled. Default is off.

   {
     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 env var and config path. The error is JSON, not a thrown exception, so the agent can self-correct:

{
  "error": "missing_xai_api_key",
  "message": "code_execution needs an 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