X (Twitter) 搜索

x_search 工具让 agent 可以直接搜索 X (Twitter) 的帖子、账号和话题串。其底层依托 xAI 在 Responses API（https://api.x.ai/v1/responses）上内置的 x_search 工具——Grok 在服务端执行搜索，并返回带有原始帖子引用的综合结果。

当你明确需要 X 上的当前讨论、反应或观点时，请使用此工具而非 web_search。 对于一般网页内容，继续使用 web_search / web_extract。

认证

满足以下任一 xAI 凭据路径时，x_search 即会注册：

凭据	来源	配置方式
SuperGrok / X Premium+ OAuth（推荐）	在 `accounts.x.ai` 浏览器登录，自动刷新	`hermes auth add xai-oauth` — 参见 xAI Grok OAuth (SuperGrok / X Premium+)
`XAI_API_KEY`	付费 xAI API 密钥	在 `~/.hermes/.env` 中设置

两者使用相同的 endpoint 和相同的请求体，区别仅在于 bearer token。当两者同时配置时，SuperGrok OAuth 优先，x_search 将消耗你的订阅配额而非付费 API 用量。

工具的 check_fn 在每次重建模型工具列表时都会运行 xAI 凭据解析器。返回 True 表示 bearer token 可获取、非空，且（若已过期）已成功刷新。刷新失败的已撤销 token 会将该工具从 schema 中隐藏，模型将无法感知其存在。

启用工具

当 xAI 凭据（OAuth token 或 XAI_API_KEY）存在时自动启用。如不需要，可通过 hermes tools → Search → x_search 显式禁用。

选择器提供两种凭据选项：

xAI Grok OAuth (SuperGrok / Premium+) — 若尚未登录，将打开浏览器跳转至 accounts.x.ai

xAI API key — 提示输入 XAI_API_KEY

任一选项均可满足门控条件。你可以使用已有的任意凭据，工具行为完全相同。若两者均已配置，调用时 OAuth 优先。

配置

工具参数

agent 调用 x_search 时使用以下参数：

参数	类型	说明
`query`	string（必填）	在 X 上要查找的内容。
`allowed_x_handles`	string 数组	可选，仅包含指定账号的列表（最多 10 个）。前缀 `@` 会被自动去除。
`excluded_x_handles`	string 数组	可选，要排除的账号列表（最多 10 个）。与 `allowed_x_handles` 互斥。
`from_date`	string	可选，`YYYY-MM-DD` 格式的起始日期。
`to_date`	string	可选，`YYYY-MM-DD` 格式的结束日期。
`enable_image_understanding`	boolean	让 xAI 分析匹配帖子中附带的图片。
`enable_video_understanding`	boolean	让 xAI 分析匹配帖子中附带的视频。

工具返回的 JSON 包含：

answer — Grok 生成的综合文本回答

citations — Responses API 顶层字段返回的引用

inline_citations — 从消息正文中提取的 url_citation 注释（每条包含 url、title、start_index、end_index）

degraded — 当设置了任意缩小范围的过滤器（allowed_x_handles、excluded_x_handles、from_date、to_date）且两个引用渠道均返回空时为 true。此时 answer 是基于模型自身知识合成的，而非来自 X 索引，应视为无来源内容。否则为 false（包括"未设置过滤器"的情况——宽泛的无来源回答只是一个回答，而非过滤器未命中）

degraded_reason — 列出哪些过滤器处于激活状态的简短字符串，当 degraded 为 false 时为 null

credential_source — OAuth 解析成功时为 "xai-oauth"，API 密钥解析成功时为 "xai"

model、query、provider、tool、success

日期验证

from_date / to_date 在发起 HTTP 调用前会在客户端进行验证：

若提供，两者均须能解析为 YYYY-MM-DD 格式。

当两者同时设置时，from_date 必须不晚于 to_date。

from_date 不得晚于今天（UTC）——尚未开始的时间窗口内不可能存在帖子，调用必然返回零引用。

to_date 允许为未来日期（调用方可能合理地请求"从昨天到明天"以捕获即将发布的帖子）。

验证失败会以结构化的 {"error": "..."} 工具结果返回，不会向 xAI 发起 HTTP 调用。

示例

与 agent 对话：

X 上的人们对新的 Grok 图像功能有什么看法？重点关注 @xai 的回应。

agent 将：

以 query="reactions to new Grok image features"、allowed_x_handles=["xai"] 调用 x_search

获取综合回答及指向具体帖子的引用列表

回复包含答案和参考来源

故障排查

"No xAI credentials available"

当两种认证路径均失败时，工具会显示此错误。请在 ~/.hermes/.env 中设置 XAI_API_KEY，或运行 hermes auth add xai-oauth 并完成浏览器登录。然后重启会话，让 agent 重新加载工具注册表。

"`x_search` is not enabled for this model"

配置的 x_search.model 没有访问服务端 x_search 工具的权限。请切换至 grok-4.20-reasoning（默认值）或其他支持该工具的 Grok 模型。当前支持列表请查阅 xAI 文档。

工具未出现在 schema 中

可能有两个原因：

工具集未启用。 运行 hermes tools，确认 🐦 X (Twitter) Search 已勾选。

无 xAI 凭据。 check_fn 返回 False，schema 保持隐藏。运行 hermes auth status 确认 xai-oauth 登录状态，并检查 XAI_API_KEY 是否已设置（如使用 API 密钥路径）。

`degraded: true` — 回答无引用来源

当你使用了 allowed_x_handles、excluded_x_handles 或日期范围，且响应返回 degraded: true 时，说明 xAI 的 X 索引未找到匹配帖子，但 Grok 仍基于自身训练数据生成了综合回答。该回答无来源支撑——请勿将其视为真实的 X 内容。

值得排查的原因：

账号名拼写错误。 去掉 @，仔细核对拼写，并确认该账号存在。

日期范围过窄，或滑过了今日帖子；请扩大范围后重试。

xAI 索引缺口。 部分活跃账号即使定期发帖，也会间歇性地无法在 x_search 中出现。请等待几分钟后重试，或在需要精确获取某账号时间线时使用 xurl 技能直接调用 X API。

另请参阅

xAI Grok OAuth (SuperGrok / Premium+) — OAuth 配置指南

Web 搜索与提取 — 用于一般（非 X）网页搜索

工具参考 — 完整工具目录

认证#

启用工具#

配置#

工具参数#

日期验证#

示例#

故障排查#

"No xAI credentials available"#

"x_search is not enabled for this model"#

工具未出现在 schema 中#

degraded: true — 回答无引用来源#

另请参阅#

认证