grok-search-cli 0.1.2 → 0.1.3

package/README.md

@@ -35,17 +35,16 @@ If no config exists yet, the CLI creates:
 ~/.config/grok-search-cli/config.json
 ```
 
-Update the generated config file using one of the bundled examples. The default xAI official config is:
+In most cases, you only need to set an API key from [xAI](https://x.ai/api):
 
 ```json
 {
-  "XAI_API_KEY": "your_xai_api_key",
-  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
-  "XAI_BASE_URL": "",
-  "XAI_COMPAT_MODE": false
+  "XAI_API_KEY": "your_xai_api_key"
 }
 ```
 
+If you are using a non-official provider, see [Configuration](#configuration).
+
 Run a query:
 
 ```bash
@@ -131,29 +130,36 @@ grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
 
 `process.env` takes priority over `~/.config/grok-search-cli/config.json`, so shell env is the easiest way to override config temporarily.
 
-### xAI Official
+By default, the CLI uses the official xAI endpoint and the built-in default model `grok-4-1-fast-non-reasoning`.
+
+| Field | Required | Default behavior | When you might override it |
+| --- | --- | --- | --- |
+| `XAI_API_KEY` | Yes | No default | Required in all cases |
+| `XAI_MODEL` | No | Uses `grok-4-1-fast-non-reasoning` | When you want a different Grok model |
+| `XAI_BASE_URL` | No | Uses the official xAI endpoint | When routing through OpenRouter or another compatible gateway |
+
+If you want to override the model:
 
 ```json
 {
   "XAI_API_KEY": "your_xai_api_key",
-  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
-  "XAI_BASE_URL": "",
-  "XAI_COMPAT_MODE": false
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning"
 }
 ```
 
-### OpenRouter
+Important: model IDs are provider-specific. The official xAI model ID, the OpenRouter model ID, and the model ID expected by another compatible gateway may not match. If you switch providers, check the provider's expected model name instead of reusing the previous one unchanged.
+
+### OpenRouter Example
 
 ```json
 {
   "XAI_API_KEY": "your_openrouter_api_key",
-  "XAI_MODEL": "x-ai/grok-4-fast:online",
-  "XAI_BASE_URL": "https://openrouter.ai/api/v1",
-  "XAI_COMPAT_MODE": false
+  "XAI_MODEL": "x-ai/grok-4.1-fast",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1"
 }
 ```
 
-### Yunwu / Other Compatible Gateways
+### Other Compatible Gateway Example
 
 ```json
 {
@@ -164,13 +170,23 @@ grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
 }
 ```
 
+For gateways such as yunwu, set `XAI_COMPAT_MODE=true`.
+
 ## Provider Guide
 
 Recommended order:
 
 1. Use official xAI APIs when possible. This is the most direct and stable path for `web_search` and `x_search`.
-2. OpenRouter is also a solid option. It can use native xAI-backed web search for xAI models.
-3. If you use a third-party proxy, verify search support yourself. Many proxies only expose `/chat/completions`, and search only works if the proxy provider has enabled web search on their side.
+2. OpenRouter is the best fallback when you do not want to use xAI directly. It is the most predictable non-official option here.
+3. Third-party compatible gateways such as yunwu are a compatibility fallback. Verify search support yourself. Many proxies only expose `/chat/completions`, and search only works if the proxy provider has enabled web search on their side.
+
+Recommended model choices:
+
+| Provider | Recommended model | Why |
+| --- | --- | --- |
+| xAI official | `grok-4-1-fast-non-reasoning` | Default path in this CLI, best support for `web_search` and `x_search` |
+| OpenRouter | `x-ai/grok-4.1-fast` | Best default when routing through OpenRouter |
+| Other compatible gateways such as yunwu | Provider-specific | Use the model ID your gateway actually exposes, for example `grok-4-fast` on yunwu |
 
 ## Search Modes
 
@@ -192,7 +208,7 @@ Use this when `XAI_BASE_URL` points to `openrouter.ai`.
 
 ### Other Compatible Gateways
 
-Use this when you connect through another OpenAI-compatible gateway with `XAI_COMPAT_MODE=true`.
+Use this when you connect through another OpenAI-compatible gateway.
 
 - Uses the gateway's compatibility path
 - Search behavior depends on the gateway

package/README.zh.md

@@ -34,17 +34,16 @@ grok-search doctor
 ~/.config/grok-search-cli/config.json
 ```
 
-打开这个文件，并按内置示例更新配置。默认的 xAI 官方配置如下：
+大多数情况下，你只需要填一个从 [xAI](https://x.ai/api) 获取的 API key：
 
 ```json
 {
-  "XAI_API_KEY": "your_xai_api_key",
-  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
-  "XAI_BASE_URL": "",
-  "XAI_COMPAT_MODE": false
+  "XAI_API_KEY": "your_xai_api_key"
 }
 ```
 
+如果你使用的是非官方提供商，见下方的[配置方式](#配置方式)。
+
 然后执行查询：
 
 ```bash
@@ -130,29 +129,36 @@ grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
 
 `process.env` 的优先级高于 `~/.config/grok-search-cli/config.json`，因此在临时覆盖配置时，优先使用 shell 环境变量。
 
-### xAI 官方
+默认情况下，CLI 会使用 xAI 官方地址和内置默认模型 `grok-4-1-fast-non-reasoning`。
+
+| 字段 | 是否必填 | 默认行为 | 什么时候可能要改 |
+| --- | --- | --- | --- |
+| `XAI_API_KEY` | 是 | 无默认值 | 所有场景都必须提供 |
+| `XAI_MODEL` | 否 | 使用 `grok-4-1-fast-non-reasoning` | 当你想切换到其他 Grok 模型时 |
+| `XAI_BASE_URL` | 否 | 使用 xAI 官方地址 | 当你要接 OpenRouter 或其他兼容网关时 |
+
+如果你想手动覆盖模型，可以这样写：
 
 ```json
 {
   "XAI_API_KEY": "your_xai_api_key",
-  "XAI_MODEL": "grok-4-1-fast-non-reasoning",
-  "XAI_BASE_URL": "",
-  "XAI_COMPAT_MODE": false
+  "XAI_MODEL": "grok-4-1-fast-non-reasoning"
 }
 ```
 
-### OpenRouter
+注意：不同服务商使用的 model id 不一定一样。xAI 官方、OpenRouter、以及其他兼容网关，通常都需要各自对应的模型名。切换服务商时，不要直接沿用原来的 model id。
+
+### OpenRouter 示例
 
 ```json
 {
   "XAI_API_KEY": "your_openrouter_api_key",
-  "XAI_MODEL": "x-ai/grok-4-fast:online",
-  "XAI_BASE_URL": "https://openrouter.ai/api/v1",
-  "XAI_COMPAT_MODE": false
+  "XAI_MODEL": "x-ai/grok-4.1-fast",
+  "XAI_BASE_URL": "https://openrouter.ai/api/v1"
 }
 ```
 
-### yunwu / 其他兼容代理站
+### 其他兼容网关示例
 
 ```json
 {
@@ -163,13 +169,23 @@ grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
 }
 ```
 
+像 yunwu 这类兼容网关，通常需要设置 `XAI_COMPAT_MODE=true`。
+
 ## 服务选择建议
 
 推荐顺序：
 
 1. 优先使用 xAI 官方服务。这是 `web_search` 和 `x_search` 最直接、最稳定的路径。
-2. OpenRouter 也比较稳。它对 xAI 模型可以走原生 xAI 支持的 web search。
-3. 如果使用第三方代理站，需要自己确认搜索能力。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
+2. 如果不直连 xAI，优先用 OpenRouter。这是这里最稳的非官方选项。
+3. 第三方兼容网关，例如 yunwu，更适合作为兼容兜底。很多代理站只暴露 `/chat/completions`，是否真的能搜索，取决于站点是否在内部为你开启了 web search。
+
+推荐模型：
+
+| 服务商 | 推荐模型 | 说明 |
+| --- | --- | --- |
+| xAI 官方 | `grok-4-1-fast-non-reasoning` | 这是当前 CLI 的默认模型，也是 `web_search` 和 `x_search` 支持最完整的路径 |
+| OpenRouter | `x-ai/grok-4.1-fast` | 通过 OpenRouter 接入时，优先用这个 |
+| 其他兼容网关，例如 yunwu | 以网关实际支持的 model id 为准 | 比如 yunwu 示例里使用 `grok-4-fast` |
 
 ## 搜索模式
 
@@ -191,7 +207,7 @@ grok-search skill > ~/.codex/skills/grok-search-cli/SKILL.md
 
 ### 其他兼容网关
 
-当你通过其他 OpenAI-compatible 网关接入，并启用 `XAI_COMPAT_MODE=true` 时使用。
+当你通过其他 OpenAI-compatible 网关接入时使用。
 
 - 使用网关提供的兼容调用路径
 - 是否真的搜索、怎么搜索，由中转站决定