--- name: xai-plus description: | Search X/Twitter and the web, chat with Grok models (text + vision), and analyze X content using xAI's API. Use when: searching X posts/threads, web research via Grok, chatting with Grok, analyzing voice patterns, researching trends, or checking post quality. Triggers: grok, xai, search x, search twitter, x search, ask grok, grok chat, analyze voice, x trends. metadata: openclaw: emoji: "🔎" requires: bins: ["node"] env: ["XAI_API_KEY"] primaryEnv: "XAI_API_KEY" ---

xAI Skill

Search X (Twitter), search the web, chat with Grok models (including vision), and analyze X content patterns using xAI's API.

Features

• X Search: Search posts, threads, and accounts with date/handle filters
• Web Search: Search the web via Grok's web_search tool
• Chat: Text and vision (image analysis) with Grok models
• Analysis: Voice patterns, trend research, post safety checks
• Models: List available xAI models

Setup

API Key

Get your xAI API key from console.x.ai.

# Via clawdbot config (recommended)
clawdbot config set skills.entries.xai-plus.apiKey "xai-YOUR-KEY"

# Or environment variable
export XAI_API_KEY="xai-YOUR-KEY"

The scripts check these locations in order:

1. XAI_API_KEY env var
2. ~/.clawdbot/clawdbot.json → env.XAI_API_KEY
3. ~/.clawdbot/clawdbot.json → skills.entries.xai-plus.apiKey
4. ~/.clawdbot/clawdbot.json → skills.entries["grok-search"].apiKey (fallback)

Default Model (Optional)

Override the default model (grok-4-1-fast):

# Via config
clawdbot config set skills.entries.xai-plus.model "grok-3"

# Or environment variable
export XAI_MODEL="grok-3"

Model priority:

1. Command-line --model flag (highest priority)
2. XAI_MODEL env var
3. ~/.clawdbot/clawdbot.json → env.XAI_MODEL
4. ~/.clawdbot/clawdbot.json → skills.entries.xai-plus.model
5. Default: grok-4-1-fast

Search

X Search

Search X posts and threads with optional filters.

Basic search:

node {baseDir}/scripts/grok_search.mjs "query" --x

With date filter:

# Last 7 days
node {baseDir}/scripts/grok_search.mjs "Claude AI" --x --days 7

# Specific date range
node {baseDir}/scripts/grok_search.mjs "AI agents" --x --from 2026-01-01 --to 2026-01-31

Filter by handles:

# Only from specific accounts
node {baseDir}/scripts/grok_search.mjs "AI news" --x --handles @AnthropicAI,@OpenAI

# Exclude accounts
node {baseDir}/scripts/grok_search.mjs "GPT" --x --exclude @spam1,@spam2

Output formats:

# JSON (default, agent-friendly)
node {baseDir}/scripts/grok_search.mjs "query" --x

# Links only
node {baseDir}/scripts/grok_search.mjs "query" --x --links-only

# Human-readable text
node {baseDir}/scripts/grok_search.mjs "query" --x --text

JSON output schema:

{
  "query": "search query",
  "mode": "x",
  "results": [
    {
      "title": "@handle",
      "url": "https://x.com/handle/status/123",
      "snippet": "Post text...",
      "author": "@handle",
      "posted_at": "2026-01-15T10:30:00Z"
    }
  ],
  "citations": ["https://x.com/..."]
}

Web Search

Search the web via Grok.

node {baseDir}/scripts/grok_search.mjs "TypeScript best practices 2026" --web

JSON output schema:

{
  "query": "search query",
  "mode": "web",
  "results": [
    {
      "title": "Page title",
      "url": "https://example.com/page",
      "snippet": "Description...",
      "author": null,
      "posted_at": null
    }
  ],
  "citations": ["https://example.com/..."]
}

Search Options

| Flag | Description | Example | |------|-------------|---------| | --x | Search X/Twitter | Required for X search | | --web | Search the web | Required for web search | | --days N | Last N days (X only) | --days 7 | | --from YYYY-MM-DD | Start date (X only) | --from 2026-01-01 | | --to YYYY-MM-DD | End date (X only) | --to 2026-01-31 | | --handles a,b | Only these accounts (X only) | --handles @user1,@user2 | | --exclude a,b | Exclude accounts (X only) | --exclude @spam | | --max N | Max results | --max 20 | | --model ID | Override model | --model grok-3 | | --json | JSON output (default) | - | | --links-only | Just URLs | - | | --text | Human-readable | - | | --raw | Include debug output | - |

See references/search-patterns.md for advanced query patterns and optimization tips.

Chat

Text Chat

Ask Grok anything.

node {baseDir}/scripts/chat.mjs "What is quantum computing?"

With model override:

node {baseDir}/scripts/chat.mjs --model grok-3 "Explain transformers in ML"

JSON output:

node {baseDir}/scripts/chat.mjs --json "What is TypeScript?"

JSON schema:

{
  "model": "grok-4-1-fast",
  "prompt": "What is TypeScript?",
  "text": "TypeScript is...",
  "citations": ["https://..."]
}

Vision Chat

Analyze images with Grok.

node {baseDir}/scripts/chat.mjs --image ./screenshot.png "What's in this image?"

Multiple images:

node {baseDir}/scripts/chat.mjs --image ./pic1.jpg --image ./pic2.jpg "Compare these"

Supported formats: JPG, PNG, WebP, GIF

Chat Options

| Flag | Description | Example | |------|-------------|---------| | --model ID | Model to use | --model grok-2-vision-1212 | | --image PATH | Attach image (can repeat) | --image ./pic.jpg | | --json | JSON output | - | | --raw | Include debug output | - |

See references/models.md for model comparison and capabilities.

Analysis

Analyze X content for voice patterns, trends, and post quality.

Voice Analysis

Analyze an account's voice and writing patterns.

node {baseDir}/scripts/analyze.mjs voice @username

Custom date range:

# Last 60 days
node {baseDir}/scripts/analyze.mjs voice @username --days 60

JSON output schema:

{
  "handle": "@username",
  "analyzed_posts": 150,
  "voice": {
    "tone": "casual, technical",
    "personality": ["curious", "direct", "helpful"],
    "perspective": "practitioner sharing lessons",
    "energy_level": "medium"
  },
  "patterns": {
    "sentence_structure": ["short declarative", "occasional fragments"],
    "vocabulary": ["technical", "accessible"],
    "formatting_quirks": ["line breaks for emphasis", "minimal punctuation"],
    "recurring_phrases": ["here's the thing", "turns out"]
  },
  "topics": ["AI", "software engineering", "startups"],
  "best_posts": [
    {
      "url": "https://x.com/username/status/123",
      "text": "Post text...",
      "why": "Authentic voice, specific example"
    }
  ],
  "anti_patterns": ["never uses em-dashes", "avoids numbered lists"]
}

Trend Research

Research trends and discussions about a topic.

node {baseDir}/scripts/analyze.mjs trends "AI agents"

JSON output schema:

{
  "topic": "AI agents",
  "trends": [
    {
      "pattern": "Shift from chatbots to autonomous agents",
      "description": "Discussion focuses on...",
      "example_posts": ["https://x.com/..."]
    }
  ],
  "perspectives": [
    {
      "viewpoint": "Agents will replace most SaaS",
      "supporters": ["@user1", "@user2"]
    }
  ],
  "hashtags": ["#AIAgents", "#AutonomousAI"],
  "key_accounts": ["@researcher1", "@founder2"],
  "posting_angles": [
    {
      "angle": "Practical implementation challenges",
      "hook": "Everyone talks about AI agents. Nobody talks about...",
      "target_audience": "Engineers building with AI"
    }
  ]
}

Post Safety Check

Check a draft post or existing post for AI signals and platform flag patterns.

Check draft text:

node {baseDir}/scripts/analyze.mjs post "Your draft post text here"

...