# Grok Search > Use when the user explicitly asks to search the web, check latest/current facts, fetch a URL, or discover pages on a website. Also use when the user asks to install, configure, or setup grok-search (API URL/key, chat vs responses). Do not use for local code search or stable offline knowledge unless the user asks for live web access. - **Type:** Skill - **Install:** `agentstack add skill-autsunset-grok-search-grok-search` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Autsunset](https://agentstack.voostack.com/s/autsunset) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Autsunset](https://github.com/Autsunset) - **Source:** https://github.com/Autsunset/grok-search ## Install ```sh agentstack add skill-autsunset-grok-search-grok-search ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Grok Search Node scripts for web search, URL fetch, and lightweight site mapping. Run `npm install` once if dependencies are not installed, then run the scripts directly — there is no MCP server or extension to call. ## Install Or Configure (agent wizard) When the user asks to **install / configure / setup** this skill, follow **README.md →「Agent 安装与配置向导」** (English: README.en.md →「Agent setup wizard」). Do not improvise a shorter flow. Order: 1. **Self-check** Node `>=18.17`, skill path, `npm install`, existing `~/.config/grok-search/config.json` (mask any key). 2. **Ask protocol**: `chat` (grok2api/NewAPI; `grok-4.3-fast` / `grok-4.20-*`) vs `responses` (CPA-style; often `grok-4.5` only). 3. **Ask** `apiUrl` (base only) and `apiKey` (never echo full key). 4. **Ask** model id; write `~/.config/grok-search/config.json` with mode `600`. 5. **Ask** whether to test. Only if yes, run: `node "$SKILL_ROOT/scripts/search.js" --no-extra "随便搜个新闻"` 6. **Success** if exit 0, no `error`, `diagnostics.grok_endpoint` matches choice, non-empty `answer.text`. 7. **On failure**, branch by `error` / HTTP status / empty search (401 key, 404 protocol/URL, 422 model, quota, proxy, model_not_found, no citations) and ask the user for the specific fix — then retest only if they agree. If search later returns `GROK_API_URL 未配置` or `GROK_API_KEY 未配置`, run this wizard instead of inventing env vars. ## Choose The Script Decide before running, by what the user already gave you: - They gave a URL and asked what it says → `scripts/fetch.js`. - They named a site but no URL, and want to know what is on it → `scripts/map.js`, then `fetch.js` on the URLs you pick. - They want current/latest information, or the URL is unknown → `scripts/search.js`. Do not chain map → fetch → search by default. Run the fewest commands that answer the question. If sub-questions are independent (different sites, unrelated facts), launch the commands in parallel instead of sequentially. ## Commands ```bash ./scripts/search.js "query" ./scripts/search.js --search-endpoint chat --model grok-4.3-fast "query" ./scripts/search.js --platform GitHub "query" ./scripts/search.js --extra 10 "query" ./scripts/search.js --no-extra "query" ./scripts/search.js --source-chars 200 "query" ./scripts/search.js --responses-openrouter-engine exa "strict web-only query" ./scripts/search.js --responses-x-search --responses-allowed-x-handles xai,OpenAI "query" ``` ```bash ./scripts/fetch.js https://example.com ./scripts/fetch.js --provider direct https://example.com ``` Use `./scripts/fetch.js --max-chars 50000 URL` only for an explicit deep read after the preview shows the page is worth reading. ```bash ./scripts/map.js https://docs.example.com --limit 20 ./scripts/map.js --provider direct https://docs.example.com ./scripts/map.js https://docs.example.com --instructions "only API reference pages" --max-depth 2 ``` Search supports two Grok protocols via `searchEndpoint` / `--search-endpoint`: - `responses` (default): `{apiUrl}/responses` + agentic `web_search`. Typical for CPA / xAI-style search (e.g. `grok-4.5`). - `chat`: `{apiUrl}/chat/completions` + `web_search` tools. Typical for grok2api / NewAPI with `grok-4.3-fast`, `grok-4.20-fast`, or `grok-4.20-0309-non-reasoning`. On many relays, Responses search only works for CPA `grok-4.5`; prefer chat for the fast Grok models above. Both paths run alongside independent Tavily and Firecrawl searches. Tavily is used when its key is configured; Firecrawl works keyless and automatically uses `FIRECRAWL_API_KEY` when available. The default combined extra target is 6. Add `--extra 10` only for a broader candidate-source sweep. Extras are never fed into Grok. If Grok quota is explicitly exhausted, `search.js` may return a visibly marked degraded answer made from raw Tavily/Firecrawl results. Check `diagnostics.degraded` and `diagnostics.grok_error`. Other Grok failures remain errors. `--no-extra` disables this fallback as well as the external searches. ## Reading Results Each script writes a single JSON object to stdout. On failure it still writes JSON to stdout, a short message to stderr, and exits non-zero. Check in this order: - `error` — if present, read `error.message`, `error.code`, `error.preview` if present, and `diagnostics.provider_attempts`. Before retrying, change something: a sharper query, a different `--provider` (fetch/map), or a different `--model` (search). Do not rerun the same command. - `diagnostics.warnings` and `diagnostics.provider_attempts` — these tell you which providers were skipped, failed, or produced content. - Search success: read `answer.text`, then `sources.merged`. Source cards are short and use `snippet`, not `description` or `content`. Full source/provider raw is in `sources.raw_path`; read it in chunks only when needed. - Search: inspect `diagnostics.grok_endpoint`, `diagnostics.degraded`, `diagnostics.cost_usd`, provider attempts, and `sources.grok[].source_type` (`citation` vs `searched`) before treating sources as evidence. - Fetch success: read `content.text`. If `content.truncated` is true and the preview is enough, stop. If more is needed, read `content.full_path` in chunks or rerun once with a deliberate larger `--max-chars`. - Map success: read `urls`, choose the best candidates, then fetch only the few URLs you need. Search and fetch are intentionally separated. Use search to discover and compare sources, then fetch a specific URL for deep reading. In one research turn, fetch 1-2 URLs by default; do not batch-fetch many pages unless the user explicitly asks. ## Providers And Limits `fetch.js` provider order for `--provider auto`: Tavily Extract → Firecrawl Scrape → Direct Fetch. `map.js` provider order for `--provider auto`: Tavily Map → Direct Map. For search, Tavily requires a key while Firecrawl uses its keyless tier by default. For fetch, missing Tavily means Firecrawl Keyless runs before Direct Fetch. The direct providers do not execute JavaScript, log in, use cookies, parse PDFs, or bypass anti-bot. Direct Map only reads `/sitemap.xml` and same-domain homepage links, ignores `--instructions`, and is limited to `--max-depth 1`. ## Proxy The scripts automatically use terminal proxy environment variables via undici when present: `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` and lowercase variants. `NO_PROXY` is honored, and loopback hosts are bypassed. Use `GROK_PROXY="http://127.0.0.1:7890"` to set a proxy just for this tool, or `GROK_PROXY=off` to force direct connections. If proxy debugging is needed, set `GROK_DEBUG=true`. If `search.js` returns `GROK_API_URL 未配置` or `GROK_API_KEY 未配置`, the project itself is missing required setup — point the user at `README.md` instead of trying to work around it. ## When To Plan First For multi-part research, conflicting sources, or anything that needs both site discovery and page content, read `references/planning.md` before running commands. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Autsunset](https://github.com/Autsunset) - **Source:** [Autsunset/grok-search](https://github.com/Autsunset/grok-search) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-autsunset-grok-search-grok-search - Seller: https://agentstack.voostack.com/s/autsunset - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.