grok-search

grok-search 同时提供一个 OpenAI Chat Completions 兼容 CLI，以及一个符合 Agent Skills 规范、可被 OpenCode 按需加载的 Skill。Skill 自带执行脚本，安装 Skill 后不需要再全局安装 CLI。

它解决什么问题

• 为 AI 提供明确的实时搜索触发条件，而不是把所有知识问题都送去联网。
• 强制搜索结果保留来源、发布日期和不确定性。
• 将 API 调用脚本随 Skill 一起安装，避免“Skill 已安装但 grok-search 命令不存在”。
• 使用专用用户配置路径，不读取项目中的通用 config.json。
• API key 通过环境变量传入，不提供容易泄漏到历史记录的 --api-key 参数。

OpenAI 兼容仅代表请求和响应格式兼容，不会自动赋予模型联网能力。配置的 Grok 模型或 API 网关必须实际支持实时搜索。

安装 Skill

从当前仓库安装到 OpenCode 全局目录：

npx skills add . --skill grok-search --agent opencode --global --yes

从 GitHub 仓库安装时，将 . 换成仓库地址：

npx skills add <owner>/<repo> --skill grok-search --agent opencode --global --yes

OpenCode 的全局安装位置是 ~/.config/opencode/skills/grok-search/。安装或更新后需要退出并重启 OpenCode，当前会话不会热加载 Skill。

也可以在项目 opencode.json 中直接注册本仓库：

{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": ["./skills"]
  }
}

配置

推荐使用环境变量：

GROK_SEARCH_BASE_URL=https://api.x.ai/v1
GROK_SEARCH_API_KEY=your-api-key
GROK_SEARCH_MODEL=your-search-capable-grok-model

可选变量：

GROK_SEARCH_TEMPERATURE=0.2
GROK_SEARCH_STREAM=true
GROK_SEARCH_TIMEOUT_MS=90000
GROK_SEARCH_CONFIG=/absolute/path/to/config.json

也可以初始化用户级配置模板：

node skills/grok-search/scripts/grok-search.mjs init

模板默认写入 $XDG_CONFIG_HOME/grok-search/config.json，未设置 XDG_CONFIG_HOME 时写入 ~/.config/grok-search/config.json。API key 仍建议只放在 GROK_SEARCH_API_KEY。

使用

Skill 内置脚本：

node skills/grok-search/scripts/grok-search.mjs search "今天 Anthropic 有哪些官方新消息？请给出发布日期和直接来源链接。"

可选的全局 CLI：

npm install -g .
grok-search search "What changed in the latest OpenAI release? Cite primary sources."

AI 用户只需提出自然语言请求，例如：

用 Grok 搜索并核实今天 Anthropic 的官方新消息，附直接来源。

验证

npm test
npm run check
npm run validate:skill
npm pack --dry-run

目录

skills/grok-search/
├── SKILL.md
├── references/configuration.md
└── scripts/grok-search.mjs

SKILL.md 保持短小，只放每次调用都需要的流程和可靠性约束；配置细节按需从 references/ 加载；可执行逻辑位于 scripts/，符合 Agent Skills 的渐进披露设计。

License

MIT