@gguf/claw 2026.2.1 → 2026.2.2

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

@@ -0,0 +1,284 @@
+---
+read_when:
+  - 添加或修改 Skills
+  - 更改 Skills 门控或加载规则
+summary: Skills：托管型与工作区型、门控规则，以及配置/环境变量连接
+title: Skills
+x-i18n:
+  generated_at: "2026-02-01T21:43:46Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 54685da5885600b367ccdad6342497199fcb168ce33f8cdc00391d993f3bab7e
+  source_path: tools/skills.md
+  workflow: 15
+---
+
+# Skills（OpenClaw）
+
+OpenClaw 使用与 **[AgentSkills](https://agentskills.io) 兼容**的 Skills 文件夹来教智能体如何使用工具。每个 Skills 是一个目录，包含带有 YAML frontmatter 和说明的 `SKILL.md` 文件。OpenClaw 加载**内置 Skills**以及可选的本地覆盖，并在加载时根据环境、配置和二进制文件是否存在进行过滤。
+
+## 位置和优先级
+
+Skills 从**三个**位置加载：
+
+1. **内置 Skills**：随安装包一起分发（npm 包或 OpenClaw.app）
+2. **托管/本地 Skills**：`~/.openclaw/skills`
+3. **工作区 Skills**：`<workspace>/skills`
+
+如果 Skills 名称冲突，优先级为：
+
+`<workspace>/skills`（最高）→ `~/.openclaw/skills` → 内置 Skills（最低）
+
+此外，你可以通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 配置额外的 Skills 文件夹（最低优先级）。
+
+## 按智能体与共享 Skills
+
+在**多智能体**设置中，每个智能体拥有自己的工作区。这意味着：
+
+- **按智能体 Skills**位于该智能体专属的 `<workspace>/skills` 中。
+- **共享 Skills**位于 `~/.openclaw/skills`（托管/本地），对同一机器上的**所有智能体**可见。
+- **共享文件夹**也可以通过 `skills.load.extraDirs`（最低优先级）添加，如果你希望多个智能体使用同一套 Skills 包。
+
+如果同一 Skills 名称存在于多个位置，适用通常的优先级规则：工作区优先，然后是托管/本地，最后是内置。
+
+## 插件 + Skills
+
+插件可以通过在 `openclaw.plugin.json` 中列出 `skills` 目录（相对于插件根目录的路径）来附带自己的 Skills。插件 Skills 在插件启用时加载，并参与正常的 Skills 优先级规则。你可以通过插件配置项上的 `metadata.openclaw.requires.config` 进行门控。参见[插件](/plugin)了解发现/配置，参见[工具](/tools)了解这些 Skills 教授的工具功能。
+
+## ClawHub（安装 + 同步）
+
+ClawHub 是 OpenClaw 的公共 Skills 注册中心。浏览地址：[clawhub.com](https://clawhub.com)。使用它来发现、安装、更新和备份 Skills。完整指南：[ClawHub](/tools/clawhub)。
+
+常用流程：
+
+- 将 Skills 安装到你的工作区：
+  - `clawhub install <skill-slug>`
+- 更新所有已安装的 Skills：
+  - `clawhub update --all`
+- 同步（扫描 + 发布更新）：
+  - `clawhub sync --all`
+
+默认情况下，`clawhub` 安装到当前工作目录下的 `./skills`（或回退到已配置的 OpenClaw 工作区）。OpenClaw 在下次会话时将其作为 `<workspace>/skills` 加载。
+
+## 安全说明
+
+- 将第三方 Skills 视为**不可信代码**。启用前请先阅读其内容。
+- 对于不可信输入和高风险工具，优先使用沙箱运行。参见[沙箱](/gateway/sandboxing)。
+- `skills.entries.*.env` 和 `skills.entries.*.apiKey` 会将密钥注入该智能体轮次的**宿主**进程中（而非沙箱）。请勿将密钥暴露在提示词和日志中。
+- 更广泛的威胁模型和检查清单，请参见[安全](/gateway/security)。
+
+## 格式（AgentSkills + Pi 兼容）
+
+`SKILL.md` 必须至少包含：
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+---
+```
+
+说明：
+
+- 我们遵循 AgentSkills 规范的布局/意图。
+- 内嵌智能体使用的解析器仅支持**单行** frontmatter 键。
+- `metadata` 应为**单行 JSON 对象**。
+- 在说明中使用 `{baseDir}` 引用 Skills 文件夹路径。
+- 可选的 frontmatter 键：
+  - `homepage` — 在 macOS Skills UI 中显示为"网站"的 URL（也支持通过 `metadata.openclaw.homepage` 设置）。
+  - `user-invocable` — `true|false`（默认：`true`）。为 `true` 时，Skills 作为用户斜杠命令暴露。
+  - `disable-model-invocation` — `true|false`（默认：`false`）。为 `true` 时，Skills 从模型提示词中排除（仍可通过用户调用使用）。
+  - `command-dispatch` — `tool`（可选）。设为 `tool` 时，斜杠命令绕过模型直接分派到工具。
+  - `command-tool` — 当设置了 `command-dispatch: tool` 时要调用的工具名称。
+  - `command-arg-mode` — `raw`（默认）。用于工具分派时，将原始参数字符串转发给工具（不进行核心解析）。
+
+    工具调用参数为：
+    `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`。
+
+## 门控（加载时过滤）
+
+OpenClaw 使用 `metadata`（单行 JSON）**在加载时过滤 Skills**：
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+metadata:
+  {
+    "openclaw":
+      {
+        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
+        "primaryEnv": "GEMINI_API_KEY",
+      },
+  }
+---
+```
+
+`metadata.openclaw` 下的字段：
+
+- `always: true` — 始终包含该 Skills（跳过其他门控）。
+- `emoji` — macOS Skills UI 使用的可选表情符号。
+- `homepage` — macOS Skills UI 中显示为"网站"的可选 URL。
+- `os` — 可选的平台列表（`darwin`、`linux`、`win32`）。如果设置，Skills 仅在这些操作系统上可用。
+- `requires.bins` — 列表；每个都必须存在于 `PATH` 中。
+- `requires.anyBins` — 列表；至少一个必须存在于 `PATH` 中。
+- `requires.env` — 列表；环境变量必须存在**或**在配置中提供。
+- `requires.config` — `openclaw.json` 路径列表，必须为真值。
+- `primaryEnv` — 与 `skills.entries.<name>.apiKey` 关联的环境变量名。
+- `install` — macOS Skills UI 使用的可选安装器规格数组（brew/node/go/uv/download）。
+
+关于沙箱的说明：
+
+- `requires.bins` 在 Skills 加载时在**宿主**上检查。
+- 如果智能体在沙箱中运行，二进制文件也必须存在于**容器内部**。
+  通过 `agents.defaults.sandbox.docker.setupCommand`（或自定义镜像）安装它。
+  `setupCommand` 在容器创建后运行一次。
+  包安装还需要网络出站权限、可写的根文件系统以及沙箱中的 root 用户。
+  示例：`summarize` Skills（`skills/summarize/SKILL.md`）需要 `summarize` CLI 存在于沙箱容器中才能在其中运行。
+
+安装器示例：
+
+```markdown
+---
+name: gemini
+description: Use Gemini CLI for coding assistance and Google search lookups.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "♊️",
+        "requires": { "bins": ["gemini"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI (brew)",
+            },
+          ],
+      },
+  }
+---
+```
+
+说明：
+
+- 如果列出了多个安装器，Gateway网关会选择**单个**首选选项（有 brew 时选 brew，否则选 node）。
+- 如果所有安装器都是 `download`，OpenClaw 会列出每个条目，以便你查看可用的产物。
+- 安装器规格可包含 `os: ["darwin"|"linux"|"win32"]` 以按平台过滤选项。
+- Node 安装遵循 `openclaw.json` 中的 `skills.install.nodeManager`（默认：npm；选项：npm/pnpm/yarn/bun）。
+  这仅影响**Skills 安装**；Gateway网关运行时仍应使用 Node（不建议将 Bun 用于 WhatsApp/Telegram）。
+- Go 安装：如果缺少 `go` 但有 `brew`，Gateway网关会先通过 Homebrew 安装 Go，并尽可能将 `GOBIN` 设置为 Homebrew 的 `bin`。
+- Download 安装：`url`（必需）、`archive`（`tar.gz` | `tar.bz2` | `zip`）、`extract`（默认：检测到归档时自动）、`stripComponents`、`targetDir`（默认：`~/.openclaw/tools/<skillKey>`）。
+
+如果没有 `metadata.openclaw`，Skills 始终可用（除非在配置中禁用，或被 `skills.allowBundled` 对内置 Skills 进行了限制）。
+
+## 配置覆盖（`~/.openclaw/openclaw.json`）
+
+内置/托管 Skills 可以切换启用状态并提供环境变量值：
+
+```json5
+{
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE",
+        },
+        config: {
+          endpoint: "https://example.invalid",
+          model: "nano-pro",
+        },
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false },
+    },
+  },
+}
+```
+
+注意：如果 Skills 名称包含连字符，请给键加引号（JSON5 允许带引号的键）。
+
+配置键默认匹配**Skills 名称**。如果 Skills 定义了 `metadata.openclaw.skillKey`，请在 `skills.entries` 下使用该键。
+
+规则：
+
+- `enabled: false` 禁用 Skills，即使它是内置/已安装的。
+- `env`：仅在进程中该变量**尚未设置**时注入。
+- `apiKey`：为声明了 `metadata.openclaw.primaryEnv` 的 Skills 提供的便捷方式。
+- `config`：用于自定义按 Skills 字段的可选容器；自定义键必须放在此处。
+- `allowBundled`：仅针对**内置**Skills 的可选允许列表。如果设置，只有列表中的内置 Skills 才可用（托管/工作区 Skills 不受影响）。
+
+## 环境注入（按智能体运行）
+
+当智能体运行开始时，OpenClaw：
+
+1. 读取 Skills 元数据。
+2. 将 `skills.entries.<key>.env` 或 `skills.entries.<key>.apiKey` 应用到 `process.env`。
+3. 使用**符合条件**的 Skills 构建系统提示词。
+4. 运行结束后恢复原始环境。
+
+这是**限定在智能体运行范围内**的，而非全局 shell 环境。
+
+## 会话快照（性能）
+
+OpenClaw 在**会话开始时**对符合条件的 Skills 进行快照，并在同一会话的后续轮次中复用该列表。对 Skills 或配置的更改在下一个新会话中生效。
+
+Skills 也可以在会话中途刷新，当 Skills 监视器启用时或当新的符合条件的远程节点出现时（见下文）。可以将其理解为**热重载**：刷新后的列表会在下一个智能体轮次中被使用。
+
+## 远程 macOS 节点（Linux Gateway网关）
+
+如果 Gateway网关运行在 Linux 上，但有一个**macOS 节点**已连接且**允许 `system.run`**（执行审批安全级别未设为 `deny`），OpenClaw 可以在该节点上存在所需二进制文件时，将仅限 macOS 的 Skills 视为可用。智能体应通过 `nodes` 工具（通常是 `nodes.run`）执行这些 Skills。
+
+这依赖于节点报告其命令支持情况以及通过 `system.run` 进行的二进制探测。如果 macOS 节点之后离线，Skills 仍然可见；在节点重新连接之前，调用可能会失败。
+
+## Skills 监视器（自动刷新）
+
+默认情况下，OpenClaw 监视 Skills 文件夹，并在 `SKILL.md` 文件更改时更新 Skills 快照。在 `skills.load` 下配置：
+
+```json5
+{
+  skills: {
+    load: {
+      watch: true,
+      watchDebounceMs: 250,
+    },
+  },
+}
+```
+
+## Token 影响（Skills 列表）
+
+当有符合条件的 Skills 时，OpenClaw 会将一个紧凑的 XML 可用 Skills 列表注入系统提示词（通过 `pi-coding-agent` 中的 `formatSkillsForPrompt`）。开销是确定性的：
+
+- **基础开销（仅在有 ≥1 个 Skills 时）：**195 个字符。
+- **每个 Skills：**97 个字符 + XML 转义后的 `<name>`、`<description>` 和 `<location>` 值的长度。
+
+公式（字符数）：
+
+```
+total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
+```
+
+说明：
+
+- XML 转义会将 `& < > " '` 展开为实体（`&amp;`、`&lt;` 等），增加长度。
+- Token 数量因模型分词器而异。粗略的 OpenAI 风格估算约为 ~4 字符/token，因此**97 字符 ≈ 24 个 token**（每个 Skills），加上你实际的字段长度。
+
+## 托管 Skills 生命周期
+
+OpenClaw 将一组基线 Skills 作为**内置 Skills**随安装包（npm 包或 OpenClaw.app）一起分发。`~/.openclaw/skills` 用于本地覆盖（例如，在不更改内置副本的情况下固定/修补某个 Skills）。工作区 Skills 由用户拥有，在名称冲突时覆盖两者。
+
+## 配置参考
+
+参见[Skills配置](/tools/skills-config)了解全部配置模式。
+
+## 想要更多 Skills？
+
+浏览 https://clawhub.com。
+
+---

package/docs/zh-CN/tools/slash-commands.md

@@ -0,0 +1,205 @@
+---
+read_when:
+  - 使用或配置聊天命令
+  - 调试命令路由或权限问题
+summary: 斜杠命令：文本与原生命令、配置及支持的命令
+title: 斜杠命令
+x-i18n:
+  generated_at: "2026-02-01T21:43:36Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: ca0deebf89518e8c62828fbb9bf4621c5fff8ab86ccb22e37da61a28f9a7886a
+  source_path: tools/slash-commands.md
+  workflow: 15
+---
+
+# 斜杠命令
+
+命令由 Gateway网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
+仅限主机使用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 为别名）。
+
+有两个相关系统：
+
+- **命令**：独立的 `/...` 消息。
+- **指令**：`/think`、`/verbose`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
+  - 指令在模型看到消息之前会被移除。
+  - 在普通聊天消息（非纯指令消息）中，它们被视为"内联提示"，**不会**持久化会话设置。
+  - 在纯指令消息（消息仅包含指令）中，它们会持久化到会话并回复确认信息。
+  - 指令仅对**已授权的发送者**（渠道允许列表/配对加上 `commands.useAccessGroups`）生效。
+    未授权的发送者看到的指令会被当作纯文本处理。
+
+还有一些**内联快捷命令**（仅限已加入允许列表/已授权的发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
+它们会立即执行，在模型看到消息之前被移除，剩余文本继续通过正常流程处理。
+
+## 配置
+
+```json5
+{
+  commands: {
+    native: "auto",
+    nativeSkills: "auto",
+    text: true,
+    bash: false,
+    bashForegroundMs: 2000,
+    config: false,
+    debug: false,
+    restart: false,
+    useAccessGroups: true,
+  },
+}
+```
+
+- `commands.text`（默认 `true`）启用解析聊天消息中的 `/...`。
+  - 在没有原生命令支持的平台上（WhatsApp/WebChat/Signal/iMessage/Google Chat/MS Teams），即使将此项设为 `false`，文本命令仍然有效。
+- `commands.native`（默认 `"auto"`）注册原生命令。
+  - Auto：Discord/Telegram 启用；Slack 关闭（直到你添加斜杠命令）；不支持原生命令的提供商忽略此项。
+  - 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
+  - `false` 会在启动时清除 Discord/Telegram 上之前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
+- `commands.nativeSkills`（默认 `"auto"`）在支持的平台上将**Skills**命令注册为原生命令。
+  - Auto：Discord/Telegram 启用；Slack 关闭（Slack 需要为每个 Skills 创建一个斜杠命令）。
+  - 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
+- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 为别名；需要 `tools.elevated` 允许列表）。
+- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式之前等待的时长（`0` 表示立即后台执行）。
+- `commands.config`（默认 `false`）启用 `/config`（读写 `openclaw.json`）。
+- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
+- `commands.useAccessGroups`（默认 `true`）对命令强制执行允许列表/策略。
+
+## 命令列表
+
+文本 + 原生命令（启用时）：
+
+- `/help`
+- `/commands`
+- `/skill <name> [input]`（按名称运行 Skills）
+- `/status`（显示当前状态；在可用时包含当前模型提供商的用量/配额信息）
+- `/allowlist`（列出/添加/移除允许列表条目）
+- `/approve <id> allow-once|allow-always|deny`（处理执行审批提示）
+- `/context [list|detail|json]`（解释"上下文"；`detail` 显示每个文件 + 每个工具 + 每个 Skills + 系统提示的大小）
+- `/whoami`（显示你的发送者 ID；别名：`/id`）
+- `/subagents list|stop|log|info|send`（检查、停止、查看日志或向当前会话的子智能体运行发送消息）
+- `/config show|get|set|unset`（将配置持久化到磁盘，仅所有者可用；需要 `commands.config: true`）
+- `/debug show|set|unset|reset`（运行时覆盖，仅所有者可用；需要 `commands.debug: true`）
+- `/usage off|tokens|full|cost`（每次响应的用量页脚或本地费用摘要）
+- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio`（控制 TTS；参见 [/tts](/tts)）
+  - Discord：原生命令为 `/voice`（Discord 保留了 `/tts`）；文本命令 `/tts` 仍然有效。
+- `/stop`
+- `/restart`
+- `/dock-telegram`（别名：`/dock_telegram`）（将回复切换到 Telegram）
+- `/dock-discord`（别名：`/dock_discord`）（将回复切换到 Discord）
+- `/dock-slack`（别名：`/dock_slack`）（将回复切换到 Slack）
+- `/activation mention|always`（仅群组）
+- `/send on|off|inherit`（仅所有者）
+- `/reset` 或 `/new [model]`（可选模型提示；剩余内容直接传递）
+- `/think <off|minimal|low|medium|high|xhigh>`（按模型/提供商动态选择；别名：`/thinking`、`/t`）
+- `/verbose on|full|off`（别名：`/v`）
+- `/reasoning on|off|stream`（别名：`/reason`；开启时发送以 `Reasoning:` 为前缀的单独消息；`stream` = 仅限 Telegram 草稿）
+- `/elevated on|off|ask|full`（别名：`/elev`；`full` 跳过执行审批）
+- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`（发送 `/exec` 查看当前设置）
+- `/model <name>`（别名：`/models`；或来自 `agents.defaults.models.*.alias` 的 `/<alias>`）
+- `/queue <mode>`（加上选项如 `debounce:2s cap:25 drop:summarize`；发送 `/queue` 查看当前设置）
+- `/bash <command>`（仅限主机；`! <command>` 的别名；需要 `commands.bash: true` + `tools.elevated` 允许列表）
+
+仅文本命令：
+
+- `/compact [instructions]`（参见 [/concepts/compaction](/concepts/compaction)）
+- `! <command>`（仅限主机；一次一个；对长时间运行的任务使用 `!poll` + `!stop`）
+- `!poll`（检查输出/状态；接受可选的 `sessionId`；`/bash poll` 也可用）
+- `!stop`（停止正在运行的 bash 任务；接受可选的 `sessionId`；`/bash stop` 也可用）
+
+注意事项：
+
+- 命令在命令名和参数之间可以使用可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
+- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本将被视为消息正文。
+- 要查看完整的提供商用量明细，请使用 `openclaw status --usage`。
+- `/allowlist add|remove` 需要 `commands.config=true` 并遵循渠道的 `configWrites` 设置。
+- `/usage` 控制每次响应的用量页脚；`/usage cost` 从 OpenClaw 会话日志中打印本地费用摘要。
+- `/restart` 默认禁用；设置 `commands.restart: true` 以启用。
+- `/verbose` 用于调试和增强可见性；正常使用时请保持**关闭**。
+- `/reasoning`（和 `/verbose`）在群组场景中存在风险：它们可能暴露你不希望公开的内部推理或工具输出。建议保持关闭，尤其是在群聊中。
+- **快速路径：**来自已加入允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
+- **群组提及门控：**来自已加入允许列表发送者的纯命令消息会绕过提及要求。
+- **内联快捷命令（仅限已加入允许列表的发送者）：**某些命令也可以嵌入在普通消息中使用，在模型看到剩余文本之前会被移除。
+  - 示例：`hey /status` 会触发状态回复，剩余文本继续通过正常流程处理。
+- 目前支持：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
+- 未授权的纯命令消息会被静默忽略，内联的 `/...` 标记会被当作纯文本处理。
+- **Skills 命令：**`user-invocable` Skills 会作为斜杠命令暴露。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。
+  - `/skill <name> [input]` 按名称运行 Skills（在原生命令限制阻止创建逐 Skills 命令时很有用）。
+  - 默认情况下，Skills 命令会作为普通请求转发给模型。
+  - Skills 可以选择性地声明 `command-dispatch: tool` 将命令直接路由到工具（确定性执行，无需模型）。
+  - 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/prose)。
+- **原生命令参数：**Discord 使用自动补全来处理动态选项（省略必需参数时使用按钮菜单）。Telegram 和 Slack 在命令支持选项且省略参数时显示按钮菜单。
+
+## 用量显示界面（在哪里显示什么）
+
+- **提供商用量/配额**（示例："Claude 剩余 80%"）在启用用量跟踪时显示在 `/status` 中，针对当前模型提供商。
+- **每次响应的令牌数/费用**由 `/usage off|tokens|full` 控制（附加在普通回复后面）。
+- `/model status` 关于的是**模型/认证/端点**，而非用量。
+
+## 模型选择（`/model`）
+
+`/model` 作为指令实现。
+
+示例：
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model opus@anthropic:default
+/model status
+```
+
+注意事项：
+
+- `/model` 和 `/model list` 显示紧凑的编号选择器（模型系列 + 可用提供商）。
+- `/model <#>` 从该选择器中选择（尽可能优先使用当前提供商）。
+- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`）（如可用）。
+
+## 调试覆盖
+
+`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅所有者可用。默认禁用；通过 `commands.debug: true` 启用。
+
+示例：
+
+```
+/debug show
+/debug set messages.responsePrefix="[openclaw]"
+/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+注意事项：
+
+- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
+- 使用 `/debug reset` 清除所有覆盖并恢复到磁盘上的配置。
+
+## 配置更新
+
+`/config` 写入你的磁盘配置（`openclaw.json`）。仅所有者可用。默认禁用；通过 `commands.config: true` 启用。
+
+示例：
+
+```
+/config show
+/config show messages.responsePrefix
+/config get messages.responsePrefix
+/config set messages.responsePrefix="[openclaw]"
+/config unset messages.responsePrefix
+```
+
+注意事项：
+
+- 配置在写入前会进行验证；无效的更改会被拒绝。
+- `/config` 更新在重启后仍然保留。
+
+## 平台说明
+
+- **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。
+- **原生命令**使用隔离的会话：
+  - Discord：`agent:<agentId>:discord:slash:<userId>`
+  - Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
+  - Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位聊天会话）
+- **`/stop`** 定位活跃的聊天会话，以便中止当前运行。
+- **Slack：**仍然支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格的命令。如果你启用了 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式呈现。

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

@@ -0,0 +1,156 @@
+---
+read_when:
+  - 你希望通过智能体进行后台/并行工作
+  - 你正在修改 sessions_spawn 或子智能体工具策略
+summary: 子智能体：生成独立的智能体运行并将结果回报给请求者聊天
+title: 子智能体
+x-i18n:
+  generated_at: "2026-02-01T21:43:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0e88b4a52d2f0df3dc7c7de87af7ab86f73b81aed91c01e676aa0bd2512d7d21
+  source_path: tools/subagents.md
+  workflow: 15
+---
+
+# 子智能体
+
+子智能体是从现有智能体运行中生成的后台智能体运行。它们在自己的会话（`agent:<agentId>:subagent:<uuid>`）中运行，完成后会将结果**回报**到请求者的聊天渠道。
+
+## 斜杠命令
+
+使用 `/subagents` 检查或控制**当前会话**的子智能体运行：
+
+- `/subagents list`
+- `/subagents stop <id|#|all>`
+- `/subagents log <id|#> [limit] [tools]`
+- `/subagents info <id|#>`
+- `/subagents send <id|#> <message>`
+
+`/subagents info` 显示运行元数据（状态、时间戳、会话 ID、转录路径、清理方式）。
+
+主要目标：
+
+- 并行化"研究/长任务/慢工具"工作，不阻塞主运行。
+- 默认保持子智能体隔离（会话分离 + 可选沙箱）。
+- 保持工具表面难以被滥用：子智能体默认**不**获取会话工具。
+- 避免嵌套扇出：子智能体不能生成子智能体。
+
+费用提示：每个子智能体有其**独立的**上下文和 token 用量。对于繁重或重复的任务，建议为子智能体设置较便宜的模型，主智能体保持使用更高质量的模型。可通过 `agents.defaults.subagents.model` 或按智能体覆盖进行配置。
+
+## 工具
+
+使用 `sessions_spawn`：
+
+- 启动子智能体运行（`deliver: false`，全局队列：`subagent`）
+- 然后运行回报步骤，将回报回复发布到请求者的聊天渠道
+- 默认模型：继承调用者，除非你设置了 `agents.defaults.subagents.model`（或按智能体 `agents.list[].subagents.model`）；显式的 `sessions_spawn.model` 仍然优先。
+- 默认思考级别：继承调用者，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体 `agents.list[].subagents.thinking`）；显式的 `sessions_spawn.thinking` 仍然优先。
+
+工具参数：
+
+- `task`（必填）
+- `label?`（可选）
+- `agentId?`（可选；如果允许，在另一个智能体 ID 下生成）
+- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行并在工具结果中发出警告）
+- `thinking?`（可选；覆盖子智能体运行的思考级别）
+- `runTimeoutSeconds?`（默认 `0`；设置后，子智能体运行在 N 秒后中止）
+- `cleanup?`（`delete|keep`，默认 `keep`）
+
+允许列表：
+
+- `agents.list[].subagents.allowAgents`：可通过 `agentId` 指定的智能体 ID 列表（`["*"]` 允许任意）。默认：仅请求者智能体。
+
+发现：
+
+- 使用 `agents_list` 查看当前允许用于 `sessions_spawn` 的智能体 ID。
+
+自动归档：
+
+- 子智能体会话在 `agents.defaults.subagents.archiveAfterMinutes`（默认：60）后自动归档。
+- 归档使用 `sessions.delete` 并将转录重命名为 `*.deleted.<timestamp>`（同一文件夹）。
+- `cleanup: "delete"` 在回报后立即归档（仍通过重命名保留转录）。
+- 自动归档为尽力而为；如果 Gateway网关重启，待处理的定时器会丢失。
+- `runTimeoutSeconds` **不会**自动归档；它仅停止运行。会话保留直到自动归档。
+
+## 认证
+
+子智能体认证按**智能体 ID** 解析，而非按会话类型：
+
+- 子智能体会话键为 `agent:<agentId>:subagent:<uuid>`。
+- 认证存储从该智能体的 `agentDir` 加载。
+- 主智能体的认证配置文件作为**回退**合并；冲突时智能体配置文件覆盖主配置文件。
+
+注意：合并是叠加的，因此主配置文件始终作为回退可用。目前尚不支持按智能体完全隔离的认证。
+
+## 回报
+
+子智能体通过回报步骤汇报结果：
+
+- 回报步骤在子智能体会话内运行（而非请求者会话）。
+- 如果子智能体回复的内容恰好为 `ANNOUNCE_SKIP`，则不发布任何内容。
+- 否则，回报回复通过后续的 `agent` 调用（`deliver=true`）发布到请求者的聊天渠道。
+- 回报回复在可用时保留线程/话题路由（Slack 线程、Telegram 话题、Matrix 线程）。
+- 回报消息被规范化为稳定的模板：
+  - `Status:`：根据运行结果推导（`success`、`error`、`timeout` 或 `unknown`）。
+  - `Result:`：回报步骤的摘要内容（如缺失则为 `(not available)`）。
+  - `Notes:`：错误详情和其他有用的上下文。
+- `Status` 不从模型输出推断；它来自运行时结果信号。
+
+回报负载末尾包含统计行（即使被包装时也是如此）：
+
+- 运行时间（例如 `runtime 5m12s`）
+- Token 用量（输入/输出/总计）
+- 配置了模型定价时的预估费用（`models.providers.*.models[].cost`）
+- `sessionKey`、`sessionId` 和转录路径（以便主智能体可通过 `sessions_history` 获取历史记录或检查磁盘上的文件）
+
+## 工具策略（子智能体工具）
+
+默认情况下，子智能体获取**除会话工具外的所有工具**：
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+通过配置覆盖：
+
+```json5
+{
+  agents: {
+    defaults: {
+      subagents: {
+        maxConcurrent: 1,
+      },
+    },
+  },
+  tools: {
+    subagents: {
+      tools: {
+        // deny 优先
+        deny: ["gateway", "cron"],
+        // 如果设置了 allow，则变为仅允许模式（deny 仍然优先）
+        // allow: ["read", "exec", "process"]
+      },
+    },
+  },
+}
+```
+
+## 并发
+
+子智能体使用专用的进程内队列通道：
+
+- 通道名称：`subagent`
+- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`）
+
+## 停止
+
+- 在请求者聊天中发送 `/stop` 会中止请求者会话并停止从中生成的所有活跃子智能体运行。
+
+## 限制
+
+- 子智能体回报为**尽力而为**。如果 Gateway网关重启，待处理的"回报"工作会丢失。
+- 子智能体仍共享相同的 Gateway网关进程资源；将 `maxConcurrent` 视为安全阀。
+- `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。
+- 子智能体上下文仅注入 `AGENTS.md` + `TOOLS.md`（不包含 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。