x-research

适用于 Claude Code 和 OpenClaw 的 X/Twitter 研究代理。搜索、筛选、监控——一切尽在终端中完成。

功能简介

将 X API 封装成一个高效的命令行工具，让您的 AI 代理（或您自己）无需编写 curl 命令即可搜索推文、提取话题串、监控账号，并获取有来源依据的研究内容。

• 搜索：支持按互动量排序、时间过滤及噪音去除
• 快速模式：用于低成本、定向查询
• 关注列表：用于监控特定账号
• 缓存机制：避免重复调用 API 产生费用
• 费用透明：每次搜索都会显示具体花费

安装

Claude Code

# 在您的项目目录下
mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

OpenClaw

# 在您的工作区目录下
mkdir -p skills
cd skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

设置

1. X API Bearer Token — 从 X 开发者门户 获取
2. 设置环境变量：

   export X_BEARER_TOKEN="your-token-here"
   

   或将其保存到 ~/.config/env/global.env：

   X_BEARER_TOKEN=your-token-here
   

3. 安装 Bun（用于 CLI 工具）：https://bun.sh

使用方法

自然语言（直接与 Claude 对话）

• “人们都在讨论 Opus 4.6 吗？”
• “在 X 上搜索 OpenClaw 技能”
• “CT 今天在谈 BNKR 吗？”
• “看看 @frankdegods 最近发了什么”

CLI 命令

cd skills/x-research

# 搜索（按点赞数排序，自动过滤转发）
bun run x-search.ts search "your query" --sort likes --limit 10

# 查看个人主页——某用户的近期推文
bun run x-search.ts profile username

# 提取话题串——完整对话
bun run x-search.ts thread TWEET_ID

# 单条推文
bun run x-search.ts tweet TWEET_ID

# 关注列表
bun run x-search.ts watchlist add username "optional note"
bun run x-search.ts watchlist check

# 将研究结果保存为文件
bun run x-search.ts search "query" --save --markdown

搜索选项

--sort likes|impressions|retweets|recent   (默认：按点赞数)
--since 1h|3h|12h|1d|7d     时间过滤器（默认：过去 7 天）
--min-likes N              最低点赞数过滤
--min-impressions N        最低曝光数过滤
--pages N                  请求页数，1–5 页（默认：1 页，每页 100 条）
--limit N                  显示结果数量（默认：15 条）
--quick                    快速模式（见下文）
--from <username>          查询语句中简写 from:username
--quality                  预先过滤低互动推文（min_faves:10）
--no-replies               排除回复
--save                     保存至 ~/clawd/drafts/
--json                     输出原始 JSON 格式
--markdown                 生成 Markdown 格式的调研文档

快速模式

--quick 旨在提供快速且经济的查询方式，适合仅需大致了解某个话题的情况。

功能说明：

• 强制单页返回（最多 10 条结果），减少 API 调用量
• 自动添加 -is:retweet -is:reply 噪音过滤条件（除非您已明确使用这些操作符）
• 缓存有效期设为 1 小时，而非默认的 15 分钟
• 搜索结束后会显示费用概览

示例：

# 快速查看某个话题
bun run x-search.ts search "BNKR" --quick

# 快速查看某人动态
bun run x-search.ts search "BNKR" --from voidcider --quick

# 仅获取高质量结果
bun run x-search.ts search "AI agents" --quality --quick

为何更省钱：

• 防止多页加载（最大节省点）
• 1 小时缓存意味着重复查询免费
• 噪音过滤减少了每页 100 条中的无效结果
• 每次搜索后都会显示费用，避免意外支出

--from 简写

无需输入完整的 from: 操作符语法，即可将 from:username 添加到查询中。

# 下列命令等价：
bun run x-search.ts search "BNKR from:voidcider"
bun run x-search.ts search "BNKR" --from voidcider

# 可与其他标志一起使用
bun run x-search.ts search "AI" --from frankdegods --quick --quality

如果您的查询中已包含 from:，该标志不会重复添加。

--quality 标志

用于过滤低互动推文（要求至少 10 次点赞）。由于 X API 搜索操作符不支持 min_faves，此功能在检索后应用。

bun run x-search.ts search "crypto AI" --quality

费用说明

截至 2026 年 2 月，X API 采用预付费积分制的按需计费模式，无订阅服务，也无月度上限。您可在 开发者控制台 购买积分，并根据每次请求扣除相应金额。

各项资源的费用：

资源	费用
读取帖子	$0.005
查找用户	$0.010
发布帖子	$0.010

搜索成本： 每页搜索最多返回 100 条帖子，约 $0.50/页。

操作	预估费用
快速搜索（1 页，≤100 条）	~$0.50
标准搜索（1 页）	~$0.50
深度研究（3 页）	~$1.50
查看个人主页（用户 + 帖子）	~$0.51
检查关注列表（5 个账号）	~$2.55
缓存重复查询（任何类型）	免费

24 小时去重机制： 如果在同一 UTC 日内两次请求相同帖子，只会收取一次费用。这意味着同一天内对同一话题的重复搜索成本低于上述估算。

支出控制： 您可以在开发者控制台设置自动充值阈值和每个账单周期的支出上限。失败的请求绝不会被计费。

xAI 积分奖励： 每个账单周期在 X API 上消费超过 $200，即可获得 10–20% 的 xAI/Grok API 积分返还。详情请参阅 定价文档。

x-search 如何节省费用：

• 缓存机制（默认 15 分钟，快速模式下 1 小时）——重复查询免费
• 24 小时去重机制使同日重复搜索在 API 层面也无需额外付费
• 快速模式可防止意外的多页加载
• 每次搜索后均显示费用，让您清楚开支情况
• --from 可精准定位特定用户，而非进行广泛搜索
• 可通过编程方式监控使用情况：GET /2/usage/tweets

文件结构

x-research/
├── SKILL.md              # 代理指令（Claude 会读取此文件）
├── x-search.ts           # CLI 入口文件
├── lib/
│   ├── api.ts            # X API 封装模块
│   ├── cache.ts          # 文件级缓存管理
│   └── format.ts         # Telegram 和 Markdown 格式化工具
└── data/
    ├── watchlist.json    # 待监控的账号列表
    └── cache/            # 自动管理的缓存目录

安全

承载令牌处理： x-search 会从 X_BEARER_TOKEN 环境变量或 ~/.config/env/global.env 文件中读取您的令牌。该令牌绝不会输出到标准输出，但请注意：

• AI 编码代理（Claude Code、Codex 等）可能会在会话记录中记录工具调用——包括 HTTP 头部信息。如果您在代理会话中运行 x-search，您的承载令牌可能会出现在这些日志中。
• 建议：
  • 将 X_BEARER_TOKEN 设置为系统环境变量（而不是直接写在命令行中）
  • 检查并调整您的代理会话日志设置
  • 使用权限最小化的令牌（只读权限）
  • 如果怀疑令牌已泄露，请及时轮换令牌

限制

• 搜索范围仅限于最近 7 天内（使用 /2/tweets/search/recent 接口）。尽管在同一按使用付费计划下也提供全存档的 /2/tweets/search/all 接口，但此技能目前尚未实现该功能。
• 仅支持只读操作——不会发布推文或与他人互动。
• 需要具备 X API 访问权限，并已预付费用（注册）。
• min_likes 和 min_retweets 搜索运算符暂不可用，相关结果将在搜索后进行过滤。
• 全存档搜索（超过 7 天）同样基于按使用付费模式（使用相同积分）。详情请参阅 X API 搜索文档。目前此技能仅支持最近 7 天内的搜索；全存档搜索功能即将推出。

星标历史

许可证

MIT

x-research-skill 快速上手指南

x-research-skill 是一个专为 Claude Code 和 OpenClaw 设计的 X (Twitter) 研究代理工具。它通过命令行界面（CLI）封装了 X API，让 AI 代理或开发者能够轻松搜索推文、获取线程、监控账号并生成带来源的研究资料，无需手动编写复杂的 curl 命令。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

1. 操作系统：支持 macOS 或 Linux（Windows 用户建议使用 WSL）。

2. 运行时环境：必须安装 Bun（用于运行 CLI 工具）。

   curl -fsSL https://bun.sh/install | bash
   

3. X API 凭证：

   • 访问 X Developer Portal 注册应用并获取 Bearer Token。
   • 注意：X API 采用按量付费模式（预充值信用点），请确保账户中有可用额度。

4. 配置环境变量： 将 Token 设置为环境变量，以便工具读取。

   临时生效（当前终端会话）：

   export X_BEARER_TOKEN="your-token-here"
   

   永久生效（推荐）： 编辑 ~/.config/env/global.env 文件，添加以下内容：

   X_BEARER_TOKEN=your-token-here
   

安装步骤

根据你的开发环境选择对应的安装方式。

方案 A：为 Claude Code 安装

在项目根目录下执行以下命令，将技能克隆到 .claude/skills 目录：

mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

方案 B：为 OpenClaw 安装

在工作区根目录下执行以下命令，将技能克隆到 skills 目录：

mkdir -p skills
cd skills
git clone https://github.com/rohunvora/x-research-skill.git x-research

提示：如果国内访问 GitHub 较慢，可配置 Git 加速代理或使用国内镜像源克隆仓库。

基本使用

安装完成后，你可以通过自然语言与 AI 交互，或直接使用 CLI 命令进行操作。

1. 自然语言模式（推荐）

直接在 Claude Code 或 OpenClaw 的对话框中输入自然语言指令，AI 会自动调用工具：

• "What are people saying about Opus 4.6?"（人们在谈论 Opus 4.6 吗？）
• "Search X for OpenClaw skills"（在 X 上搜索 OpenClaw 技能）
• "Check what @frankdegods posted recently"（查看 @frankdegods 最近发了什么）

2. CLI 命令行模式

进入工具目录后，可直接运行 TypeScript 脚本执行具体任务。

基础搜索（按点赞数排序，自动过滤转发）：

cd skills/x-research
bun run x-search.ts search "your query" --sort likes --limit 10

查看特定用户的近期推文：

bun run x-search.ts profile username

获取完整对话线程：

bun run x-search.ts thread TWEET_ID

低成本快速检索（Quick Mode）： 适用于快速获取话题热度，限制页数以节省 API 费用。

bun run x-search.ts search "BNKR" --quick

保存研究报告为 Markdown 文件：

bun run x-search.ts search "query" --save --markdown

常用参数说明

• --sort: 排序方式 (likes, impressions, retweets, recent)
• --since: 时间范围 (1h, 3h, 1d, 7d)
• --from: 指定用户搜索 (例如 --from voidcider)
• --quality: 过滤低质量推文（仅保留点赞数≥10 的内容）
• --quick: 快速模式（单页结果，自动去噪，更便宜）
• --save: 将结果保存到 ~/clawd/drafts/

费用提示：每次搜索后工具会显示本次操作的 API 成本。默认缓存机制可避免对相同查询重复收费。