Custom Grok Search

使用 xAI Grok 的 Responses API 进行网页搜索与 X/Twitter 搜索；支持官方 xAI 接口，也支持通过公益站或其他第三方 Grok 兼容代理来使用 web_search / x_search。

Security Scan

The skill mostly does what it says (wraps xAI/Grok Responses API for web/X search) but it quietly reads multiple local config locations and environment variables not declared in the registry metadata and will reuse API keys it finds in a home config file — this mismatch and the broad config access merit caution.

Purpose & Capability

Name/description match the code: the scripts call the Responses API and request web_search/x_search tools. It also supports official xAI keys or a custom Grok-compatible proxy, which matches the declared purpose. However the registry metadata claimed no required env vars/credentials while the code actively looks for many environment variables and a home config file for API keys (CUSTOM_GROK_APIKEY, XAI_API_KEY, CUSTOM_GROK_BASE_URL, etc.), so the metadata understates the credential/config needs.

Instruction Scope

SKILL.md instructs running the included scripts; the scripts do only API calls and optional image reads. But at runtime they will: (1) load $PWD/.env and ~/.openclaw/.env, (2) read ~/.clawdbot/clawdbot.json for stored API keys, (3) base64-embed image files when --image is used, and (4) perform real network calls to the configured base URL. These file reads and use of a home config file are not surfaced in the registry metadata and could expose secrets from shared config files if present. The selftest script also makes real API calls (not a dry run), which may transmit keys/data externally.

Install Mechanism

No install spec and no external downloads; the skill is instruction+scripts only. There is no installer that pulls arbitrary code from URLs or writes binaries to unusual locations.

Credentials

Although the skill needs an API key to call the Responses API, it reads many environment variables and configuration locations beyond the registry's declared 'none'. In particular it looks for CUSTOM_GROK_APIKEY and XAI_API_KEY, but also CUSTOM_GROK_BASE_URL, CUSTOM_GROK_MODEL, XAI_BASE_URL, GROK_MODEL, XAI_USER_AGENT and will read ~/.clawdbot/clawdbot.json and reuse apiKey values found under multiple possible keys (including entries for other skills). That expands its access surface to other stored credentials and may cause unintended use of unrelated API keys found in the user's config file.

Persistence & Privilege

The skill does not request persistent system presence (always:false) and does not modify other skills or system settings. It runs as normal user-level scripts and spawns child processes only within selftest; no privileged operations are requested.

What to consider before installing

This skill appears to implement the advertised Grok/xAI search functionality, but it reads .env files ($PWD/.env and ~/.openclaw/.env) and ~/.clawdbot/clawdbot.json to find API keys and settings — behavior not declared in the registry metadata. Before installing or running: (1) inspect ~/.clawdbot/clawdbot.json and any .env files to ensure they don't contain unrelated secrets you don't want the script to read; (2) if using a third-party proxy, verify CUSTOM_GROK_BASE_URL is a trusted endpoint because your API key (and optional image data) will be sent there; (3) avoid running selftest unless you want the script to make real external API calls; (4) prefer providing only the minimal API key (official XAI key) rather than broad config files; and (5) if you need stricter control, modify the scripts to only read a single explicit env var you provide rather than searching home config files.

这个 Skill 用来调用 Grok 的服务端搜索工具：

• web_search：网页搜索
• x_search：X / Twitter 搜索

适用场景：

• 用户想搜索网页信息，但希望走 Grok / xAI 能力
• 用户想搜 X / Twitter 上的帖子、账号、讨论串
• 运行环境没有直接使用官方 xAI 接口，而是改走公益站或其他第三方 Grok 兼容代理

支持的两种模式

1. 官方 xAI 模式

如果环境里提供的是官方 xAI 凭证，脚本会直接请求官方接口。

适合：

• 你自己有官方 xAI Key
• 不需要第三方代理

2. 公益站 / 第三方代理模式

如果检测到 CUSTOM_GROK_APIKEY，脚本会自动切换到第三方 Grok 兼容代理模式。

适合：

• 通过公益站使用 Grok Search
• 使用自建或第三方兼容 OpenAI / xAI Responses API 的代理
• 需要自定义 base URL、模型名、User-Agent

如果你需要配置代理相关变量，请读取：

• references/config.md

如果你需要官方文档入口，请读取：

• references/xai-tools-links.md

运行方式

使用 {baseDir} 来引用 Skill 目录，避免因为工作目录不同导致路径失效。

搜索

• 网页搜索：

  • node {baseDir}/scripts/grok_search.mjs "<query>" --web

• X / Twitter 搜索：

  • node {baseDir}/scripts/grok_search.mjs "<query>" --x

对话

• 文本对话：

  • node {baseDir}/scripts/chat.mjs "<prompt>"

• 图像对话：

  • node {baseDir}/scripts/chat.mjs --image /path/to/image.jpg "<prompt>"

其他

• 列出可用模型：

  • node {baseDir}/scripts/models.mjs

• 运行轻量自检：

  • node {baseDir}/scripts/selftest.mjs

常用参数

搜索脚本支持这些常用参数：

输出控制

• --links-only：只输出引用链接
• --text：输出精简文本，不展示 citations 段
• --raw：把原始 Responses API 返回写到 stderr，便于排错

通用参数

• --max <n>：限制结果数，默认 8
• --model <id>：本次调用临时指定模型

X / Twitter 搜索过滤

• --days <n>：限制最近 N 天
• --from YYYY-MM-DD
• --to YYYY-MM-DD
• --handles @a,@b：只看这些账号
• --exclude @bots,@spam：排除这些账号

输出格式

默认输出为便于 agent 消费的 JSON，大致结构如下：

{
  "query": "...",
  "mode": "web" | "x",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "author": "...",
      "posted_at": "..."
    }
  ],
  "citations": ["https://..."]
}

使用建议

• 一般网页研究优先用 --web
• 查推文、帖子、线程时优先用 --x
• 如果你是通过公益站或第三方代理使用 Grok，先看 references/config.md 再调用脚本
• 如果模型偶发没有严格返回 JSON，脚本会尽量透传文本结果，而不是直接硬失败