home / skills / openclaw / skills / grok-search

grok-search skill

safe

This skill helps you search web or X/Twitter using xAI Grok server-side tools to return structured JSON with citations.

npx playbooks add skill openclaw/skills --skill grok-search

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

2.4 KB

---
name: grok-search
description: Search the web or X/Twitter using xAI Grok server-side tools (web_search, x_search) via the xAI Responses API. Use when you need tweets/threads/users from X, want Grok as an alternative to Brave, or you need structured JSON + citations.
homepage: https://docs.x.ai/docs/guides/tools/search-tools
triggers: ["grok", "xai", "search x", "search twitter", "find tweets", "x search", "twitter search", "web_search", "x_search"]
metadata: {"clawdbot":{"emoji":"🔎","requires":{"bins":["node"],"env":["XAI_API_KEY"]},"primaryEnv":"XAI_API_KEY"}}
---

Run xAI Grok locally via bundled scripts (search + chat + model listing). Default output for search is *pretty JSON* (agent-friendly) with citations.

## API key

The script looks for an xAI API key in this order:
- `XAI_API_KEY` env var
- `~/.clawdbot/clawdbot.json` → `env.XAI_API_KEY`
- `~/.clawdbot/clawdbot.json` → `skills.entries["grok-search"].apiKey`
- fallback: `skills.entries["search-x"].apiKey` or `skills.entries.xai.apiKey`

## Run

Use `{baseDir}` so the command works regardless of workspace layout.

### Search

- Web search (JSON):
  - `node {baseDir}/scripts/grok_search.mjs "<query>" --web`

- X/Twitter search (JSON):
  - `node {baseDir}/scripts/grok_search.mjs "<query>" --x`

### Chat

- Chat (text):
  - `node {baseDir}/scripts/chat.mjs "<prompt>"`

- Chat (vision):
  - `node {baseDir}/scripts/chat.mjs --image /path/to/image.jpg "<prompt>"`

### Models

- List models:
  - `node {baseDir}/scripts/models.mjs`

## Useful flags

Output:
- `--links-only` print just citation URLs
- `--text` hide the citations section in pretty output
- `--raw` include the raw Responses API payload on stderr (debug)

Common:
- `--max <n>` limit results (default 8)
- `--model <id>` (default `grok-4-1-fast`)

X-only filters (server-side via x_search tool params):
- `--days <n>` (e.g. 7)
- `--from YYYY-MM-DD` / `--to YYYY-MM-DD`
- `--handles @a,@b` (limit to these handles)
- `--exclude @bots,@spam` (exclude handles)

## Output shape (JSON)

```json
{
  "query": "...",
  "mode": "web" | "x",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "author": "...",
      "posted_at": "..."
    }
  ],
  "citations": ["https://..."]
}
```

## Notes

- `citations` are merged/validated from xAI response annotations where possible (more reliable than trusting the model’s JSON blindly).
- Prefer `--x` for tweets/threads, `--web` for general research.

Overview

This skill lets you run xAI Grok server-side tools to search the web or X/Twitter and produce agent-friendly JSON results with validated citations. It provides bundled scripts for web and X searches, chat, and model listing, and prefers structured JSON output suitable for downstream automation. Use it when you need tweets, threads, or users from X, an alternative Grok-based search, or reliable JSON + citation metadata.

How this skill works

The skill invokes Grok via small node scripts that call the xAI Responses API tools (web_search and x_search). It collects results, merges and validates citation annotations from the API, and returns a consistent JSON shape containing query, mode, results, and citations. The scripts support chat and vision modes, model listing, and flags for output format, limits, and X-specific filters.

When to use it

Collect tweets, threads, or user posts from X/Twitter programmatically.
Perform web research that needs structured JSON results and source citations.
Integrate Grok-based search into agents, pipelines, or archival workflows.
Debug or inspect Grok Responses API payloads while developing search features.
Filter X results by date range, handles, or exclusions on the server side.

Best practices

Prefer --x for X/Twitter queries and --web for general web research to get more relevant results.
Use the --max flag to limit results for faster runs and predictable output sizes.
Enable --raw when debugging to see the original Responses API payload on stderr.
Use --links-only when you only need citation URLs to speed parsing and reduce output noise.
Store the xAI API key in an environment variable or the configured skills entry to avoid interactive prompts.

Example use cases

Archive recent tweets about a breaking news topic with --days and --max to collect a compact dataset.
Produce JSON-backed research summaries with web citations for an agent that composes reports.
Filter posts from a set of handles and exclude bot accounts before feeding results into moderation tooling.
Run vision-enabled chat on an image to combine visual context with web lookups for richer responses.
List available Grok models and switch to grok-4-1-fast or another model via the --model flag.

FAQ

How does the skill find the xAI API key?

It checks XAI_API_KEY env var first, then configuration entries in a local clawdbot config path, and falls back to related skill entries if present.

Can I get just URLs or hide citations?

Yes. Use --links-only to print only citation URLs and --text to hide the citations section in pretty output.