hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/x-search.md

title	description	sidebar_label	sidebar_position
X (Twitter) 搜索	使用 xAI 内置的 x_search Responses 工具在 agent 内搜索 X (Twitter) 帖子和话题串——支持 SuperGrok OAuth 登录或 XAI_API_KEY。	X (Twitter) 搜索	7

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 显式禁用。

hermes tools
# → 🐦 X (Twitter) Search   (press space to toggle on)

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

1. xAI Grok OAuth (SuperGrok / Premium+) — 若尚未登录，将打开浏览器跳转至 accounts.x.ai
2. xAI API key — 提示输入 XAI_API_KEY

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

配置

# ~/.hermes/config.yaml
x_search:
  # 用于 Responses 调用的 xAI 模型。
  # grok-4.20-reasoning 是推荐的默认值；任何支持
  # x_search 工具访问权限的 Grok 模型均可使用。
  model: grok-4.20-reasoning

  # 请求超时时间（秒）。复杂查询的 x_search 可能需要 60–120 秒，
  # 默认值较为宽松。最小值：30。
  timeout_seconds: 180

  # 遇到 5xx / ReadTimeout / ConnectionError 时的自动重试次数。
  # 每次重试按指数退避（1.5 倍尝试秒数，上限 5 秒）。
  retries: 2

工具参数

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 将：

1. 以 query="reactions to new Grok image features"、allowed_x_handles=["xai"] 调用 x_search
2. 获取综合回答及指向具体帖子的引用列表
3. 回复包含答案和参考来源

故障排查

"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 中

可能有两个原因：

1. 工具集未启用。 运行 hermes tools，确认 🐦 X (Twitter) Search 已勾选。
2. 无 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）网页搜索
• 工具参考 — 完整工具目录