independent-openrouter-x-search

OpenClaw tool plugin that exposes openrouter_x_search, an independent OpenRouter Grok X Search tool.

This tool is primarily for searching X (Twitter) content: posts, accounts, threads, recent discourse, and social signals. It consumes OpenRouter credits. It can work independently of OpenClaw's built-in web_search and is useful when X/Twitter-native results are needed.

Install

openclaw plugins install npm:@jwongart/independent-openrouter-x-search@0.0.2

Configuration

Request timeout is configured at plugin level:

{
  "plugins": {
    "entries": {
      "independent-openrouter-x-search": {
        "config": {
          "timeout_ms": 120000
        }
      }
    }
  }
}

• timeout_ms: request timeout in milliseconds, from 15000 to 300000. Default is 120000.

Tool

• openrouter_x_search: calls OpenRouter Chat Completions with model=x-ai/grok-4.3, OpenRouter native web plugin, and x_search_filter hints so Grok uses xAI X Search for X/Twitter content.

Inputs

• query (required): the X/Twitter search request. It can be a natural-language question, keyword query, handle-focused query, X URL, or post/status ID.
• allowed_x_handles: optional list of X handles to include, without @.
• excluded_x_handles: optional list of X handles to exclude, without @.
• from_date, to_date: optional date filters in YYYY-MM-DD format. OpenRouter/xAI X Search appears to treat to_date as an exclusive boundary; for a single-day search, set to_date to the next calendar day or omit it.
• enable_image_understanding, enable_video_understanding: optional booleans for media understanding in X posts.
• max_results: OpenRouter native web plugin result cap. Default is 5.
• max_tokens: maximum output tokens. Default is decided by OpenRouter/model if omitted.
• temperature, top_p: OpenRouter request parameters.
• include_reasoning, reasoning, response_format: OpenRouter request parameters for reasoning and structured output behavior.

The plugin fixes model to x-ai/grok-4.3 and adds a system instruction telling the model to search X/Twitter only and avoid ordinary webpages. OpenRouter currently exposes X Search through the xAI model's native search path, so the plugin cannot hard-disable every upstream web-search capability, but it strongly constrains the call toward X Search and returns the actual raw response in details.

Output

The tool returns natural-language content for OpenClaw plus structured details:

• content: the Grok answer, a compact Resources list, any observed search tool calls, model, usage/cost summary such as Usage: 19,874 prompt + 1,240 completion = 21,114 tokens and Estimated cost: $0.0374593, plus Billing: This tool consumes OpenRouter credits.
• details.openrouterRequest: the exact JSON body sent to OpenRouter.
• details.openrouterResponse: the raw OpenRouter Chat Completions response.
• details.retryCount: retry count for transient 429/5xx/network failures.

API Key

The plugin reads the OpenRouter API key in this order:

1. OPENROUTER_API_KEY from the Gateway process environment.
2. env.OPENROUTER_API_KEY from ~/.openclaw/openclaw.json.
3. models.providers.openrouter.apiKey from ~/.openclaw/openclaw.json.

The API key is never returned in tool output.

Build

npm install
npm run plugin:build
npm run plugin:validate
npm test

License

MIT