@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/tools/chrome-extension.md

@@ -0,0 +1,185 @@
+---
+read_when:
+  - 你想让智能体控制现有的 Chrome 标签页（工具栏按钮）
+  - 你需要通过 Tailscale 实现远程 Gateway网关 + 本地浏览器自动化
+  - 你想了解浏览器接管的安全影响
+summary: Chrome 扩展：让 OpenClaw 控制你现有的 Chrome 标签页
+title: Chrome 扩展
+x-i18n:
+  generated_at: "2026-02-01T21:40:11Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3b77bdad7d3dab6adb76ff25b144412d6b54b915993b1c1f057f36dea149938b
+  source_path: tools/chrome-extension.md
+  workflow: 15
+---
+
+# Chrome 扩展（浏览器中继）
+
+OpenClaw Chrome 扩展让智能体控制你**现有的 Chrome 标签页**（你日常使用的 Chrome 窗口），而不是启动一个单独的 OpenClaw 托管 Chrome 配置文件。
+
+附加/分离通过**单个 Chrome 工具栏按钮**完成。
+
+## 概念说明
+
+包含三个部分：
+
+- **浏览器控制服务**（Gateway网关或节点）：智能体/工具调用的 API（通过 Gateway网关）
+- **本地中继服务器**（local loopback CDP）：在控制服务和扩展之间建立桥接（默认 `http://127.0.0.1:18792`）
+- **Chrome MV3 扩展**：使用 `chrome.debugger` 附加到活动标签页，并将 CDP 消息传递给中继
+
+OpenClaw 随后通过常规的 `browser` 工具界面（选择正确的配置文件）控制附加的标签页。
+
+## 安装/加载（未打包）
+
+1. 将扩展安装到稳定的本地路径：
+
+```bash
+openclaw browser extension install
+```
+
+2. 打印已安装扩展的目录路径：
+
+```bash
+openclaw browser extension path
+```
+
+3. Chrome → `chrome://extensions`
+
+- 启用"开发者模式"
+- "加载已解压的扩展程序" → 选择上面打印的目录
+
+4. 固定该扩展。
+
+## 更新（无需构建步骤）
+
+扩展作为静态文件包含在 OpenClaw 发行版（npm 包）中。没有单独的"构建"步骤。
+
+升级 OpenClaw 后：
+
+- 重新运行 `openclaw browser extension install` 以刷新 OpenClaw 状态目录下的已安装文件。
+- Chrome → `chrome://extensions` → 点击扩展上的"重新加载"。
+
+## 使用方法（无需额外配置）
+
+OpenClaw 内置了一个名为 `chrome` 的浏览器配置文件，指向默认端口上的扩展中继。
+
+使用方式：
+
+- CLI：`openclaw browser --browser-profile chrome tabs`
+- 智能体工具：`browser`，设置 `profile="chrome"`
+
+如果你需要不同的名称或不同的中继端口，可以创建自己的配置文件：
+
+```bash
+openclaw browser create-profile \
+  --name my-chrome \
+  --driver extension \
+  --cdp-url http://127.0.0.1:18792 \
+  --color "#00AA00"
+```
+
+## 附加/分离（工具栏按钮）
+
+- 打开你想让 OpenClaw 控制的标签页。
+- 点击扩展图标。
+  - 徽章显示 `ON` 表示已附加。
+- 再次点击即可分离。
+
+## 它控制哪个标签页？
+
+- 它**不会**自动控制"你当前正在查看的标签页"。
+- 它**只控制你通过点击工具栏按钮明确附加的标签页**。
+- 要切换：打开另一个标签页并在那里点击扩展图标。
+
+## 徽章 + 常见错误
+
+- `ON`：已附加；OpenClaw 可以控制该标签页。
+- `…`：正在连接本地中继。
+- `!`：中继不可达（最常见原因：浏览器中继服务器未在本机运行）。
+
+如果你看到 `!`：
+
+- 确保 Gateway网关在本地运行（默认设置），或者如果 Gateway网关在其他地方运行，请在本机运行一个节点主机。
+- 打开扩展选项页面；它会显示中继是否可达。
+
+## 远程 Gateway网关（使用节点主机）
+
+### 本地 Gateway网关（与 Chrome 在同一台机器上）——通常**无需额外步骤**
+
+如果 Gateway网关与 Chrome 在同一台机器上运行，它会在 local loopback 上启动浏览器控制服务
+并自动启动中继服务器。扩展与本地中继通信；CLI/工具调用发送到 Gateway网关。
+
+### 远程 Gateway网关（Gateway网关在其他机器上运行）——**运行一个节点主机**
+
+如果你的 Gateway网关在另一台机器上运行，请在运行 Chrome 的机器上启动一个节点主机。
+Gateway网关会将浏览器操作代理到该节点；扩展 + 中继保持在浏览器所在机器的本地。
+
+如果连接了多个节点，使用 `gateway.nodes.browser.node` 固定一个节点，或设置 `gateway.nodes.browser.mode`。
+
+## 沙箱隔离（工具容器）
+
+如果你的智能体会话是沙箱隔离的（`agents.defaults.sandbox.mode != "off"`），`browser` 工具可能会受到限制：
+
+- 默认情况下，沙箱隔离会话通常指向**沙箱浏览器**（`target="sandbox"`），而非你的宿主机 Chrome。
+- Chrome 扩展中继接管需要控制**宿主机**的浏览器控制服务。
+
+选项：
+
+- 最简单：从**非沙箱隔离**的会话/智能体使用扩展。
+- 或允许沙箱隔离会话控制宿主机浏览器：
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+然后确保工具未被工具策略拒绝，并（如有需要）使用 `target="host"` 调用 `browser`。
+
+调试：`openclaw sandbox explain`
+
+## 远程访问提示
+
+- 将 Gateway网关和节点主机保持在同一个 tailnet 上；避免将中继端口暴露到局域网或公网。
+- 有意识地配对节点；如果你不需要远程控制，请禁用浏览器代理路由（`gateway.nodes.browser.mode="off"`）。
+
+## "extension path" 的工作原理
+
+`openclaw browser extension path` 打印包含扩展文件的**已安装**磁盘目录。
+
+CLI 故意**不会**打印 `node_modules` 路径。请始终先运行 `openclaw browser extension install`，将扩展复制到 OpenClaw 状态目录下的稳定位置。
+
+如果你移动或删除了安装目录，Chrome 会将扩展标记为损坏，直到你从有效路径重新加载。
+
+## 安全影响（请务必阅读）
+
+这是一个强大且有风险的功能。请将其视为给予模型"操控你浏览器的双手"。
+
+- 扩展使用 Chrome 的调试器 API（`chrome.debugger`）。附加后，模型可以：
+  - 在该标签页中点击/输入/导航
+  - 读取页面内容
+  - 访问该标签页已登录会话能访问的任何内容
+- **这不像**专用的 OpenClaw 托管配置文件那样是隔离的。
+  - 如果你附加到日常使用的配置文件/标签页，就等于授予了对该账户状态的访问权限。
+
+建议：
+
+- 优先使用专用的 Chrome 配置文件（与个人浏览分开）进行扩展中继使用。
+- 将 Gateway网关和所有节点主机保持在仅限 tailnet 的环境中；依赖 Gateway网关认证 + 节点配对。
+- 避免在局域网（`0.0.0.0`）上暴露中继端口，也避免使用 Funnel（公网）。
+- 中继会阻止非扩展来源，并要求 CDP 客户端提供内部认证令牌。
+
+相关内容：
+
+- 浏览器工具概述：[浏览器](/tools/browser)
+- 安全审计：[安全](/gateway/security)
+- Tailscale 设置：[Tailscale](/gateway/tailscale)

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

@@ -0,0 +1,209 @@
+---
+read_when:
+  - 向新用户介绍 ClawHub
+  - 安装、搜索或发布 Skills
+  - 说明 ClawHub CLI 标志和同步行为
+summary: ClawHub 指南：公共 Skills 注册中心 + CLI 工作流
+title: ClawHub
+x-i18n:
+  generated_at: "2026-02-01T21:42:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8b7f8fab80a34e409f37fa130a49ff5b487966755a7b0d214dfebf5207c7124c
+  source_path: tools/clawhub.md
+  workflow: 15
+---
+
+# ClawHub
+
+ClawHub 是 **OpenClaw 的公共 Skills 注册中心**。它是一项免费服务：所有 Skills 都是公开的、开放的，所有人都可以查看、共享和复用。Skills 就是一个包含 `SKILL.md` 文件（以及辅助文本文件）的文件夹。你可以在网页应用中浏览 Skills，也可以使用 CLI 来搜索、安装、更新和发布 Skills。
+
+网站：[clawhub.com](https://clawhub.com)
+
+## 适用人群（新手友好）
+
+如果你想为 OpenClaw 智能体添加新功能，ClawHub 是查找和安装 Skills 的最简单方式。你不需要了解后端的工作原理。你可以：
+
+- 使用自然语言搜索 Skills。
+- 将 Skills 安装到你的工作区。
+- 之后使用一条命令更新 Skills。
+- 通过发布 Skills 来备份你自己的 Skills。
+
+## 快速入门（非技术人员）
+
+1. 安装 CLI（参见下一节）。
+2. 搜索你需要的内容：
+   - `clawhub search "calendar"`
+3. 安装一个 Skills：
+   - `clawhub install <skill-slug>`
+4. 启动一个新的 OpenClaw 会话，以加载新 Skills。
+
+## 安装 CLI
+
+任选其一：
+
+```bash
+npm i -g clawhub
+```
+
+```bash
+pnpm add -g clawhub
+```
+
+## 在 OpenClaw 中的定位
+
+默认情况下，CLI 会将 Skills 安装到当前工作目录下的 `./skills`。如果已配置 OpenClaw 工作区，`clawhub` 会回退到该工作区，除非你通过 `--workdir`（或 `CLAWHUB_WORKDIR`）进行覆盖。OpenClaw 从 `<workspace>/skills` 加载工作区 Skills，并会在**下一个**会话中生效。如果你已经在使用 `~/.openclaw/skills` 或内置 Skills，工作区 Skills 优先级更高。
+
+有关 Skills 加载、共享和权限控制的更多详情，请参阅
+[Skills](/tools/skills)。
+
+## 服务功能
+
+- **公开浏览**Skills 及其 `SKILL.md` 内容。
+- 基于嵌入向量（向量搜索）的**搜索**，而不仅仅是关键词匹配。
+- 支持语义化版本号、变更日志和标签（包括 `latest`）的**版本管理**。
+- 每个版本以 zip 格式**下载**。
+- **星标和评论**，支持社区反馈。
+- **审核**钩子，用于审批和审计。
+- **CLI 友好的 API**，支持自动化和脚本编写。
+
+## CLI 命令和参数
+
+全局选项（适用于所有命令）：
+
+- `--workdir <dir>`：工作目录（默认：当前目录；回退到 OpenClaw 工作区）。
+- `--dir <dir>`：Skills 目录，相对于工作目录（默认：`skills`）。
+- `--site <url>`：网站基础 URL（浏览器登录）。
+- `--registry <url>`：注册中心 API 基础 URL。
+- `--no-input`：禁用提示（非交互模式）。
+- `-V, --cli-version`：打印 CLI 版本。
+
+认证：
+
+- `clawhub login`（浏览器流程）或 `clawhub login --token <token>`
+- `clawhub logout`
+- `clawhub whoami`
+
+选项：
+
+- `--token <token>`：粘贴 API 令牌。
+- `--label <label>`：为浏览器登录令牌存储的标签（默认：`CLI token`）。
+- `--no-browser`：不打开浏览器（需要 `--token`）。
+
+搜索：
+
+- `clawhub search "query"`
+- `--limit <n>`：最大结果数。
+
+安装：
+
+- `clawhub install <slug>`
+- `--version <version>`：安装指定版本。
+- `--force`：如果文件夹已存在则覆盖。
+
+更新：
+
+- `clawhub update <slug>`
+- `clawhub update --all`
+- `--version <version>`：更新到指定版本（仅限单个 slug）。
+- `--force`：当本地文件与任何已发布版本不匹配时强制覆盖。
+
+列表：
+
+- `clawhub list`（读取 `.clawhub/lock.json`）
+
+发布：
+
+- `clawhub publish <path>`
+- `--slug <slug>`：Skills 标识符。
+- `--name <name>`：显示名称。
+- `--version <version>`：语义化版本号。
+- `--changelog <text>`：变更日志文本（可以为空）。
+- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
+
+删除/恢复（仅所有者/管理员）：
+
+- `clawhub delete <slug> --yes`
+- `clawhub undelete <slug> --yes`
+
+同步（扫描本地 Skills + 发布新增/更新的 Skills）：
+
+- `clawhub sync`
+- `--root <dir...>`：额外的扫描根目录。
+- `--all`：无提示上传所有内容。
+- `--dry-run`：显示将要上传的内容。
+- `--bump <type>`：更新的版本号递增类型 `patch|minor|major`（默认：`patch`）。
+- `--changelog <text>`：非交互更新的变更日志。
+- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
+- `--concurrency <n>`：注册中心检查并发数（默认：4）。
+
+## 智能体常用工作流
+
+### 搜索 Skills
+
+```bash
+clawhub search "postgres backups"
+```
+
+### 下载新 Skills
+
+```bash
+clawhub install my-skill-pack
+```
+
+### 更新已安装的 Skills
+
+```bash
+clawhub update --all
+```
+
+### 备份你的 Skills（发布或同步）
+
+对于单个 Skills 文件夹：
+
+```bash
+clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
+```
+
+一次扫描并备份多个 Skills：
+
+```bash
+clawhub sync --all
+```
+
+## 高级详情（技术性）
+
+### 版本管理和标签
+
+- 每次发布都会创建一个新的**语义化版本** `SkillVersion`。
+- 标签（如 `latest`）指向某个版本；移动标签可以实现回滚。
+- 变更日志附加在每个版本上，在同步或发布更新时可以为空。
+
+### 本地更改与注册中心版本
+
+更新时会使用内容哈希将本地 Skills 内容与注册中心版本进行比较。如果本地文件与任何已发布版本不匹配，CLI 会在覆盖前询问确认（或在非交互模式下需要 `--force`）。
+
+### 同步扫描和回退根目录
+
+`clawhub sync` 首先扫描当前工作目录。如果未找到 Skills，它会回退到已知的旧版位置（例如 `~/openclaw/skills` 和 `~/.openclaw/skills`）。这样设计是为了在不需要额外标志的情况下找到旧版 Skills 安装。
+
+### 存储和锁文件
+
+- 已安装的 Skills 记录在工作目录下的 `.clawhub/lock.json` 中。
+- 认证令牌存储在 ClawHub CLI 配置文件中（可通过 `CLAWHUB_CONFIG_PATH` 覆盖）。
+
+### 遥测（安装计数）
+
+当你在登录状态下运行 `clawhub sync` 时，CLI 会发送一个最小快照用于计算安装次数。你可以完全禁用此功能：
+
+```bash
+export CLAWHUB_DISABLE_TELEMETRY=1
+```
+
+## 环境变量
+
+- `CLAWHUB_SITE`：覆盖网站 URL。
+- `CLAWHUB_REGISTRY`：覆盖注册中心 API URL。
+- `CLAWHUB_CONFIG_PATH`：覆盖 CLI 存储令牌/配置的位置。
+- `CLAWHUB_WORKDIR`：覆盖默认工作目录。
+- `CLAWHUB_DISABLE_TELEMETRY=1`：禁用 `sync` 的遥测功能。

package/docs/zh-CN/tools/creating-skills.md

@@ -0,0 +1,61 @@
+---
+title: 创建 Skills
+x-i18n:
+  generated_at: "2026-02-01T21:42:12Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ad801da34fe361ffa584ded47f775d1c104a471a3f7b7f930652255e98945c3a
+  source_path: tools/creating-skills.md
+  workflow: 15
+---
+
+# 创建自定义 Skills 🛠
+
+OpenClaw 的设计易于扩展。"Skills"是为你的助手添加新功能的主要方式。
+
+## 什么是 Skills？
+
+Skills 是一个包含 `SKILL.md` 文件（为 LLM 提供指令和工具定义）的目录，还可以选择性地包含一些脚本或资源。
+
+## 分步指南：你的第一个 Skills
+
+### 1. 创建目录
+
+Skills 存放在你的工作区中，通常位于 `~/.openclaw/workspace/skills/`。为你的 Skills 创建一个新文件夹：
+
+```bash
+mkdir -p ~/.openclaw/workspace/skills/hello-world
+```
+
+### 2. 定义 `SKILL.md`
+
+在该目录中创建一个 `SKILL.md` 文件。该文件使用 YAML frontmatter 存放元数据，使用 Markdown 编写指令。
+
+```markdown
+---
+name: hello_world
+description: A simple skill that says hello.
+---
+
+# Hello World Skill
+
+When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
+```
+
+### 3. 添加工具（可选）
+
+你可以在 frontmatter 中定义自定义工具，或指示智能体使用现有的系统工具（如 `bash` 或 `browser`）。
+
+### 4. 刷新 OpenClaw
+
+让你的智能体"刷新 Skills"或重启 Gateway网关。OpenClaw 将发现新目录并索引 `SKILL.md`。
+
+## 最佳实践
+
+- **保持简洁**：指示模型应该做*什么*，而不是如何成为一个 AI。
+- **安全第一**：如果你的 Skills 使用 `bash`，请确保提示不会允许来自不受信任用户输入的任意命令注入。
+- **本地测试**：使用 `openclaw agent --message "use my new skill"` 进行测试。
+
+## 共享 Skills
+
+你还可以在 [ClawHub](https://clawhub.com) 上浏览和贡献 Skills。

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

@@ -0,0 +1,64 @@
+---
+read_when:
+  - 调整提升模式的默认设置、允许列表或斜杠命令行为
+summary: 提升执行模式与 /elevated 指令
+title: 提升模式
+x-i18n:
+  generated_at: "2026-02-01T21:42:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 83767a01609304026d145feb0aa0b0533e8cf8b16cd200f724d9e3e8cf2920c3
+  source_path: tools/elevated.md
+  workflow: 15
+---
+
+# 提升模式（/elevated 指令）
+
+## 功能说明
+
+- `/elevated on` 在 Gateway网关主机上运行并保留 exec 审批（与 `/elevated ask` 相同）。
+- `/elevated full` 在 Gateway网关主机上运行**并且**自动批准 exec（跳过 exec 审批）。
+- `/elevated ask` 在 Gateway网关主机上运行但保留 exec 审批（与 `/elevated on` 相同）。
+- `on`/`ask` **不会**强制设置 `exec.security=full`；已配置的安全/审批策略仍然适用。
+- 仅在智能体处于**沙箱环境**时改变行为（否则 exec 已经在主机上运行）。
+- 指令形式：`/elevated on|off|ask|full`、`/elev on|off|ask|full`。
+- 仅接受 `on|off|ask|full`；其他任何输入将返回提示且不改变状态。
+
+## 控制范围（以及不控制的部分）
+
+- **可用性门控**：`tools.elevated` 是全局基线。`agents.list[].tools.elevated` 可以进一步限制每个智能体的提升权限（两者都必须允许）。
+- **每会话状态**：`/elevated on|off|ask|full` 为当前会话密钥设置提升级别。
+- **内联指令**：消息中的 `/elevated on|ask|full` 仅对该条消息生效。
+- **群组**：在群聊中，仅当智能体被提及时才响应提升指令。绕过提及要求的纯命令消息视为已提及。
+- **主机执行**：提升模式将 `exec` 强制在 Gateway网关主机上执行；`full` 还会设置 `security=full`。
+- **审批**：`full` 跳过 exec 审批；`on`/`ask` 在允许列表/审批规则要求时遵守审批流程。
+- **非沙箱智能体**：对执行位置无影响；仅影响门控、日志和状态。
+- **工具策略仍然适用**：如果 `exec` 被工具策略拒绝，则无法使用提升模式。
+- **与 `/exec` 分离**：`/exec` 为授权发送者调整每会话默认值，不需要提升模式。
+
+## 解析顺序
+
+1. 消息上的内联指令（仅对该条消息生效）。
+2. 会话覆盖（通过发送仅包含指令的消息来设置）。
+3. 全局默认值（配置中的 `agents.defaults.elevatedDefault`）。
+
+## 设置会话默认值
+
+- 发送一条**仅包含**指令的消息（允许空白字符），例如 `/elevated full`。
+- 将发送确认回复（`Elevated mode set to full...` / `Elevated mode disabled.`）。
+- 如果提升访问被禁用或发送者不在已批准的允许列表中，指令将回复可操作的错误信息且不改变会话状态。
+- 发送 `/elevated`（或 `/elevated:`）且不带参数可查看当前提升级别。
+
+## 可用性 + 允许列表
+
+- 功能门控：`tools.elevated.enabled`（即使代码支持，默认可通过配置关闭）。
+- 发送者允许列表：`tools.elevated.allowFrom`，按提供商设置允许列表（例如 `discord`、`whatsapp`）。
+- 每智能体门控：`agents.list[].tools.elevated.enabled`（可选；只能进一步限制）。
+- 每智能体允许列表：`agents.list[].tools.elevated.allowFrom`（可选；设置后，发送者必须同时匹配全局和每智能体的允许列表）。
+- Discord 回退：如果省略 `tools.elevated.allowFrom.discord`，则使用 `channels.discord.dm.allowFrom` 列表作为回退。设置 `tools.elevated.allowFrom.discord`（即使为 `[]`）可覆盖此行为。每智能体允许列表**不**使用回退。
+- 所有门控必须通过；否则提升模式视为不可用。
+
+## 日志 + 状态
+
+- 提升模式的 exec 调用以 info 级别记录日志。
+- 会话状态包含提升模式信息（例如 `elevated=ask`、`elevated=full`）。