Tools: add x_search via xAI Responses

docs/tools/web.md

@@ -1,11 +1,12 @@
 ---
-summary: "web_search tool -- search the web with Brave, Firecrawl, Gemini, Grok, Kimi, Perplexity, or Tavily"
-read_when:
-  - You want to enable or configure web_search
-  - You need to choose a search provider
-  - You want to understand auto-detection and provider fallback
 title: "Web Search"
 sidebarTitle: "Web Search"
+summary: "web_search, x_search, and web_fetch -- search the web, search X posts, or fetch page content"
+read_when:
+  - You want to enable or configure web_search
+  - You want to enable or configure x_search
+  - You need to choose a search provider
+  - You want to understand auto-detection and provider fallback
 ---
 
 # Web Search
@@ -13,6 +14,10 @@ sidebarTitle: "Web Search"
 The `web_search` tool searches the web using your configured provider and
 returns results. Results are cached by query for 15 minutes (configurable).
 
+OpenClaw also includes `x_search` for X (formerly Twitter) posts and
+`web_fetch` for lightweight URL fetching. In this phase, `web_fetch` stays
+local while `web_search` and `x_search` can use xAI Responses under the hood.
+
 <Info>
   `web_search` is a lightweight HTTP tool, not browser automation. For
   JS-heavy sites or logins, use the [Web Browser](/tools/browser). For
@@ -40,6 +45,12 @@ returns results. Results are cached by query for 15 minutes (configurable).
     await web_search({ query: "OpenClaw plugin SDK" });
     ```
 
+    For X posts, use:
+
+    ```javascript
+    await x_search({ query: "dinner recipes" });
+    ```
+
   </Step>
 </Steps>
 
@@ -136,6 +147,9 @@ Provider-specific config (API keys, base URLs, modes) lives under
 `plugins.entries.<plugin>.config.webSearch.*`. See the provider pages for
 examples.
 
+For `x_search`, configure `tools.web.x_search.*` directly. It uses the same
+`XAI_API_KEY` fallback as Grok web search.
+
 ### Storing API keys
 
 <Tabs>
@@ -195,6 +209,55 @@ examples.
   -- use their dedicated tools for advanced options.
 </Warning>
 
+## x_search
+
+`x_search` queries X (formerly Twitter) posts using xAI and returns
+AI-synthesized answers with citations. It accepts natural-language queries and
+optional structured filters. OpenClaw only enables the built-in xAI `x_search`
+tool on the request that serves this tool call.
+
+### x_search config
+
+```json5
+{
+  tools: {
+    web: {
+      x_search: {
+        enabled: true,
+        apiKey: "xai-...", // optional if XAI_API_KEY is set
+        model: "grok-4-1-fast-non-reasoning",
+        inlineCitations: false,
+        maxTurns: 2,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+      },
+    },
+  },
+}
+```
+
+### x_search parameters
+
+| Parameter                    | Description                                            |
+| ---------------------------- | ------------------------------------------------------ |
+| `query`                      | Search query (required)                                |
+| `allowed_x_handles`          | Restrict results to specific X handles                 |
+| `excluded_x_handles`         | Exclude specific X handles                             |
+| `from_date`                  | Only include posts on or after this date (YYYY-MM-DD)  |
+| `to_date`                    | Only include posts on or before this date (YYYY-MM-DD) |
+| `enable_image_understanding` | Let xAI inspect images attached to matching posts      |
+| `enable_video_understanding` | Let xAI inspect videos attached to matching posts      |
+
+### x_search example
+
+```javascript
+await x_search({
+  query: "dinner recipes",
+  allowed_x_handles: ["nytfood"],
+  from_date: "2026-03-01",
+});
+```
+
 ## Examples
 
 ```javascript
@@ -223,13 +286,13 @@ await web_search({
 
 ## Tool profiles
 
-If you use tool profiles or allowlists, add `web_search` or `group:web`:
+If you use tool profiles or allowlists, add `web_search`, `x_search`, or `group:web`:
 
 ```json5
 {
   tools: {
-    allow: ["web_search"],
-    // or: allow: ["group:web"]  (includes both web_search and web_fetch)
+    allow: ["web_search", "x_search"],
+    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
   },
 }
 ```
@@ -238,3 +301,4 @@ If you use tool profiles or allowlists, add `web_search` or `group:web`:
 
 - [Web Fetch](/tools/web-fetch) -- fetch a URL and extract readable content
 - [Web Browser](/tools/browser) -- full browser automation for JS-heavy sites
+- [Grok Search](/tools/grok-search) -- Grok as the `web_search` provider