OpenClaw Twitter (X) Skill: Connect Your Agent to X Data

1. Get a twitterapi.io API key. Sign in at the dashboard with Google and copy the key from the first screen. Up to $1 in free credits for new accounts that pass the bot check; expires after 31 days; see /pricing. At $0.15 per 1,000 posts returned, $1 covers about 6,600 posts. You do not need an X developer account, an OAuth app or a card to read public data.

2. Have OpenClaw running. OpenClaw needs Node.js 24.16 or newer (or 26.1+). npx openclaw@latest starts onboarding in one command; the installer script and openclaw gateway install set it up as a background service. openclaw gateway status should show the Gateway listening on port 18789.

3. Store the key once, outside any config you might share. OpenClaw reads environment variables from the Gateway process, from .env in its working directory, and from ~/.openclaw/.env as a global fallback; neither file overrides a variable that is already set. Config strings can then reference the key as ${TWITTERAPI_IO_API_KEY}, and openclaw mcp doctor warns you if a header or env value holds a literal secret instead of a reference.

4. Pick a route. The MCP server is the fastest: one command and the model gets 12 tools. The skill is better when you want control: which endpoint, which operators, which fields reach the model, and how many pages a run may read. You can install both, but give any one agent only the one it needs (the injection section explains why).

Rate limits. Accounts that have never paid are limited to 0.2 requests per second; after the first payment the limit is 20 per second. At 0.2 per second a 5-page search takes at least 20 seconds, which is fine for a digest and slow for an interactive chat, so test with one page first.

OpenClaw keeps MCP server definitions under mcp.servers in ~/.openclaw/openclaw.json (a JSON5 file) and turns the tools each server lists into agent tools, subject to the same tool policies as everything else. A server needs either a url (Streamable HTTP or SSE) or a command (stdio). twitterapi.io runs a hosted Streamable HTTP server at https://mcp.twitterapi.io/mcp that authenticates with an X-API-Key header, and publishes the same server on npm as @twitterapi_io/mcp-server (version 0.2.0, MIT, reads TWITTERAPI_IO_API_KEY).

The config below is the hosted route written straight into the file. headers is the OpenClaw field for static HTTP headers, and ${TWITTERAPI_IO_API_KEY} is resolved from the Gateway environment when the config loads. If the variable is missing, OpenClaw leaves the placeholder visibly unresolved and logs a warning; when a Streamable HTTP server rejects initialization with HTTP 401, the startup log and catalog diagnostic report authentication refused (401) next to the server name.

toolFilter.include is optional. Without it the agent sees all 12 tools: search_tweets, get_user_info, get_user_about, get_user_followers, get_user_followings, get_user_last_tweets, get_user_mentions, get_tweets_by_ids, get_tweet_replies, get_tweet_quotes, get_tweet_retweeters and get_trends. Each one maps to a single read endpoint (for example search_tweets calls /twitter/tweet/advanced_search), and every tool only reads. Listing only what a job needs keeps the prompt shorter and the agent's options narrower.

We checked every server definition on this page (the JSON5 blocks, the openclaw mcp set object and the stdio variant) against the MCP server schema in OpenClaw's source (src/config/zod-schema.mcp-server.ts): all pass, and a typo such as transport: "http" in the file is rejected (the value must be streamable-http, sse or stdio). We did not start a live Gateway for this guide.

Prefer the CLI? openclaw mcp set takes one JSON object, openclaw mcp add builds a definition from flags, and openclaw mcp doctor <name> --probe opens a live connection and lists the tools. One detail that trips people up: in current releases the CLI commands that change saved servers or probe them (add, set, configure, probe, doctor --probe) refuse to run while a local Gateway owns the state directory. Run openclaw gateway stop, then the command, then openclaw gateway start, or use Settings → MCP in the Control UI, which writes the same entry through the running Gateway.

The script below does the whole route in four steps, with the Gateway stopped while the CLI edits the saved servers. Pick 2a (hosted, nothing to install) or 2b (stdio, OpenClaw spawns npx -y @twitterapi_io/mcp-server@0.2.0 as a child process). Pinning the version in 2b means an npm release never changes your agent's tools without you noticing.

For stdio servers OpenClaw filters the child's environment before it starts: it drops interpreter and loader hooks such as NODE_OPTIONS and LD_*, and keeps ordinary credential variables, including custom *_API_KEY names, so TWITTERAPI_IO_API_KEY passes through.

When the probe succeeds, ask a question that needs fresh data. The model chooses search_tweets, writes an X search query with query and queryType (Latest or Top), and reasons over the JSON it gets back. Say what you want filtered ("English, no replies") so it adds the operators. Each call to search_tweets returns one page of up to 20 posts and a next_cursor; at $0.15 per 1,000 posts returned, that page costs at most $0.003.

One trade-off of Route A: the MCP tools return the full post objects, which is where most of your model's tokens go (next sections measure it). If you run large digests, Route B's trimmed output is the cheaper context.

An OpenClaw skill is a folder with a SKILL.md: YAML frontmatter (name, description, optional metadata) and plain instructions. OpenClaw lists eligible skills in the system prompt as a compact XML block (roughly 24 tokens per skill plus the name, description and location), and the model reads the full file when the skill fits the task. Skills in <workspace>/skills (by default ~/.openclaw/workspace/skills) have the highest precedence; ~/.openclaw/skills is shared by every local agent. Changes are picked up by a background watcher in about a minute, or immediately on Gateway restart.

The metadata.openclaw block gates the skill: requires.bins keeps it hidden until curl and jq are on PATH, and requires.env until TWITTERAPI_IO_API_KEY is set. primaryEnv names that variable, so you can also supply the key per skill in openclaw.json as skills.entries.x-topic-digest.apiKey (a string or a SecretRef such as { source: "env", provider: "default", id: "TWITTERAPI_IO_API_KEY" }). OpenClaw injects it for the agent run only and restores the environment afterwards. Injection reaches the host process, not a sandbox: if your agent runs sandboxed, pass the key into the sandbox separately and make sure curl and jq exist inside the container.

The helper does three things a model would otherwise do badly. It adds lang:en -filter:replies to every query unless you ask for raw mode, which our study found turns a half-usable result into a nearly clean one. It trims each post to 7 fields (url, author, createdAt, likes, reposts, replies, text), printed as one JSON line per post. And it stops after one page of up to 20 posts, printing next_cursor so the agent has to ask for more on purpose. {baseDir} in the instructions is replaced with the skill's own folder, so the path works wherever the skill is installed.

We tested the helper offline against recorded /twitter/tweet/advanced_search responses from our study: one full page comes out as 20 post lines plus a cursor line, the 7-field output for that page was 6,558 tokens against 49,093 for the raw page, and an error body such as {"status":"error","msg":"..."} becomes {"error": "..."} instead of an empty result. The first version of our jq filter emitted a cursor line after every post because , binds tighter than | in jq; the parentheses in the final filter are there for that reason.

Below the install script is the helper's output format, produced by running its jq filter on a recorded @openclaw post from our sample (date trimmed).

Search results for "openclaw twitter" mix three different things, so it helps to separate them. OpenClaw's X channel plugin (documented at docs.openclaw.ai/channels/x) makes your agent a bot account that answers mentions. It reads mentions and thread context through the official X API with an OAuth2 app you create, replies only to allowlisted authors by default, and does not support DMs, original posts, likes, follows or media uploads. It estimates spend at X's pay-per-use rates and caps it with costLimits (defaults: $100 a day, $1,000 a cycle). Third-party skills on ClawHub and posting services such as OpenTweet (opentweet.io) cover scheduling and posting. The two routes on this page are about reading X data on demand or on a schedule.

Reading a 50-post thread, the X channel's default threadContext.maxPosts, costs $0.25 at X's $0.005 per post read and $0.0075 at $0.15 per 1,000 posts returned. Use the channel if you want a public reply bot and accept X's pricing; use Route A or B when the agent's job is to know what is being said.

A monitoring skill is only as good as what the search hands the model. To measure that, we ran 8 searches an OpenClaw user might watch (openclaw, clawhub, "mcp server", "ai agent", "claude code", "prompt injection", "local llm", "agent skills") three ways each: plain Latest (5 pages, what a naive skill or a bare search_tweets call returns), Latest with lang:en -filter:replies (3 pages, what the skill above sends) and plain Top (3 pages, X's own ranking). That is 88 requests and 1,740 posts, collected in 2026. A post counts as usable for a digest when it is English, not a reply, not a duplicate of an earlier post in the same result, and has at least 8 words of its own after links, mentions and hashtags are removed.

Plain Latest is half noise. Only 49% of plain Latest results were usable. Replies were the biggest loss at 37% of all posts; 20% were not English. For a tool-name query like openclaw it was worse: 31% usable, with 58% replies. Reposts were not a factor: 0 of the 1,740 search results were reposts.

Two operators fix most of it. With lang:en -filter:replies the usable share rose to 98% (470 of 480 posts), with every query at 95% or higher. Both operators are honored server-side: the filtered results contained 0 replies and 0 non-English posts. That is why the skill adds them by default and why, on Route A, you should ask the agent for English original posts explicitly.

Top is a different feed, not a cleaner Latest. Top was 82% usable, with no replies, but its median post had 362 likes against 0 in Latest, and only 1.8% of Top posts (median across queries) also appeared in the newest 100. The median Top post was 11.9 days older than the newest post for its query (median across queries; 2.9 days for "claude code", 56.2 for openclaw). Top tells the agent what was popular over days or weeks; Latest tells it what is new. A digest that wants both should run both.

Combining topics barely duplicates. Across the 8 filtered searches, 10 of 480 posts (2.1%) appeared under more than one query, so a multi-topic digest can merge results by post URL without losing much.

The table shows each query. "Filtered" is Latest with lang:en -filter:replies; the last two columns come from the time span of the newest results (next section).

Every post the API returns is a full object: text, author profile, entities, media, quoted post, card and counts. That is what an MCP tool or a bare curl call hands the model. We counted it with the o200k_base tokenizer on compact JSON: a post averaged 1,563 tokens (median 1,260, 90th percentile 2,802). The 7-field record our skill prints averaged 219 tokens (median 140, 90th percentile 426), 86% fewer, or 7.1x.

In practice: 100 raw posts are about 156,265 tokens, which is more than a 128k context window holds (only 81 raw posts fit). Trimmed, the same 100 posts are about 21,864 tokens and 585 fit. For one organization account the gap was larger still: the 60 recent posts of @openclaw averaged 2,246 tokens raw and 120 trimmed.

Count both sides of the bill. An hourly digest reading one page per run reads up to 480 posts a day: $0.072 of X data, and about 750,071 input tokens a day if the model reads raw JSON against 104,947 trimmed. Multiply that by your model's input price to see which side of the bill to optimize first.

Keep the fields the digest needs, and add others deliberately: viewCount for reach, quoted_tweet.text if quotes matter, entities.urls[].expanded_url if the agent should know where links point. Each one costs tokens on every post.

How often a monitor should run depends on how fast its topic moves. We estimated each query's rate from the time span of its newest results. The spread is enormous: "ai agent" produced about 197.1 filtered posts an hour and "claude code" about 119.7, while openclaw ran at about 13.7 and clawhub at about 0.1 (its newest 100 posts spanned about 75 days). The median filtered rate across the 8 queries was 11.1 posts an hour.

Three schedules cover most needs. Once a day, 100 posts per topic (5 pages) suits slow topics and costs $0.015 per topic per day, or $3.60 a month for 8 topics. Hourly, one page reads up to 480 posts a day per topic for at most $0.072 ($2.16 a month), and covers every new post for topics under 20 posts an hour. Every post on a fast topic means paging until you reach the last post you saw: for "ai agent" that was about 4,730 filtered posts and $0.71 a day. The same reads at the official X API's $0.005 per post would be about 33x more.

For fast topics, narrow the query before you buy coverage: add min_faves:10, an exact phrase or from: a list of accounts. A digest of what people engaged with is often more useful than every post.

OpenClaw's scheduler runs the skill for you. openclaw automations create (alias openclaw cron) takes a cron expression and a prompt, runs it in an isolated session, and can announce the result to a channel or post it to a webhook:

twitterapi.io also has write endpoints. They run through an authenticated session: one /twitter/user_login_v2 call ($0.10, through a proxy you supply) returns login_cookies, and each post, delete, like, retweet, follow or unfollow is then $0.002 per call. On the official X API pay-per-use plan a post created costs $0.015, or $0.20 if it contains a URL, so a plain post is 7.5x cheaper ($0.015 / $0.002) and a post with a link 100x ($0.20 / $0.002).

Posting is where an agent can do real damage, so the skill below is built to need you. disable-model-invocation: true keeps it out of the model's prompt: the agent cannot decide to post on its own, and the skill runs only when you type /x-post <text>. The instructions make it show the text and wait for a yes, the script refuses anything over 280 characters, builds the JSON body with jq --arg so quotes in the text cannot break it, and returns only status, tweet_id and message.

The caveats are not optional. The call acts as that X account, so X can rate-limit, lock or suspend it. Keep a human pace (a few posts a day, not a loop), expect the session to need a fresh login now and then, and note that each HTTP 200 call is billed. Follow X's automation rules (help.x.com/en/rules-and-policies/x-automation): no bulk or duplicate posting, no automated replies or mentions to people who did not ask, and no DMs from this setup. Never let the agent that reads X content also hold this skill.

Anyone can post on X, and a search result puts their text into your agent's context. A post that says "ignore previous instructions and ..." is indirect prompt injection, the first entry in the OWASP Top 10 for LLM applications. OpenClaw raises the stakes because its agents often hold the exec tool and live on your machine. In our 1,740 posts, exactly 1 contained a literal "if you are an AI, ignore previous instructions" payload, and it surfaced in a plain Latest search for "prompt injection". Rare, but a monitor runs every day.

1. Least privilege per agent. Give the agent that reads X only read capabilities. In openclaw.json, agents.entries.<id>.skills is the final list of skills that agent sees, and toolFilter.include limits which MCP tools a server exposes. The docs are explicit that skill allowlists are not a shell boundary, so constrain exec with sandboxing or exec allowlists too.

2. Say it in the skill. The x-topic-digest instructions tell the model that post text is data, never instructions, and not to open links unless you ask. This lowers the risk; it does not remove it.

3. Keep reads and writes apart. The posting skill is user-invoked only and lives on a different agent. A post cannot talk an agent into using a tool it does not have.

4. Less text in, less risk in. One page per call and 7 fields per post means less attacker-controlled text per turn. 43% of plain Latest posts and 69% of Top posts carried a link, which is why the skill tells the agent not to follow them.

OpenClaw's own docs add one more: treat third-party skills as untrusted code and read them before enabling. That includes ours; the full skill is on this page so you can.

The skill does not show up. Run openclaw skills check. A skill can be present but not ready: requires.bins wants curl and jq on the Gateway's PATH, and requires.env wants TWITTERAPI_IO_API_KEY visible to the Gateway, not just your shell. Existing sessions keep their skill snapshot; start a new one with /new.

openclaw mcp add or --probe refuses to run. The CLI needs exclusive state ownership for saved-server changes and probes. Run openclaw gateway stop first and openclaw gateway start afterwards, or add the server in Settings → MCP.

authentication refused (401). The server rejected the key: either the ${...} reference did not resolve or the key itself is wrong. Check that the variable name is uppercase and matches the .env line exactly, that the Gateway was restarted after you edited .env, and that the key works in the dashboard.

The search returns an error line. The helper prints the API's msg. An invalid key, no credits left and malformed queries all show up here; "mcp server" needs the inner double quotes, which is why the skill tells the agent to single-quote the whole query.

Results look thin or off-topic. Short tool names collide with other meanings, and plain Latest is about half replies. Add lang:en -filter:replies, an exact phrase, or from: accounts. Try Top for the most-engaged posts.

Slow searches. Before the first payment the limit is 0.2 requests per second, so multi-page calls queue. After the first payment it is 20 per second.

An agent tried to post on its own. It should not be able to. Check that the posting skill has disable-model-invocation: true and is not in that agent's skill list.

Question. When an OpenClaw agent runs a 'monitor a topic' skill on X, how much of what it gets is usable for a digest, how do Latest, filtered Latest and Top differ, how many tokens does each post cost the model raw versus trimmed, how fast do agent topics move, what does a daily digest cost, and how often do posts carry instructions aimed at an AI?

Queries. 8 searches written down before collection: openclaw, clawhub, "mcp server", "ai agent", "claude code", "prompt injection", "local llm", "agent skills". Each ran as plain Latest (5 pages), Latest with lang:en -filter:replies (3 pages) and plain Top (3 pages). Plus the @openclaw organization timeline (3 pages of /twitter/user/last_tweets, 60 posts over about 48 days).

Method. /twitter/tweet/advanced_search through a rate-limited, read-only client: 88 search requests and 1,740 posts, plus 3 timeline requests. Collected in 2026. Rates per hour are posts divided by the hours between the newest and oldest post in a result.

Labels. Reply: X's reply flag. Not English: the post's lang is not en. Duplicate: the same text, after lowercasing and removing links, mentions and spacing, as an earlier post in the same result. Short: fewer than 8 words after removing links, mentions and hashtags. Usable: none of those. Tokens: tiktoken o200k_base on compact JSON of the full post object versus the 7-field record. Instruction-like: text matching phrases such as 'ignore previous instructions' or 'if you are an AI'; a first draft that also matched 'system prompt' was dropped because those hits were posts discussing prompts. Cost: $0.15 per 1,000 posts returned, with a minimum of 15 credits per request (the minimum applies to an empty or one-post result).

What this sample cannot show. It is one snapshot in 2026; Latest changes by the minute and launch days look different. The topics are AI and developer tools; other topics have other reply and language mixes. 'Usable' is a mechanical label, not a judgment of accuracy or relevance. Rates from 100 posts are rough, especially for slow topics. Token counts depend on the tokenizer your model uses. We did not run a live OpenClaw agent against these searches; the skill's helper was tested on recorded responses.

Privacy. Aggregates only. No private individual is named, quoted or profiled, and the only post shown is from an organization account. Raw pages from topic searches were not kept in the repository; the study keeps de-identified rows (no IDs, URLs, text or handles) plus the gzip-compressed @openclaw timeline. Protocol, analysis script and results: data/studies/openclaw-twitter/ (protocol.json, analyze.py, results.json).