Skip to main content

X（Twitter）搜索

x_search 工具允许代理直接在 X（Twitter）上搜索帖子、个人资料和话题线。该功能由 xAI 内置的 x_search 工具支持，通过 Responses API 的 https://api.x.ai/v1/responses 进行调用——Grok 本身在服务端执行搜索，并返回带有原始帖子引用的合成结果。

当您特别需要获取 X 平台上的实时讨论、反应或声明时，请使用此工具替代 web_search。若需进行一般性网页搜索，请继续使用 web_search / web_extract。

认证方式​

x_search 在满足以下任一条件时注册：

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

两者调用同一接口并使用相同请求体——唯一区别在于承载令牌（bearer token）。当两者均配置时，SuperGrok OAuth 优先级更高，因此 x_search 将使用您的订阅配额，而非消耗付费 API 调用额度。

该工具的 check_fn 会在模型工具列表重建时每次运行 xAI 凭据解析器。若返回 True，则表示承载令牌可获取、非空，且若曾过期也已成功刷新。已被撤销且刷新失败的令牌将使该工具从 schema 中隐藏，模型无法识别该工具。

启用工具​

默认关闭。请在 hermes tools 中启用：

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

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

  1. xAI Grok OAuth（SuperGrok 订阅） —— 若未登录，将打开浏览器跳转至 accounts.x.ai
  2. xAI API 密钥 —— 提示输入 XAI_API_KEY

任一选择均可满足准入条件。您可以根据已有凭证自由选择；两种方式下工具行为完全一致。若两者均配置，调用时将优先使用 OAuth。

配置​

# ~/.hermes/config.yaml
x_search:
  # xAI model used for the Responses call.
  # grok-4.20-reasoning is the recommended default; any Grok model
  # with x_search tool access works.
  model: grok-4.20-reasoning

  # Request timeout in seconds. x_search can take 60–120s for
  # complex queries — the default is generous. Minimum: 30.
  timeout_seconds: 180

  # Number of automatic retries on 5xx / ReadTimeout / ConnectionError.
  # Each retry backs off (1.5x attempt seconds, capped at 5s).
  retries: 2

工具参数​

代理调用 x_search 时传入以下参数：

参数类型说明
query字符串（必填）您希望在 X 上查找的内容。
allowed_x_handles字符串数组可选：仅包含指定账号（最多 10 个）。前缀 @ 会被自动去除。
excluded_x_handles字符串数组可选：排除指定账号（最多 10 个）。与 allowed_x_handles 互斥。
from_date字符串可选：开始日期（格式为 ISO 8601，如 2024-01-01）。
to_date字符串可选：结束日期（格式为 ISO 8601，如 2024-01-31）。
enable_image_understanding布尔值是否要求 xAI 分析匹配帖子中附带的图片。
enable_video_understanding布尔值是否要求 xAI 分析匹配帖子中附带的视频。

工具返回 JSON 格式数据，包含：

  • answer —— Grok 生成的合成文本回答
  • citations —— Responses API 返回的引用列表（顶级字段）
  • inline_citations —— 从消息正文提取的 url_citation 注释（每个包含 url、title、start_index、end_index）
  • credential_source —— 当前认证类型："xai-oauth"（OAuth 解析成功），或 "xai"（API Key 解析成功）
  • model, query, provider, tool, success

示例​

与代理对话：

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

代理将：

  1. 调用 x_search，传入 query="reactions to new Grok image features" 和 allowed_x_handles=["xai"]
  2. 获取合成答案及指向具体帖子的引用列表
  3. 回复包含答案和参考链接

故障排查​

“无可用 xAI 凭证”​

该提示出现在两种认证路径均失败时。请在 ~/.hermes/.env 中设置 XAI_API_KEY，或运行 hermes auth add xai-oauth 完成浏览器登录。之后重启会话，以便代理重新读取工具注册表。

“x_search 未为此模型启用”​

当前配置的 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 密钥路径）。

参考​