Clawbird — X/Twitter Tools

You have access to 13 tools for interacting with X (Twitter) via the official X API v2. All tools return JSON with results and estimated API cost.

Authentication & Credentials

This plugin authenticates to the X API using OAuth 1.0a User Context for write operations (posting, liking, following, DMs) and optionally a Bearer Token for read-only operations (search, user lookup).

Where credentials come from: You must generate them at the X Developer Portal:

1. Create a Project and App at developer.x.com
Generate OAuth 1.0a keys: API Key, API Secret, Access Token, Access Token Secret
Optionally generate a Bearer Token for read-only operations

How credentials are provided: Credentials are passed to the plugin at runtime by the OpenClaw plugin config system (pluginConfig). The plugin never reads config files directly. Fallback: environment variables X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_SECRET, X_BEARER_TOKEN.

No credentials are hardcoded or bundled. The plugin will return a clear error if credentials are missing.

External Endpoints

All network requests go exclusively to the official X API v2. No other hosts are contacted.

Endpoint	Method	Tool(s)	Data Sent
INLINECODE6	POST	xposttweet, xpostthread, xreplytweet	Tweet text, reply metadata
INLINECODE7

Security & Privacy

- Network access: Only api.x.com (official X API). No other domains are contacted.
Local file access: Writes a session-scoped clawbird-interactions.jsonl file to the working directory, logging mutation actions (posts, likes, follows, DMs) so the agent can avoid duplicating work. No other files are read or written beyond the declared environment variables.
Credential handling: OAuth tokens are read from plugin config or env vars at runtime and passed to the X API via signed HTTP headers. They are never logged, cached to disk, or transmitted to any third party.
Data sent to X: Only the data you explicitly provide in tool parameters (tweet text, search queries, usernames, message text). No additional user data is collected or sent.
Data received from X: Tweet content, user profiles, DM messages, and engagement metrics as returned by the X API. This data is returned to the agent as JSON and not stored.

Trust Statement

Clawbird is an npm-distributed skill — the runtime code is installed via npm i -g @xonder/clawbird and is not bundled in the ClawHub skill archive. The security properties below can be verified by auditing the source:

- Source: https://github.com/xonder/clawbird (MIT)
npm: https://www.npmjs.com/package/@xonder/clawbird
Makes no network requests other than to api.x.com (source: src/client.ts)
Reads and writes one local file (clawbird-interactions.jsonl) for session interaction logging — no other filesystem access (source: src/interaction-log.ts)
Has zero transitive dependencies beyond the official @xdevplatform/xdk SDK and INLINECODE25
Includes a comprehensive test suite (200+ tests) verifiable via INLINECODE26

Since this skill installs code from npm at runtime, review the source or pin a specific version (npm i -g @xonder/clawbird@1.1.0) before granting credentials.

Write Actions & Autonomous Use

The following tools modify remote state on your X account:

Tool	Action	Reversible?
xposttweet	Posts a tweet	Delete manually
xpostthread

Recommendation: If running autonomously, consider requiring explicit user confirmation before write actions by configuring agent-level tool policies. Read-only tools (xgettweet, xsearchtweets, xgetuserprofile, xgetmentions, xgetdms, xgetcostsummary) are safe for autonomous use.

Available Tools

Posting

x_post_tweet — Post a single tweet.

- text (required): Tweet content (max 280 chars)
Returns: INLINECODE30

x_post_thread — Post a multi-tweet thread.

- tweets (required): Array of tweet texts (posted in order, each as a reply to the previous)
Returns: INLINECODE33

x_reply_tweet — Reply to an existing tweet.

- tweetId (required): Tweet ID or full URL (e.g. https://x.com/user/status/123456)
INLINECODE37 (required): Reply content (max 280 chars)
Returns: INLINECODE38

Engagement

x_like_tweet — Like a tweet.

- tweetId (required): Tweet ID or full URL
Returns: INLINECODE41

Social

x_follow_user — Follow a user.

- username (required): Username to follow (with or without @)
Returns: INLINECODE45

Research

x_get_tweet — Get a single tweet by ID or URL.

- tweetId (required): Tweet ID or full URL (e.g. https://x.com/user/status/123456)
Returns: INLINECODE49

x_search_tweets — Search recent tweets (last 7 days).

- query (required): Search query — supports X operators like from:user, #hashtag, "exact phrase", -exclude, INLINECODE56
INLINECODE57 (optional): 10–100, default 10
Returns: INLINECODE58

x_get_user_profile — Get a user's profile.

- username (required): Username with or without INLINECODE61
Returns: INLINECODE62

x_get_mentions — Get recent mentions of the authenticated account.

- maxResults (optional): 5–100, default 10
Returns: INLINECODE65

Direct Messages

x_send_dm — Send a direct message to a user.

- username (required): Recipient's username (with or without @)
INLINECODE69 (required): Message content
Returns: INLINECODE70

x_get_dms — Get recent direct messages.

- username (optional): Filter DMs to a specific user's conversation
INLINECODE73 (optional): 1–100, default 10
Returns: INLINECODE74

Utility

x_get_interaction_log — Get the log of all write actions performed this session (posts, replies, likes, follows, DMs). Useful to review what has already been done and avoid duplicating actions.

- limit (optional): Maximum number of recent entries to return (default: all)
Returns: INLINECODE77

x_get_cost_summary — Get cumulative API cost for this session.

- No parameters required
Returns: INLINECODE79

Best Practices

Search Queries

- Use from:username to search a specific user's tweets
Use #hashtag for hashtag search
Use "exact phrase" for exact matches
Combine operators: INLINECODE83
Use -is:retweet to filter out retweets

Thread Formatting

- Keep each tweet under 280 characters
Start with a strong hook in tweet 1
Number tweets (1/N) for long threads
End with a call to action or summary

Cost Awareness

Every tool response includes an estimatedCost field. Approximate costs:

- Post/Reply: ~$0.01 per tweet
Like: ~$0.005
Search: ~$0.005 per result
User lookup: ~$0.001
Mentions: ~$0.005 per result
Send DM: ~$0.01
Read DMs: ~$0.005 per result
Get tweet: ~$0.005

Use x_get_cost_summary to check cumulative session spend before expensive operations.

Rate Limits

- Posting: 200 tweets per 15 minutes
Search: 180 requests per 15 minutes (user), 450 (app)
Likes: 50 per 15 minutes
User lookup: 900 per 15 minutes
Mentions: 180 per 15 minutes
DMs: 200 messages per 15 minutes, 1000 per 24 hours
Following: 400 per 24 hours

Error Handling

All tools return errors as { error: "message", details?: ... }. Common issues:

- Rate limiting (wait and retry)
Authentication errors (check API credentials)
Tweet not found (verify ID/URL)
Empty text (provide non-empty content)

Clawbird — X/Twitter 工具

您可以通过官方 X API v2 访问 13 个与 X（Twitter）交互的工具。所有工具均返回包含结果和预估 API 成本的 JSON 数据。

认证与凭证

本插件使用 OAuth 1.0a 用户上下文 进行写操作（发帖、点赞、关注、私信），并可选择使用 Bearer Token 进行只读操作（搜索、用户查询）。

凭证来源： 您必须在 X 开发者平台生成凭证：

1. 在 developer.x.com 创建项目和应用
生成 OAuth 1.0a 密钥：API Key、API Secret、Access Token、Access Token Secret
可选：生成用于只读操作的 Bearer Token

凭证提供方式： 凭证在运行时通过 OpenClaw 插件配置系统（pluginConfig）传递给插件。插件从不直接读取配置文件。备用方案：环境变量 XAPIKEY、XAPISECRET、XACCESSTOKEN、XACCESSSECRET、XBEARERTOKEN。

凭证不会硬编码或捆绑。 如果缺少凭证，插件将返回明确的错误信息。

外部端点

所有网络请求仅发送至官方 X API v2。不联系任何其他主机。

端点	方法	工具	发送数据
https://api.x.com/2/tweets	POST	xposttweet、xpostthread、xreplytweet	推文文本、回复元数据
https://api.x.com/2/tweets/:id

安全与隐私

- 网络访问： 仅 api.x.com（官方 X API）。不联系任何其他域名。
本地文件访问： 在工作目录中写入一个会话范围的 clawbird-interactions.jsonl 文件，记录变更操作（发帖、点赞、关注、私信），以便代理避免重复工作。除声明的环境变量外，不读取或写入任何其他文件。
凭证处理： OAuth 令牌在运行时从插件配置或环境变量中读取，并通过签名的 HTTP 头传递给 X API。它们永远不会被记录、缓存到磁盘或传输给任何第三方。
发送至 X 的数据： 仅限您在工具参数中明确提供的数据（推文文本、搜索查询、用户名、消息文本）。不会收集或发送任何额外的用户数据。
从 X 接收的数据： 推文内容、用户资料、私信消息以及 X API 返回的互动指标。这些数据以 JSON 格式返回给代理，不会存储。

信任声明

Clawbird 是一个通过 npm 分发的技能——运行时代码通过 npm i -g @xonder/clawbird 安装，不捆绑在 ClawHub 技能存档中。以下安全属性可通过审计源代码进行验证：

- 源代码： https://github.com/xonder/clawbird（MIT 许可证）
npm： https://www.npmjs.com/package/@xonder/clawbird
除 api.x.com 外不发起任何网络请求（来源：src/client.ts）
读取和写入一个本地文件（clawbird-interactions.jsonl）用于会话交互日志记录——无其他文件系统访问（来源：src/interaction-log.ts）
除官方 @xdevplatform/xdk SDK 和 @sinclair/typebox 外无任何传递依赖
包含全面的测试套件（200+ 测试），可通过 npm test 验证

由于此技能在运行时从 npm 安装代码，请在授予凭证前审查源代码或锁定特定版本（npm i -g @xonder/clawbird@1.1.0）。

写操作与自主使用

以下工具会修改您 X 账户的远程状态：

工具	操作	可逆？
xposttweet	发布推文	手动删除
xpostthread

建议： 如果自主运行，建议通过配置代理级工具策略，在写操作前要求用户明确确认。只读工具（xgettweet、xsearchtweets、xgetuserprofile、xgetmentions、xgetdms、xgetcostsummary）可安全用于自主使用。

可用工具

发布

xposttweet — 发布单条推文。

- text（必填）：推文内容（最多 280 字符）
返回：{ id, text, url, estimatedCost }

xpostthread — 发布多条推文组成的帖子。

- tweets（必填）：推文文本数组（按顺序发布，每条回复上一条）
返回：{ threadId, tweetCount, tweets: [{ id, text, url }], estimatedCost }

xreplytweet — 回复现有推文。

- tweetId（必填）：推文 ID 或完整 URL（例如 https://x.com/user/status/123456）
text（必填）：回复内容（最多 280 字符）
返回：{ id, text, url, inReplyTo, estimatedCost }

互动

xliketweet — 点赞推文。

- tweetId（必填）：推文 ID 或完整 URL
返回：{ liked, tweetId, estimatedCost }

社交

xfollowuser — 关注用户。

- username（必填）：要关注的用户名（带或不带 @）
返回：{ following, user: { id, username }, estimatedCost }

研究

xgettweet — 通过 ID 或 URL 获取单条推文。

- tweetId（必填）：推文 ID 或完整 URL（例如 https://x.com/user/status/123456）
返回：{ id, text, authorId, createdAt, metrics, conversationId, lang, url, author: { id, name, username, verified, profileImageUrl }, estimatedCost }

xsearchtweets — 搜索近期推文（最近 7 天）。

- query（必填）：搜索查询——支持 X 运算符，如 from:user、#hashtag、exact phrase、-exclude、lang:en
maxResults（可选）：10–100，默认 10
返回：{ query, resultCount, tweets: [{ id, text, authorId, createdAt, metrics, url }], estimatedCost }

xgetuser_profile — 获取用户资料。

- username（必填）：用户名，带或不带 @
返回：{ id, name, username, description, followersCount, followingCount, tweetCount, verified, profileImageUrl, url, createdAt, location,