search-x

搜索 X

由 xAI 的 Responses API 和 x_search 工具驱动的实时 X/Twitter 搜索。返回真实推文，并附带引用、互动信息、图片和直接链接。不抓取数据、不使用 Cookie、不进行浏览器自动化——只使用 xAI API。

设置

设置你的 xAI API 密钥：

openclaw config set skills.entries.search-x.apiKey "xai-YOUR-KEY"

或使用环境变量：

export XAI_API_KEY="xai-YOUR-KEY"

在此获取 API 密钥：https://console.x.ai

---

使用 x_search 的 Responses API（推荐）

此技能搜索 X 的主要方式是通过带有 x_search 工具的 Responses API（POST /v1/responses）。这是推荐的方式，因为 xAI 会在服务端处理所有搜索编排。

工作原理

POST https://api.x.ai/v1/responses
Authorization: Bearer $XAI_API_KEY
Content-Type: application/json

{
  "model": "grok-4-1-fast-non-reasoning",
  "tools": [{"type": "x_search"}],
  "input": "Find recent tweets about Claude Code tips"
}

与手动使用 chat/completions + 搜索相比，主要优势包括：

• 服务端编排 - Grok 决定何时以及如何搜索 X，无需客户端工具循环
• 自动添加引用 - 每条结果都包含指向真实推文的来源 URL
• 组合使用工具 - 你可以在同一个请求中传入 x_search、web_search 和 code_interpreter，Grok 会使用合适的工具
• 结构化结果 - 引用以包含 URL 的结构化对象返回，而非内嵌在文本中

在一个请求中组合工具

{
  "model": "grok-4-1-fast-non-reasoning",
  "tools": [
    {"type": "x_search"},
    {"type": "web_search"}
  ],
  "input": "What are people saying about the new React compiler on X, and what does the official documentation say?"
}

Grok 会搜索 X 上的社交讨论，并搜索网络上的官方文档，然后综合两者，生成一条附带各来源引用的回复。

---

模型

模型	上下文	价格（每 1M 个令牌，输入/输出）	最适合用于
grok-4.20-multi-agent-beta-0309	2M	$2 / $6	复杂的多步骤研究
grok-4.20-beta-0309-reasoning	2M	$2 / $6	深度推理分析
grok-4-1-fast-reasoning	2M	$0.20 / $0.50	快速推理搜索
grok-4-1-fast-non-reasoning	2M	$0.20 / $0.50	快速搜索（最便宜）

Grok 4.20 多 Agent Beta

grok-4.20-multi-agent-beta-0309 模型使用多 Agent 协作处理复杂的研究查询。多个 Grok Agent 会协同拆解查询、从不同角度搜索并综合结果。适用于以下情况：

• 查询需要交叉参照多个主题或账号
• 你需要全面研究，而非快速查找
• 用户要求根据大量数据点进行分析、比较或趋势综合
• 相比全面性，时间和成本不那么重要

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "comprehensive analysis of AI safety discourse evolution"

模型选择指南

• 默认（快速搜索）： grok-4-1-fast-non-reasoning - 最便宜、最快，适合简单的推文查找
• 需要推理： grok-4-1-fast-reasoning - 价格相同，增加思维链以提升分析能力
• 图片搜索： grok-4.20-beta-0309-reasoning - 除推文外还会返回图片结果
• 深度研究： grok-4.20-multi-agent-beta-0309 - 使用多 Agent 处理复杂查询

---

通过 x_search 使用搜索模式

x_search 工具支持四种不同的搜索模式。Grok 会根据查询自动选择合适的模式，但你可以通过提示词引导它。

关键词搜索

精确匹配词语。最适合查找包含特定短语、话题标签或词语的推文。

node {baseDir}/scripts/search.js "Claude Code monorepo tips"

Grok 会搜索包含精确词语的推文。在查询中使用引号可以精确匹配短语。

语义搜索

基于含义的搜索。最适合查找关于某个概念的推文，即使这些推文没有使用完全相同的词语。

node {baseDir}/scripts/search.js "people frustrated with slow CI/CD pipelines"

Grok 会理解意图，并找到相关推文，即使其中使用了不同的表述（例如“构建时间太折磨人了”“GitHub Actions 要等很久”）。

用户搜索

查找账号及其动态。最适合查询个人资料和发现账号。

node {baseDir}/scripts/search.js --handles karpathy --days 30 "posts from @karpathy about transformers"

返回账号信息、近期帖子和互动模式。结合主题筛选条件，可以查看某人对特定主题的看法。

线程抓取

获取完整对话线程。最适合阅读完整的回复链和讨论。

node {baseDir}/scripts/search.js --handles sama --days 7 "thread about AI regulation"

Grok 会重建完整线程，包括回复、引用推文和完整的对话上下文。

---

命令

基本搜索

node {baseDir}/scripts/search.js "AI video editing"

搜索 X 上的查询，并返回包含用户名、内容、日期和直接链接的推文。

按时间筛选

node {baseDir}/scripts/search.js --days 7 "breaking news"
node {baseDir}/scripts/search.js --days 1 "trending today"
node {baseDir}/scripts/search.js --days 90 "product launch retrospective"

--days 标志用于设置搜索的回溯时间。默认值为 30 天。使用 --days 1 搜索“今天发生了什么”，使用 --days 7 获取每周汇总，使用 --days 90 进行更长期的研究。

按账号筛选

node {baseDir}/scripts/search.js --handles @elonmusk,@OpenAI "AI announcements"
node {baseDir}/scripts/search.js --exclude @bots "real discussions"

使用 --handles 将结果限制为特定账号。使用 --exclude 过滤无关内容。两者都接受逗号分隔的列表，账号名前可以带 @ 前缀，也可以不带。

输出选项

node {baseDir}/scripts/search.js --json "topic"        # Full JSON response with all metadata
node {baseDir}/scripts/search.js --compact "topic"     # Just tweets, no commentary or citations list
node {baseDir}/scripts/search.js --links-only "topic"  # Just X links, one per line

模型选择

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "complex research query"
node {baseDir}/scripts/search.js --model grok-4-1-fast-non-reasoning "quick text search"
node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning "topic with images"

---

模式

此技能支持六种不同模式，具体取决于用户的请求内容。Agent 应根据查询选择合适的模式。

模式 1：基本推文搜索

使用时机： 用户要求“搜索 X”“查找关于……的推文”或“大家都在说什么”。

运行方式：

node {baseDir}/scripts/search.js "query here"

示例查询：

• “搜索 X 上关于 Claude Code 技巧的内容”
• “查找关于新款 iPhone 的推文”
• “大家在 X 上都怎么评价 Rust？”

模式 2：串文阅读器

使用时机： 用户要求“阅读这条串文”“展开这条串文”，或提供 X/Twitter URL 并希望查看完整对话。

运行方式：

node {baseDir}/scripts/search.js "thread by @username about [topic] site:x.com"

阅读串文时，请构造一个包含作者账号名和串文主题的查询。Grok 的 x_search 会找到串文并返回完整的回复链。如果用户提供了直接推文 URL，请从 URL 中提取用户名和主题并进行搜索。

示例查询：

• “阅读这条串文：https://x.com/karpathy/status/1234567890”
  • 提取内容：搜索“@karpathy 发布的串文”，并使用 --handles karpathy --days 7
• “展开 @levelsio 关于初创公司的串文”
  • 搜索：--handles levelsio "startups thread"

串文阅读提示：

• 使用 --handles 锁定串文作者
• 使用 --days 3 或 --days 7 缩小时间范围
• 在查询中要求 Grok“包含串文中的所有回复”
• 如果串文很长，Grok 可能会进行总结——使用 --compact 重新运行，以获得更精简的输出

模式 3：趋势分析

使用时机： 用户询问“最近有什么趋势”“X 上有什么热门内容”或“关于［主题］有哪些热门讨论”。

运行方式：

node {baseDir}/scripts/search.js --days 1 "trending [topic] most discussed"

进行趋势分析时，请使用较短的时间范围（1-3 天），并加入“趋势”“走红”“讨论最多”或“热门讨论”等词语。Grok 会找出互动量高的帖子和常见主题。

示例查询：

• “今天 X 上关于 AI 有什么趋势？”
  • 搜索：--days 1 "trending AI most discussed viral"
• “这周 Twitter 上关于科技行业裁员有哪些热门讨论？”
  • 搜索：--days 7 "tech layoffs biggest conversations most discussed"
• “关于这次选举，有什么内容正在走红？”
  • 搜索：--days 1 "election viral trending"

趋势结果输出指南： 呈现趋势结果时，请按主题整理。将相关推文归为一组，并注明哪些主题的互动量最高。格式示例：

## Trending: [Topic] (last 24 hours)

### Theme 1: [Description]
- @user1: "tweet content" (high engagement)
  https://x.com/user1/status/123
- @user2: "related tweet"
  https://x.com/user2/status/456

### Theme 2: [Description]
- @user3: "tweet content"
  https://x.com/user3/status/789

模式 4：个人资料 / 账号分析

使用时机： 用户询问“X 上的 @handle 是谁”“@handle 会发布什么内容”或“显示 @handle 最近发布的帖子”。

运行方式：

node {baseDir}/scripts/search.js --handles username --days 30 "posts from @username"

分析个人资料时，使用 --handles 锁定该账号并搜索其近期动态。也可以结合主题筛选条件，查看某人关于特定主题发表过的内容。

示例查询：

• “@elonmusk 最近都发布了什么内容？”
  • 搜索：--handles elonmusk --days 7 "recent posts from @elonmusk"
• “显示 @karpathy 最近对 AI 的看法”
  • 搜索：--handles karpathy --days 30 "AI machine learning deep learning"
• “X 上的 @levelsio 是谁？”
  • 搜索：--handles levelsio --days 30 "posts from @levelsio about"

个人资料结果输出指南： 呈现个人资料结果时，请先概述此人主要发布的内容，再展示近期亮点：

## @username - Profile Summary

**Main topics:** AI, startups, indie hacking
**Posting frequency:** ~5-10 tweets/day
**Notable recent posts:**

1. @username (Mar 14): "tweet content"
   https://x.com/username/status/123

2. @username (Mar 12): "tweet content"
   https://x.com/username/status/456

模式 5：图片搜索

**使用时机：**用户需要 X 上的图片、截图、照片、表情包或其他视觉内容时。这是一项关键差异化功能——Grok-4.20 可以返回图片搜索结果。

运行方式：

node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning "images of [topic]"

**重要提示：**图片搜索必须使用 grok-4.20 模型。grok-4-1-fast 模型不会返回图片搜索结果。

你还可以将 Responses API + x_search 与 grok-imagine-image 结合起来，根据搜索上下文生成图片。例如，先搜索 X 上流行的表情包形式，再生成一张相同风格的新图片。

示例查询：

• “展示 X 上人们分享的有关火星着陆的图片”
  • 搜索：--model grok-4.20-beta-0309-reasoning --days 3 "Mars landing images photos"
• “查找 X 上有关编程的表情包”
  • 搜索：--model grok-4.20-beta-0309-reasoning --days 7 "programming memes funny"
• “人们分享了哪些有关 Claude Code 的截图？”
  • 搜索：--model grok-4.20-beta-0309-reasoning --days 7 "Claude Code screenshots"

模式 6：多 Agent 研究

**使用时机：**用户需要全面分析、跨主题比较，或需要从多个角度进行深入研究时。

运行方式：

node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 "comprehensive query"

多 Agent 模型会将复杂查询拆分为子任务，从多个角度进行搜索，并综合分析结果。适用于：

• “比较 @OpenAI 和 @AnthropicAI 社群对模型安全的看法”
• “全面介绍本月 React 与 Svelte 之争”
• “研究 X 上 [event] 争议的完整时间线”

---

提示词缓存

xAI 支持提示词缓存，缓存令牌的输入成本可降低 90%。以下场景适合使用：

• 使用相似的系统提示词或上下文重复执行搜索
• 使用相同的基础查询持续监控某个主题
• 构建定期轮询 X 的仪表板

API 会自动检测缓存令牌。组织请求时，应保持系统提示词和工具定义在多次调用之间一致，只更改用户查询。首次请求按全价计费；后续请求若使用相同前缀，则可享受 90% 的折扣。

---

批处理 API

xAI Batch API（自 2026 年 1 月起正式发布）支持批量处理搜索。可用于：

• 监控工作流——在一个批次中搜索 50 个不同的主题或账号
• 研究流程——以更低成本在夜间运行大量查询
• 竞争分析——并行追踪多个竞争对手在 X 上的动态

如何使用批量搜索

POST https://api.x.ai/v1/batch
Authorization: Bearer $XAI_API_KEY

{
  "requests": [
    {
      "custom_id": "search-1",
      "method": "POST",
      "url": "/v1/responses",
      "body": {
        "model": "grok-4-1-fast-non-reasoning",
        "tools": [{"type": "x_search"}],
        "input": "Query 1"
      }
    },
    {
      "custom_id": "search-2",
      "method": "POST",
      "url": "/v1/responses",
      "body": {
        "model": "grok-4-1-fast-non-reasoning",
        "tools": [{"type": "x_search"}],
        "input": "Query 2"
      }
    }
  ]
}

批处理请求会异步处理。轮询批次状态端点以检查是否完成。结果会按照请求的顺序返回。

---

输出格式

向用户展示搜索结果时，请将其格式化为包含互动信息的推文卡片。

标准推文卡片格式

@username (Display Name) - Mar 14, 2026
"The full tweet content goes here, preserving the original text
exactly as posted."

Link: https://x.com/username/status/1234567890123456789

紧凑格式（适用于大量结果）

- @username: "Tweet content truncated if needed..." (Mar 14)
  https://x.com/username/status/123

仅链接格式

当用户只需要 URL 时（例如，在浏览器中打开或传递给其他工具）：

https://x.com/user1/status/123
https://x.com/user2/status/456
https://x.com/user3/status/789

关键格式规则

1. 始终为每条推文附上 X 的直接链接
2. 保留推文原文，不要改写
3. 为每条推文注明作者的 @handle
4. 如果 Grok 返回互动数据（点赞、转发、回复），请一并注明
5. 按相关性对结果分组，而非按时间顺序排列；除非用户要求查看时间线
6. 如果没有找到结果，请明确说明，并建议尝试其他查询
7. 除非用户要求更多，否则最多返回 10-15 条推文

---

错误恢复

没有 API 密钥

如果未设置 XAI_API_KEY，且在配置中找不到密钥：

Error: No xAI API key found.
Set XAI_API_KEY in your environment or run:
  openclaw config set skills.entries.search-x.apiKey "xai-YOUR-KEY"
Get your key at: https://console.x.ai

速率限制（HTTP 429）

xAI API 设有速率限制。如果遇到 429：

1. 等待 10-15 秒后重试一次
2. 如果仍受速率限制，请告知用户：“已触发 xAI API 速率限制。请一分钟后重试。”
3. 不要重试超过一次——用户可以手动重新运行

身份验证失败（HTTP 401 / 403）

1. 告知用户，他们的 API 密钥可能无效或已过期
2. 引导他们前往 https://console.x.ai 检查密钥
3. 建议：export XAI_API_KEY="xai-NEW-KEY"

结果为空

如果 Grok 没有返回推文：

1. 尝试扩大时间范围：使用 --days 90，而不是 --days 7
2. 尝试移除账号筛选条件
3. 尝试使用更简单的查询词
4. 告知用户：“此查询没有找到推文。请尝试使用更宽泛的搜索词或更长的时间范围。”

超时 / 网络错误

1. Grok 处理复杂查询可能需要 5-15 秒，这是正常的
2. 多 Agent 查询可能需要 15-30 秒，这是预期情况
3. 如果请求超时，请使用更简单的查询重试一次
4. 如果网络中断，请明确告知用户

---

环境变量

变量	必需	默认值	描述
XAI_API_KEY	是	-	你在 console.x.ai 获取的 xAI API 密钥
SEARCH_X_MODEL	否	grok-4-1-fast-non-reasoning	搜索的默认模型
SEARCH_X_DAYS	否	30	默认时间范围，单位为天

---

聊天中的用法示例

简单搜索

用户：“在 X 上搜索大家对 Claude Code 的看法” **操作：**运行 node {baseDir}/scripts/search.js "Claude Code" **呈现：**带链接的推文卡片

按时间范围搜索

用户：“查找上周关于 Rust 与 Go 的推文” **操作：**运行 node {baseDir}/scripts/search.js --days 7 "Rust vs Go"

搜索特定账号

用户：“@karpathy 最近都发了些什么？” **操作：**运行 node {baseDir}/scripts/search.js --handles karpathy --days 14 "posts from @karpathy"

阅读帖子串

用户：“阅读这个帖子串：https://x.com/sama/status/1234567890” **操作：**提取账号名（sama），运行 node {baseDir}/scripts/search.js --handles sama --days 7 "thread"

趋势检查

用户：“今天 X 上关于 AI 的热门话题是什么？” **操作：**运行 node {baseDir}/scripts/search.js --days 1 "AI trending most discussed viral"

图片搜索

用户：“给我看看大家在 X 上分享的关于新款 MacBook 的图片” **操作：**运行 node {baseDir}/scripts/search.js --model grok-4.20-beta-0309-reasoning --days 7 "new MacBook images photos screenshots"

多 Agent 研究

用户：“全面分析本月 X 上关于 AI 安全的辩论” **操作：**运行 node {baseDir}/scripts/search.js --model grok-4.20-multi-agent-beta-0309 --days 30 "AI safety debate comprehensive analysis all perspectives"

多账号对比

用户：“@OpenAI 和 @AnthropicAI 对 AI 安全有什么看法？” **操作：**运行 node {baseDir}/scripts/search.js --handles OpenAI,AnthropicAI --days 30 "AI safety"

排除筛选

用户：“在 X 上搜索 AI 新闻，但排除机器人账号” **操作：**运行 node {baseDir}/scripts/search.js --exclude bots,spam --days 7 "AI news"

收藏链接以供稍后查看

用户：“给我本月关于独立开发的优质推文链接” **操作：**运行 node {baseDir}/scripts/search.js --links-only --days 30 "indie hacking best advice"

输出 JSON 以便管道处理

用户：“获取关于 TypeScript 的推文原始 JSON” **操作：**运行 node {baseDir}/scripts/search.js --json "TypeScript"

批量监控

用户：“设置对 X 上 10 个竞争对手账号的监控” **操作：**使用 Batch API 一次提交 10 个查询，每个竞争对手账号对应一个查询

---

获得最佳结果的技巧

1. 让查询具体明确。“Claude Code 单体仓库技巧”每次都比“Claude Code”效果更好。
2. **使用账号筛选器提高信噪比。**关注特定用户能大幅减少噪声。
3. **根据目标选择时间范围。**突发新闻 = 1 天。每周综述 = 7 天。研究 = 30-90 天。
4. **视觉查询使用 grok-4.20 模型。**只有这些模型会返回 X 上的图片结果。
5. 深入研究时使用多 Agent。grok-4.20-multi-agent-beta-0309 擅长多角度分析。
6. **组合使用不同模式。**搜索某个主题，找到有趣的帖子串，然后阅读全文。
7. **使用 --compact 进行快速浏览。**需要快速查看大量推文时，紧凑模式会去除评论。
8. **工作流中使用 --links-only。**将链接传递给浏览器启动器、书签工具或其他技能。
9. **利用提示词缓存。**在重复搜索中保持系统提示词一致，可节省 90% 的输入成本。
10. **批量处理时使用 Batch API。**监控、竞争分析和研究流水线都能受益于批处理。

---

相关技能

• /xai - 不通过 X 搜索直接与 Grok 聊天（通用知识、编码、分析）
• /last30days - 研究过去 30 天内多个来源发生的事件（不只是 X）
• /parallel - 并行运行多项搜索，加快研究工作流