@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/tools/thinking.md

@@ -0,0 +1,80 @@
+---
+read_when:
+  - 调整思考或详细模式指令解析或默认值时
+summary: "`/think` + `/verbose` 的指令语法及其对模型推理的影响"
+title: 思考级别
+x-i18n:
+  generated_at: "2026-02-01T21:43:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 1a611474c2781c9a8e9dac0e084e7ee4ef58aebece181fdc877392fc27442746
+  source_path: tools/thinking.md
+  workflow: 15
+---
+
+# 思考级别（/think 指令）
+
+## 功能说明
+
+- 在任何入站消息正文中使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
+- 级别（别名）：`off | minimal | low | medium | high | xhigh`（仅 GPT-5.2 + Codex 模型）
+  - minimal → "think"
+  - low → "think hard"
+  - medium → "think harder"
+  - high → "ultrathink"（最大预算）
+  - xhigh → "ultrathink+"（仅 GPT-5.2 + Codex 模型）
+  - `highest`、`max` 映射为 `high`。
+- 提供商说明：
+  - Z.AI（`zai/*`）仅支持二元思考（`on`/`off`）。任何非 `off` 级别均视为 `on`（映射为 `low`）。
+
+## 解析优先顺序
+
+1. 消息上的内联指令（仅适用于该条消息）。
+2. 会话覆盖（通过发送仅包含指令的消息设置）。
+3. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
+4. 回退：具备推理能力的模型为 low；否则为 off。
+
+## 设置会话默认值
+
+- 发送一条**仅包含**指令的消息（允许空白），例如 `/think:medium` 或 `/t high`。
+- 该设置在当前会话中持续生效（默认按发送者）；通过 `/think:off` 或会话空闲重置来清除。
+- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令将被拒绝并给出提示，会话状态保持不变。
+- 不带参数发送 `/think`（或 `/think:`）可查看当前思考级别。
+
+## 按智能体应用
+
+- **内嵌 Pi**：解析后的级别传递给进程内的 Pi 智能体运行时。
+
+## 详细模式指令（/verbose 或 /v）
+
+- 级别：`on`（最小）| `full` | `off`（默认）。
+- 仅包含指令的消息切换会话详细模式并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别返回提示且不改变状态。
+- `/verbose off` 存储一个显式的会话覆盖；通过会话 UI 选择 `inherit` 来清除。
+- 内联指令仅影响该条消息；否则应用会话/全局默认值。
+- 不带参数发送 `/verbose`（或 `/verbose:`）可查看当前详细模式级别。
+- 启用详细模式后，发出结构化工具结果的智能体（Pi 及其他 JSON 智能体）会将每个工具调用作为独立的元数据消息发回，可用时以 `<emoji> <tool-name>: <arg>` 为前缀（路径/命令）。这些工具摘要在每个工具启动时立即发送（独立气泡），而非作为流式增量。
+- 当详细模式为 `full` 时，工具输出也会在完成后转发（独立气泡，截断至安全长度）。如果在运行过程中切换 `/verbose on|full|off`，后续的工具气泡会遵循新设置。
+
+## 推理可见性（/reasoning）
+
+- 级别：`on|off|stream`。
+- 仅包含指令的消息切换回复中是否显示思考块。
+- 启用时，推理内容作为**独立消息**发送，以 `Reasoning:` 为前缀。
+- `stream`（仅 Telegram）：在回复生成期间将推理内容流式输出到 Telegram 草稿气泡中，然后发送不包含推理的最终回答。
+- 别名：`/reason`。
+- 不带参数发送 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
+
+## 相关内容
+
+- 提权模式文档位于[提权模式](/tools/elevated)。
+
+## 心跳
+
+- 心跳探测正文为配置的心跳提示词（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令照常生效（但避免从心跳中更改会话默认值）。
+- 心跳投递默认仅包含最终负载。要同时发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或按智能体 `agents.list[].heartbeat.includeReasoning: true`。
+
+## Web 聊天 UI
+
+- Web 聊天的思考选择器在页面加载时从入站会话存储/配置中读取并反映会话的已存储级别。
+- 选择另一个级别仅应用于下一条消息（`thinkingOnce`）；发送后，选择器会回到已存储的会话级别。
+- 要更改会话默认值，请发送 `/think:<level>` 指令（和之前一样）；选择器将在下次刷新后反映该设置。

package/docs/zh-CN/tools/web.md

@@ -0,0 +1,264 @@
+---
+read_when:
+  - 你想启用 web_search 或 web_fetch
+  - 你需要设置 Brave Search API 密钥
+  - 你想使用 Perplexity Sonar 进行网页搜索
+summary: 网页搜索 + 抓取工具（Brave Search API、Perplexity 直连/OpenRouter）
+title: 网页工具
+x-i18n:
+  generated_at: "2026-02-01T21:43:53Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 760b706cc966cb421e370f10f8e76047f8ca9fe0a106d90c05d979976789465a
+  source_path: tools/web.md
+  workflow: 15
+---
+
+# 网页工具
+
+OpenClaw 内置两个轻量级网页工具：
+
+- `web_search` — 通过 Brave Search API（默认）或 Perplexity Sonar（直连或通过 OpenRouter）搜索网页。
+- `web_fetch` — HTTP 抓取 + 可读内容提取（HTML → markdown/文本）。
+
+这些**不是**浏览器自动化。对于 JS 密集型网站或需要登录的场景，请使用
+[浏览器工具](/tools/browser)。
+
+## 工作原理
+
+- `web_search` 调用你配置的提供商并返回结果。
+  - **Brave**（默认）：返回结构化结果（标题、URL、摘要）。
+  - **Perplexity**：返回基于实时网页搜索的 AI 综合答案及引用来源。
+- 结果按查询缓存 15 分钟（可配置）。
+- `web_fetch` 执行普通 HTTP GET 并提取可读内容
+  （HTML → markdown/文本）。它**不会**执行 JavaScript。
+- `web_fetch` 默认启用（除非显式禁用）。
+
+## 选择搜索提供商
+
+| 提供商            | 优点                            | 缺点                                   | API 密钥                                     |
+| ----------------- | ------------------------------- | -------------------------------------- | -------------------------------------------- |
+| **Brave**（默认） | 快速、结构化结果、有免费额度    | 传统搜索结果                           | `BRAVE_API_KEY`                              |
+| **Perplexity**    | AI 综合答案、引用来源、实时搜索 | 需要 Perplexity 或 OpenRouter 访问权限 | `OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY` |
+
+有关特定提供商的详情，请参阅 [Brave Search 设置](/brave-search) 和 [Perplexity Sonar](/perplexity)。
+
+在配置中设置提供商：
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "brave", // 或 "perplexity"
+      },
+    },
+  },
+}
+```
+
+示例：切换到 Perplexity Sonar（直连 API）：
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...",
+          baseUrl: "https://api.perplexity.ai",
+          model: "perplexity/sonar-pro",
+        },
+      },
+    },
+  },
+}
+```
+
+## 获取 Brave API 密钥
+
+1. 在 https://brave.com/search/api/ 创建 Brave Search API 账户
+2. 在控制面板中，选择 **Data for Search** 计划（不是 "Data for AI"）并生成 API 密钥。
+3. 运行 `openclaw configure --section web` 将密钥存储到配置中（推荐），或在环境中设置 `BRAVE_API_KEY`。
+
+Brave 提供免费额度和付费计划；请查看 Brave API 门户了解
+当前的限制和定价。
+
+### 密钥设置位置（推荐）
+
+**推荐：**运行 `openclaw configure --section web`。它会将密钥存储在
+`~/.openclaw/openclaw.json` 的 `tools.web.search.apiKey` 下。
+
+**环境变量替代方案：**在 Gateway网关进程环境中设置 `BRAVE_API_KEY`。对于 Gateway网关安装，将其放入 `~/.openclaw/.env`（或你的
+服务环境）。参见[环境变量](/help/faq#how-does-openclaw-load-environment-variables)。
+
+## 使用 Perplexity（直连或通过 OpenRouter）
+
+Perplexity Sonar 模型内置网页搜索功能，并返回带有引用来源的 AI 综合
+答案。你可以通过 OpenRouter 使用它们（无需信用卡——支持
+加密货币/预付费）。
+
+### 获取 OpenRouter API 密钥
+
+1. 在 https://openrouter.ai/ 创建账户
+2. 充值（支持加密货币、预付费或信用卡）
+3. 在账户设置中生成 API 密钥
+
+### 设置 Perplexity 搜索
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        provider: "perplexity",
+        perplexity: {
+          // API 密钥（如果已设置 OPENROUTER_API_KEY 或 PERPLEXITY_API_KEY 则可选）
+          apiKey: "sk-or-v1-...",
+          // 基础 URL（省略时根据密钥自动选择默认值）
+          baseUrl: "https://openrouter.ai/api/v1",
+          // 模型（默认为 perplexity/sonar-pro）
+          model: "perplexity/sonar-pro",
+        },
+      },
+    },
+  },
+}
+```
+
+**环境变量替代方案：**在 Gateway网关环境中设置 `OPENROUTER_API_KEY` 或 `PERPLEXITY_API_KEY`。对于 Gateway网关安装，将其放入 `~/.openclaw/.env`。
+
+如果未设置基础 URL，OpenClaw 会根据 API 密钥来源选择默认值：
+
+- `PERPLEXITY_API_KEY` 或 `pplx-...` → `https://api.perplexity.ai`
+- `OPENROUTER_API_KEY` 或 `sk-or-...` → `https://openrouter.ai/api/v1`
+- 未知密钥格式 → OpenRouter（安全回退）
+
+### 可用的 Perplexity 模型
+
+| 模型                             | 描述                 | 最适合   |
+| -------------------------------- | -------------------- | -------- |
+| `perplexity/sonar`               | 带网页搜索的快速问答 | 快速查询 |
+| `perplexity/sonar-pro`（默认）   | 带网页搜索的多步推理 | 复杂问题 |
+| `perplexity/sonar-reasoning-pro` | 思维链分析           | 深度研究 |
+
+## web_search
+
+使用你配置的提供商搜索网页。
+
+### 前提条件
+
+- `tools.web.search.enabled` 不能为 `false`（默认：启用）
+- 你选择的提供商的 API 密钥：
+  - **Brave**：`BRAVE_API_KEY` 或 `tools.web.search.apiKey`
+  - **Perplexity**：`OPENROUTER_API_KEY`、`PERPLEXITY_API_KEY` 或 `tools.web.search.perplexity.apiKey`
+
+### 配置
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        apiKey: "BRAVE_API_KEY_HERE", // 如果已设置 BRAVE_API_KEY 则可选
+        maxResults: 5,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+      },
+    },
+  },
+}
+```
+
+### 工具参数
+
+- `query`（必填）
+- `count`（1–10；默认从配置获取）
+- `country`（可选）：用于区域特定结果的 2 字母国家代码（例如 "DE"、"US"、"ALL"）。省略时，Brave 使用其默认区域。
+- `search_lang`（可选）：搜索结果的 ISO 语言代码（例如 "de"、"en"、"fr"）
+- `ui_lang`（可选）：UI 元素的 ISO 语言代码
+- `freshness`（可选，仅限 Brave）：按发现时间过滤（`pd`、`pw`、`pm`、`py` 或 `YYYY-MM-DDtoYYYY-MM-DD`）
+
+**示例：**
+
+```javascript
+// 德语特定搜索
+await web_search({
+  query: "TV online schauen",
+  count: 10,
+  country: "DE",
+  search_lang: "de",
+});
+
+// 法语搜索，使用法语 UI
+await web_search({
+  query: "actualités",
+  country: "FR",
+  search_lang: "fr",
+  ui_lang: "fr",
+});
+
+// 最近的结果（过去一周）
+await web_search({
+  query: "TMBG interview",
+  freshness: "pw",
+});
+```
+
+## web_fetch
+
+抓取 URL 并提取可读内容。
+
+### 前提条件
+
+- `tools.web.fetch.enabled` 不能为 `false`（默认：启用）
+- 可选的 Firecrawl 回退：设置 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY`。
+
+### 配置
+
+```json5
+{
+  tools: {
+    web: {
+      fetch: {
+        enabled: true,
+        maxChars: 50000,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+        maxRedirects: 3,
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+        readability: true,
+        firecrawl: {
+          enabled: true,
+          apiKey: "FIRECRAWL_API_KEY_HERE", // 如果已设置 FIRECRAWL_API_KEY 则可选
+          baseUrl: "https://api.firecrawl.dev",
+          onlyMainContent: true,
+          maxAgeMs: 86400000, // 毫秒（1 天）
+          timeoutSeconds: 60,
+        },
+      },
+    },
+  },
+}
+```
+
+### 工具参数
+
+- `url`（必填，仅限 http/https）
+- `extractMode`（`markdown` | `text`）
+- `maxChars`（截断过长的页面）
+
+说明：
+
+- `web_fetch` 首先使用 Readability（主要内容提取），然后使用 Firecrawl（如果已配置）。如果两者都失败，工具返回错误。
+- Firecrawl 请求使用反机器人检测模式，并默认缓存结果。
+- `web_fetch` 默认发送类 Chrome 的 User-Agent 和 `Accept-Language`；如需覆盖请修改 `userAgent`。
+- `web_fetch` 会阻止私有/内部主机名，并重新检查重定向（通过 `maxRedirects` 限制）。
+- `web_fetch` 是尽力提取；某些网站需要使用浏览器工具。
+- 有关密钥设置和服务详情，请参阅 [Firecrawl](/tools/firecrawl)。
+- 响应会被缓存（默认 15 分钟）以减少重复抓取。
+- 如果你使用工具配置文件/允许列表，请添加 `web_search`/`web_fetch` 或 `group:web`。
+- 如果缺少 Brave 密钥，`web_search` 会返回一个简短的设置提示及文档链接。