mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 10:00:42 +00:00
docs(tools): rewrite loop detection, code execution, and tighten elevated/skills
Loop detection (docs/tools/loop-detection.md): substantial rewrite. Fixed the post-compaction guard default story — the guard runs whenever tools.loopDetection.enabled is not explicitly false, even with no config block at all (verified in src/agents/pi-embedded-runner/run.ts near line 800: 'enabled: resolvedLoopDetectionConfig?.enabled !== false'). The previous doc framed it as opt-in. Added the missing unknownToolThreshold field (default 10) sourced from src/config/schema.help.ts, a complete fields table, and a CardGroup related links section. Code execution (docs/tools/code-execution.md): rewrote with Steps-driven setup, code-verified defaults from extensions/xai/src/code-execution-shared.ts (default model grok-4-1-fast, default timeout 30 s, optional maxTurns), the missing_xai_api_key structured error documented as JSON, and a properties summary table. Replaced the trailing bullet list with a CardGroup pointing at exec, exec-approvals, web tools, and the xAI provider page. Elevated (docs/tools/elevated.md): converted Related to a CardGroup and added a Note that the bash chat command (! prefix / /bash alias) also requires tools.elevated, sourced from src/config/schema.help.ts:1375. Skills config (docs/tools/skills-config.md): renamed the 'Sandboxed skills + env vars' subhead to remove the brittle '+' character per docs/CLAUDE.md, promoted the host-only env warning to a Warning block so the most common skill-config footgun stays visible, and converted Related to a CardGroup including a config-reference link.
This commit is contained in:
Vincent Koc
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "code_execution -- run sandboxed remote Python analysis with xAI"
|
||||
summary: "code_execution: run sandboxed remote Python analysis with xAI"
|
||||
read_when:
|
||||
- You want to enable or configure code_execution
|
||||
- You want remote analysis without local shell access
|
||||
@@ -7,53 +7,95 @@ read_when:
|
||||
title: "Code execution"
|
||||
---
|
||||
|
||||
`code_execution` runs sandboxed remote Python analysis on xAI's Responses API.
|
||||
`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_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`](/tools/exec):
|
||||
|
||||
- `exec` runs shell commands on your machine or node
|
||||
- `code_execution` runs Python in xAI's remote sandbox
|
||||
- `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`
|
||||
- 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`](/tools/exec) for that.
|
||||
Do **not** use it when you need local files, your shell, your repo, or paired devices. Use [`exec`](/tools/exec) for that.
|
||||
|
||||
## Setup
|
||||
|
||||
You need an xAI API key. Any of these work:
|
||||
<Steps>
|
||||
<Step title="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:
|
||||
|
||||
- `XAI_API_KEY`
|
||||
- `plugins.entries.xai.config.webSearch.apiKey`
|
||||
```bash
|
||||
export XAI_API_KEY=xai-...
|
||||
```
|
||||
|
||||
Example:
|
||||
Or via config:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
xai: {
|
||||
config: {
|
||||
webSearch: {
|
||||
apiKey: "xai-...",
|
||||
},
|
||||
codeExecution: {
|
||||
enabled: true,
|
||||
model: "grok-4-1-fast",
|
||||
maxTurns: 2,
|
||||
timeoutSeconds: 30,
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
xai: {
|
||||
config: {
|
||||
webSearch: {
|
||||
apiKey: "xai-...",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Enable and tune code_execution">
|
||||
The tool is gated on `plugins.entries.xai.config.codeExecution.enabled`. Default is off.
|
||||
|
||||
```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)
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Restart the Gateway">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
`code_execution` shows up in the agent's tool list once the xAI plugin re-registers with `enabled: true`.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## How to use it
|
||||
|
||||
@@ -71,20 +113,40 @@ Use x_search to find posts mentioning OpenClaw this week, then use code_executio
|
||||
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.
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
- It should be treated as ephemeral analysis, not a persistent notebook.
|
||||
- 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`](/tools/web#x_search) first.
|
||||
- For fresh X data, use [`x_search`](/tools/web#x_search) first and pipe the result into `code_execution`.
|
||||
|
||||
## Related
|
||||
|
||||
- [Exec tool](/tools/exec)
|
||||
- [Exec approvals](/tools/exec-approvals)
|
||||
- [apply_patch tool](/tools/apply-patch)
|
||||
- [Web tools](/tools/web)
|
||||
- [xAI](/providers/xai)
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Exec tool" href="/tools/exec" icon="terminal">
|
||||
Local shell execution on your machine or paired node.
|
||||
</Card>
|
||||
<Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
|
||||
Allow/deny policy for shell execution.
|
||||
</Card>
|
||||
<Card title="Web tools" href="/tools/web" icon="globe">
|
||||
`web_search`, `x_search`, and `web_fetch`.
|
||||
</Card>
|
||||
<Card title="xAI provider" href="/providers/xai" icon="microchip">
|
||||
Grok models, web/x search, and code execution config.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Reference in New Issue
Block a user