Grok Search

Use Grok Search for freshness-first research.

Prefer it when the task is about:

• breaking news
• X/Twitter chatter
• fast-moving narratives
• “what are people saying now?”
• quick multi-source synthesis
• comparing official claims vs community discussion

Do not default to Grok Search for:

• official docs lookup
• API/reference pages
• pricing / plan details
• direct page text extraction
• canonical source retrieval

For those, prefer

exa-search

.

Workflow

1. Use

   --mode news

   for fresh updates.
2. Use

   --mode social

   for X/Twitter and discourse-heavy prompts.
3. Use

   --mode research

   for broad multi-source synthesis.
4. Use

   --mode docs-compare

   when you want official claims plus community interpretation.
5. Use

   --plain

   for human-readable terminal output.
6. Use

   --profile <id>

   when testing one key or diagnosing failover.
7. Use

   --ignore-cooldown

   only when you intentionally want to override a temporary cooldown and force another try.

Config

Preferred key resolution order:

1. --api-key

2. GROK_API_KEY

3. GROK_API_KEYS

   (comma-separated)

4. config.local.json

5. config.json

6. ~/.codex/config/grok-search.json

Recommended setup for this workspace: keep the real key(s) inside the skill folder in

config.local.json

so the whole skill can be backed up and moved as one directory.

Single key

{
  "profiles": [
    { "id": "main", "api_key": "YOUR_GROK_API_KEY" }
  ]
}

Multiple keys with auto failover

{
  "profiles": [
    { "id": "main", "api_key": "KEY_1" },
    { "id": "backup-1", "api_key": "KEY_2" },
    { "id": "backup-2", "api_key": "KEY_3" }
  ],
  "base_url": "https://your-grok-endpoint.example",
  "model": "grok-4.1-fast",
  "timeout_seconds": 120,
  "extra_body": {},
  "extra_headers": {},
  "cooldown": {
    "enabled": true,
    "state_file": "runtime/cooldowns.json",
    "default_minutes": 15,
    "rate_limit_minutes": 20,
    "quota_minutes": 60,
    "auth_minutes": 360
  }
}

Failover behavior:

• profiles are tried in order
• 401 / 403 / 429 and quota / billing / rate-limit / token-unavailable style errors automatically move to the next key
• output includes

  profileId

  and

  attempts

Cooldown behavior:

• failover-worthy failures place the profile into temporary cooldown
• cooldown state lives in

  runtime/cooldowns.json

  by default
• later runs will skip cooling profiles instead of hammering the same failing key again
• use

  --ignore-cooldown

  if you intentionally want to force a retry

Commands

General live research

python3 scripts/grok_search.py --query "What changed in OpenClaw recently?"

Breaking-news style lookup

python3 scripts/grok_search.py --mode news --query "Latest OpenClaw Telegram streaming changes"

Social/discourse lookup

python3 scripts/grok_search.py --mode social --query "What are people saying about OpenClaw on X?"

Multi-source synthesis

python3 scripts/grok_search.py --mode research --query "Summarize recent discussion around OpenClaw model failover"

Official docs vs community interpretation

python3 scripts/grok_search.py --mode docs-compare --query "Compare OpenClaw official docs and community discussion on Telegram streaming"

Force one profile

python3 scripts/grok_search.py --query "OpenClaw Telegram streaming" --profile main

Notes

• This skill is optimized for freshness and breadth, not canonical-source purity.

• docs-compare

  now explicitly separates official facts from community interpretation.
• If the answer must come from official docs, switch to

  exa-search

  .
• Use

  references/query-recipes.md

  for reusable query patterns.