hermes教程-X（Twitter）搜索

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。

提示

如果你已经为 xAI 模型支付了 Portal 费用，Live Search 调用将计入为聊天配置的同一 xAI 密钥。请参阅 Nous Portal。

身份验证

当 任一 xAI 凭证路径可用时，x_search 会注册：

两者都使用相同的负载访问相同的端点——唯一的区别是 bearer token。当两者都配置时，SuperGrok OAuth 优先，因此 x_search 将使用你的订阅配额，而不是付费 API 消费。

该工具的 check_fn 在每次重建模型工具列表时运行 xAI 凭证解析器。返回 True 表示 bearer 可获取且非空，并且（如果已过期）已成功刷新。刷新失败的已撤销令牌会从模式中隐藏该工具；模型根本无法看到它。

启用工具

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

hermes tools
## → 🐦 X (Twitter) Search   (按空格键切换开启)

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

1. xAI Grok OAuth (SuperGrok / Premium+) — 如果你尚未登录，则打开浏览器访问 accounts.x.ai
2. xAI API 密钥 — 提示输入 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：

该工具返回 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 调用。

示例

与代理对话：

人们在 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 文档 获取当前列表。

工具未出现在模式中

两个可能的原因：

1. 工具集未启用。 运行 hermes tools 并确认 🐦 X (Twitter) Search 已勾选。
2. 没有 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 / Premium+) — OAuth 设置指南
• Web 搜索与提取 — 用于一般（非 X）网页搜索
• 工具参考 — 完整工具目录