xAI Plus

---
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](https://console.x.ai).

```bash
# 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`):

```bash
# 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:**
```bash
node {baseDir}/scripts/grok_search.mjs "query" --x
```

**With date filter:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```json
{
  "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.

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

**JSON output schema:**
```json
{
  "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](references/search-patterns.md) for advanced query patterns and optimization tips.

## Chat

### Text Chat

Ask Grok anything.

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

**With model override:**
```bash
node {baseDir}/scripts/chat.mjs --model grok-3 "Explain transformers in ML"
```

**JSON output:**
```bash
node {baseDir}/scripts/chat.mjs --json "What is TypeScript?"
```

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

### Vision Chat

Analyze images with Grok.

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

**Multiple images:**
```bash
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](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.

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

**Custom date range:**
```bash
# Last 60 days
node {baseDir}/scripts/analyze.mjs voice @username --days 60
```

**JSON output schema:**
```json
{
  "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.

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

**JSON output schema:**
```json
{
  "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:**
```bash
node {baseDir}/scripts/analyze.mjs post "Your draft post text here"
```

**Check existing post:**
```bash
node {baseDir}/scripts/analyze.mjs post --url "https://x.com/user/status/