X（Twitter）搜索
x_search 工具让代理直接搜索 X（Twitter）帖子、个人资料和线程。它由 xAI 在 Responses API 上的内置 x_search 工具支持（https://api.x.ai/v1/responses）——Grok 本身在服务器端运行搜索，并返回带有原始帖子引用的合成结果。
当您特别想要 X 上的当前讨论、反应或声明时，使用此工具代替 web_search。对于常规网页，请继续使用 web_search / web_extract。
认证
当 任一 xAI 凭证路径可用时，x_search 会注册：
| 凭证 | 来源 | 设置 |
|---|---|---|
| SuperGrok / X Premium+ OAuth（首选） | 在 accounts.x.ai 的浏览器登录，自动刷新 | hermes auth add xai-oauth — 参见 X Premium+） |
XAI_API_KEY | 付费 xAI API 密钥 | 在 ~/.hermes/.env 中设置 |
两者都使用相同的负载命中相同的端点——唯一的区别是 bearer token。当两者都配置时，SuperGrok OAuth 优先，因此 x_search 使用您的订阅配额运行，而非付费 API 消费。
该工具的 check_fn 在每次重建模型工具列表时运行 xAI 凭证解析器。返回 True 意味着 bearer 可获取且非空，且（如果已过期）已成功刷新。撤销的 token 且刷新失败时，工具从模式中隐藏；模型根本无法看到它。
启用工具
当 xAI 凭证（OAuth token 或 XAI_API_KEY）存在时自动启用。如果您不希望这样，通过 hermes tools → Search → x_search 显式禁用。
hermes tools
# → 🐦 X (Twitter) Search （按空格键开启）选择器提供两个凭证选项：
- xAI Grok OAuth（SuperGrok 订阅） — 如果您尚未登录，打开浏览器到
accounts.x.ai - 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工具参数
代理使用以下参数调用 x_search：
| 参数 | 类型 | 描述 |
|---|---|---|
query | 字符串（必需） | 在 X 上查找的内容。 |
allowed_x_handles | 字符串数组 | 可选，要独占包含的句柄列表（最多 10 个）。开头的 @ 被剥离。 |
excluded_x_handles | 字符串数组 | 可选，要排除的句柄列表（最多 10 个）。与 allowed_x_handles 互斥。 |
from_date | 字符串 | 可选的 YYYY-MM-DD 开始日期。 |
to_date | 字符串 | 可选的 YYYY-MM-DD 结束日期。 |
enable_image_understanding | 布尔值 | 要求 xAI 分析匹配帖子附带的图片。 |
enable_video_understanding | 布尔值 | 要求 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时为nullcredential_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 调用。
示例
与代理对话：
X 上的人对新 Grok 图片功能有什么看法？关注 @xai 的回复。
代理将：
- 调用
x_search，参数为query="reactions to new Grok image features"、allowed_x_handles=["xai"] - 返回合成答案及指向特定帖子的引用列表
- 回复答案和参考资料
故障排除
”没有可用的 xAI 凭证”
当两个认证路径都失败时，工具会显示此信息。要么在 ~/.hermes/.env 中设置 XAI_API_KEY，要么运行 hermes auth add xai-oauth 并完成浏览器登录。然后重启您的会话，以便代理重新读取工具注册表。
“x_search 未对此模型启用”
配置的 x_search.model 没有访问服务器端 x_search 工具的权限。切换到 grok-4.20-reasoning（默认值）或其他支持它的 Grok 模型。查看 xAI 文档 获取当前列表。
工具未出现在模式中
两个可能的原因：
- 工具集未启用。 运行
hermes tools并确认🐦 X (Twitter) Search已勾选。 - 没有 xAI 凭证。 check_fn 返回 False，因此模式保持隐藏。运行
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 订阅） — OAuth 设置指南
- 网络搜索与提取 — 用于一般的（非 X）网络搜索
- 工具参考 — 完整工具目录