@gguf/claw 2026.2.1 → 2026.2.3

package/docs/zh-CN/plugins/agent-tools.md

@@ -0,0 +1,99 @@
+---
+read_when:
+  - 你想在插件中添加新的智能体工具
+  - 你需要通过允许列表将工具设为可选启用
+summary: 在插件中编写智能体工具（模式定义、可选工具、允许列表）
+title: 插件智能体工具
+x-i18n:
+  generated_at: "2026-02-01T21:34:08Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4479462e9d8b17b664bf6b5f424f2efc8e7bedeaabfdb6a93126e051e635c659
+  source_path: plugins/agent-tools.md
+  workflow: 15
+---
+
+# 插件智能体工具
+
+OpenClaw 插件可以注册**智能体工具**（JSON Schema 函数），这些工具在智能体运行期间暴露给 LLM。工具可以是**必需的**（始终可用）或**可选的**（需主动启用）。
+
+智能体工具在主配置的 `tools` 下进行配置，或在 `agents.list[].tools` 下按智能体单独配置。允许列表/拒绝列表策略控制智能体可以调用哪些工具。
+
+## 基本工具
+
+```ts
+import { Type } from "@sinclair/typebox";
+
+export default function (api) {
+  api.registerTool({
+    name: "my_tool",
+    description: "Do a thing",
+    parameters: Type.Object({
+      input: Type.String(),
+    }),
+    async execute(_id, params) {
+      return { content: [{ type: "text", text: params.input }] };
+    },
+  });
+}
+```
+
+## 可选工具（主动启用）
+
+可选工具**永远不会**自动启用。用户必须将其添加到智能体的允许列表中。
+
+```ts
+export default function (api) {
+  api.registerTool(
+    {
+      name: "workflow_tool",
+      description: "Run a local workflow",
+      parameters: {
+        type: "object",
+        properties: {
+          pipeline: { type: "string" },
+        },
+        required: ["pipeline"],
+      },
+      async execute(_id, params) {
+        return { content: [{ type: "text", text: params.pipeline }] };
+      },
+    },
+    { optional: true },
+  );
+}
+```
+
+在 `agents.list[].tools.allow`（或全局 `tools.allow`）中启用可选工具：
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        tools: {
+          allow: [
+            "workflow_tool", // 指定工具名称
+            "workflow", // 插件 id（启用该插件的所有工具）
+            "group:plugins", // 所有插件工具
+          ],
+        },
+      },
+    ],
+  },
+}
+```
+
+影响工具可用性的其他配置项：
+
+- 仅包含插件工具名称的允许列表被视为插件启用配置；核心工具仍保持启用状态，除非你在允许列表中同时包含核心工具或工具组。
+- `tools.profile` / `agents.list[].tools.profile`（基础允许列表）
+- `tools.byProvider` / `agents.list[].tools.byProvider`（按提供商的允许/拒绝配置）
+- `tools.sandbox.tools.*`（沙箱环境下的沙箱工具策略）
+
+## 规则与建议
+
+- 工具名称**不得**与核心工具名称冲突；冲突的工具将被跳过。
+- 允许列表中使用的插件 id 不得与核心工具名称冲突。
+- 对于会触发副作用或需要额外二进制文件/凭据的工具，建议使用 `optional: true`。

package/docs/zh-CN/plugins/manifest.md

@@ -0,0 +1,68 @@
+---
+read_when:
+  - 你正在构建一个 OpenClaw 插件
+  - 你需要提供插件配置 Schema 或调试插件验证错误
+summary: 插件清单及 JSON Schema 要求（严格配置验证）
+title: 插件清单
+x-i18n:
+  generated_at: "2026-02-01T21:34:21Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 47b3e33c915f47bdd172ae0316af7ef16ca831c317e3f1a7fdfcd67e3bd43f56
+  source_path: plugins/manifest.md
+  workflow: 15
+---
+
+# 插件清单（openclaw.plugin.json）
+
+每个插件都**必须**在**插件根目录**下提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单来**在不执行插件代码的情况下**验证配置。缺失或无效的清单将被视为插件错误，并阻止配置验证。
+
+参阅完整的插件系统指南：[插件](/plugin)。
+
+## 必填字段
+
+```json
+{
+  "id": "voice-call",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
+```
+
+必填键：
+
+- `id`（字符串）：插件的规范 id。
+- `configSchema`（对象）：插件配置的 JSON Schema（内联形式）。
+
+可选键：
+
+- `kind`（字符串）：插件类型（例如：`"memory"`）。
+- `channels`（数组）：此插件注册的渠道 id（例如：`["matrix"]`）。
+- `providers`（数组）：此插件注册的提供商 id。
+- `skills`（数组）：要加载的 Skills 目录（相对于插件根目录）。
+- `name`（字符串）：插件的显示名称。
+- `description`（字符串）：插件简短描述。
+- `uiHints`（对象）：用于 UI 渲染的配置字段标签/占位符/敏感标志。
+- `version`（字符串）：插件版本（仅供参考）。
+
+## JSON Schema 要求
+
+- **每个插件都必须提供 JSON Schema**，即使不接受任何配置也是如此。
+- 空 Schema 是可以接受的（例如 `{ "type": "object", "additionalProperties": false }`）。
+- Schema 在配置读取/写入时进行验证，而非在运行时。
+
+## 验证行为
+
+- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已在插件清单中声明。
+- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
+- 如果插件已安装但清单或 Schema 损坏或缺失，验证将失败，Doctor 会报告插件错误。
+- 如果插件配置存在但插件已**禁用**，配置会被保留，并在 Doctor 和日志中显示**警告**。
+
+## 注意事项
+
+- 清单对**所有插件**都是必需的，包括从本地文件系统加载的插件。
+- 运行时仍然会单独加载插件模块；清单仅用于发现和验证。
+- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器允许列表要求（例如 pnpm 的 `allow-build-scripts` - `pnpm rebuild <package>`）。

package/docs/zh-CN/plugins/voice-call.md

@@ -0,0 +1,250 @@
+---
+read_when:
+  - 你想通过 OpenClaw 发起外呼语音通话
+  - 你正在配置或开发语音通话插件
+summary: 语音通话插件：通过 Twilio/Telnyx/Plivo 进行外呼和来电（插件安装 + 配置 + CLI）
+title: 语音通话插件
+x-i18n:
+  generated_at: "2026-02-01T21:34:37Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d731c63bf52781cc49262db550d0507d7fc33e5e7ce5d87efaf5d44aedcafef7
+  source_path: plugins/voice-call.md
+  workflow: 15
+---
+
+# 语音通话（插件）
+
+通过插件为 OpenClaw 提供语音通话功能。支持外呼通知和多轮对话的来电策略。
+
+当前支持的提供商：
+
+- `twilio`（Programmable Voice + Media Streams）
+- `telnyx`（Call Control v2）
+- `plivo`（Voice API + XML transfer + GetInput speech）
+- `mock`（开发环境/无网络）
+
+快速理解模型：
+
+- 安装插件
+- 重启 Gateway网关
+- 在 `plugins.entries.voice-call.config` 下进行配置
+- 使用 `openclaw voicecall ...` 或 `voice_call` 工具
+
+## 运行位置（本地 vs 远程）
+
+语音通话插件运行在 **Gateway网关进程内部**。
+
+如果你使用远程 Gateway网关，请在**运行 Gateway网关的机器**上安装和配置插件，然后重启 Gateway网关以加载它。
+
+## 安装
+
+### 方式 A：从 npm 安装（推荐）
+
+```bash
+openclaw plugins install @openclaw/voice-call
+```
+
+安装后重启 Gateway网关。
+
+### 方式 B：从本地文件夹安装（开发环境，不复制文件）
+
+```bash
+openclaw plugins install ./extensions/voice-call
+cd ./extensions/voice-call && pnpm install
+```
+
+安装后重启 Gateway网关。
+
+## 配置
+
+在 `plugins.entries.voice-call.config` 下设置配置：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        enabled: true,
+        config: {
+          provider: "twilio", // 或 "telnyx" | "plivo" | "mock"
+          fromNumber: "+15550001234",
+          toNumber: "+15550005678",
+
+          twilio: {
+            accountSid: "ACxxxxxxxx",
+            authToken: "...",
+          },
+
+          plivo: {
+            authId: "MAxxxxxxxxxxxxxxxxxxxx",
+            authToken: "...",
+          },
+
+          // Webhook 服务器
+          serve: {
+            port: 3334,
+            path: "/voice/webhook",
+          },
+
+          // 公网暴露（选择其一）
+          // publicUrl: "https://example.ngrok.app/voice/webhook",
+          // tunnel: { provider: "ngrok" },
+          // tailscale: { mode: "funnel", path: "/voice/webhook" }
+
+          outbound: {
+            defaultMode: "notify", // notify | conversation
+          },
+
+          streaming: {
+            enabled: true,
+            streamPath: "/voice/stream",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+注意事项：
+
+- Twilio/Telnyx 需要一个**可公网访问的** webhook URL。
+- Plivo 需要一个**可公网访问的** webhook URL。
+- `mock` 是本地开发提供商（不进行网络调用）。
+- `skipSignatureVerification` 仅用于本地测试。
+- 如果你使用 ngrok 免费版，请将 `publicUrl` 设置为精确的 ngrok URL；签名验证始终强制执行。
+- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 允许在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 local loopback（ngrok 本地代理）时，接受签名无效的 Twilio webhook。**仅用于本地开发**。
+- Ngrok 免费版 URL 可能会变化或出现插页行为；如果 `publicUrl` 偏移，Twilio 签名将会失败。生产环境建议使用稳定域名或 Tailscale funnel。
+
+## 通话的 TTS
+
+语音通话使用核心 `messages.tts` 配置（OpenAI 或 ElevenLabs）来进行通话中的流式语音合成。你可以在插件配置下使用**相同的结构**进行覆盖——它会与 `messages.tts` 进行深度合并。
+
+```json5
+{
+  tts: {
+    provider: "elevenlabs",
+    elevenlabs: {
+      voiceId: "pMsXgVXv3BLzUgSXRplE",
+      modelId: "eleven_multilingual_v2",
+    },
+  },
+}
+```
+
+注意事项：
+
+- **语音通话会忽略 Edge TTS**（电话音频需要 PCM；Edge 输出不可靠）。
+- 当启用 Twilio 媒体流时使用核心 TTS；否则通话将回退到提供商原生语音。
+
+### 更多示例
+
+仅使用核心 TTS（不覆盖）：
+
+```json5
+{
+  messages: {
+    tts: {
+      provider: "openai",
+      openai: { voice: "alloy" },
+    },
+  },
+}
+```
+
+仅为通话覆盖为 ElevenLabs（其他地方保持核心默认值）：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            provider: "elevenlabs",
+            elevenlabs: {
+              apiKey: "elevenlabs_key",
+              voiceId: "pMsXgVXv3BLzUgSXRplE",
+              modelId: "eleven_multilingual_v2",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+仅为通话覆盖 OpenAI 模型（深度合并示例）：
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          tts: {
+            openai: {
+              model: "gpt-4o-mini-tts",
+              voice: "marin",
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## 来电
+
+来电策略默认为 `disabled`。要启用来电，请设置：
+
+```json5
+{
+  inboundPolicy: "allowlist",
+  allowFrom: ["+15550001234"],
+  inboundGreeting: "Hello! How can I help?",
+}
+```
+
+自动回复使用智能体系统。通过以下参数进行调优：
+
+- `responseModel`
+- `responseSystemPrompt`
+- `responseTimeoutMs`
+
+## CLI
+
+```bash
+openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
+openclaw voicecall continue --call-id <id> --message "Any questions?"
+openclaw voicecall speak --call-id <id> --message "One moment"
+openclaw voicecall end --call-id <id>
+openclaw voicecall status --call-id <id>
+openclaw voicecall tail
+openclaw voicecall expose --mode funnel
+```
+
+## 智能体工具
+
+工具名称：`voice_call`
+
+操作：
+
+- `initiate_call`（message、to?、mode?）
+- `continue_call`（callId、message）
+- `speak_to_user`（callId、message）
+- `end_call`（callId）
+- `get_status`（callId）
+
+本仓库附带了对应的 Skills 文档，位于 `skills/voice-call/SKILL.md`。
+
+## Gateway网关 RPC
+
+- `voicecall.initiate`（`to?`、`message`、`mode?`）
+- `voicecall.continue`（`callId`、`message`）
+- `voicecall.speak`（`callId`、`message`）
+- `voicecall.end`（`callId`）
+- `voicecall.status`（`callId`）

package/docs/zh-CN/plugins/zalouser.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 你想在 OpenClaw 中使用 Zalo Personal（非官方）支持
+  - 你正在配置或开发 zalouser 插件
+summary: Zalo Personal 插件：通过 zca-cli 实现二维码登录和消息收发（插件安装 + 渠道配置 + CLI + 工具）
+title: Zalo Personal 插件
+x-i18n:
+  generated_at: "2026-02-01T21:34:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b29b788b023cd50720e24fe6719f02e9f86c8bca9c73b3638fb53c2316718672
+  source_path: plugins/zalouser.md
+  workflow: 15
+---
+
+# Zalo Personal（插件）
+
+通过插件为 OpenClaw 提供 Zalo Personal 支持，使用 `zca-cli` 自动化操作普通 Zalo 用户账号。
+
+> **警告：**非官方自动化可能导致账号被暂停或封禁。使用风险自负。
+
+## 命名
+
+渠道 id 为 `zalouser`，以明确表示这是对**个人 Zalo 用户账号**的自动化操作（非官方）。我们将 `zalo` 保留给未来可能的官方 Zalo API 集成。
+
+## 运行位置
+
+此插件运行在 **Gateway网关进程内部**。
+
+如果你使用远程 Gateway网关，请在**运行 Gateway网关的机器上**安装和配置此插件，然后重启 Gateway网关。
+
+## 安装
+
+### 方式 A：从 npm 安装
+
+```bash
+openclaw plugins install @openclaw/zalouser
+```
+
+安装后重启 Gateway网关。
+
+### 方式 B：从本地文件夹安装（开发模式）
+
+```bash
+openclaw plugins install ./extensions/zalouser
+cd ./extensions/zalouser && pnpm install
+```
+
+安装后重启 Gateway网关。
+
+## 前提条件：zca-cli
+
+Gateway网关所在机器必须将 `zca` 添加到 `PATH` 中：
+
+```bash
+zca --version
+```
+
+## 配置
+
+渠道配置位于 `channels.zalouser` 下（而非 `plugins.entries.*`）：
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+## CLI
+
+```bash
+openclaw channels login --channel zalouser
+openclaw channels logout --channel zalouser
+openclaw channels status --probe
+openclaw message send --channel zalouser --target <threadId> --message "Hello from OpenClaw"
+openclaw directory peers list --channel zalouser --query "name"
+```
+
+## 智能体工具
+
+工具名称：`zalouser`
+
+操作：`send`、`image`、`link`、`friends`、`groups`、`me`、`status`

package/docs/zh-CN/prose.md

@@ -0,0 +1,141 @@
+---
+read_when:
+  - 你想运行或编写 .prose 工作流
+  - 你想启用 OpenProse 插件
+  - 你需要了解状态存储
+summary: OpenProse：OpenClaw 中的 .prose 工作流、斜杠命令和状态管理
+title: OpenProse
+x-i18n:
+  generated_at: "2026-02-01T21:34:47Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: cf7301e927b9a46347b498e264aeaa10dd76e85ff2de04775be57435718339f5
+  source_path: prose.md
+  workflow: 15
+---
+
+# OpenProse
+
+OpenProse 是一种可移植的、以 Markdown 为核心的工作流格式，用于编排 AI 会话。在 OpenClaw 中，它以插件形式提供，安装后包含一个 OpenProse Skills 包和一个 `/prose` 斜杠命令。程序存放在 `.prose` 文件中，可以通过显式控制流生成多个子智能体。
+
+官方网站：https://www.prose.md
+
+## 功能概述
+
+- 支持显式并行的多智能体研究与综合。
+- 可重复的、审批安全的工作流（代码审查、事件分诊、内容流水线）。
+- 可复用的 `.prose` 程序，可在支持的智能体运行时中运行。
+
+## 安装与启用
+
+内置插件默认处于禁用状态。启用 OpenProse：
+
+```bash
+openclaw plugins enable open-prose
+```
+
+启用插件后重启 Gateway网关。
+
+开发/本地签出：`openclaw plugins install ./extensions/open-prose`
+
+相关文档：[插件](/plugin)、[插件清单](/plugins/manifest)、[Skills](/tools/skills)。
+
+## 斜杠命令
+
+OpenProse 注册 `/prose` 作为用户可调用的 Skills 命令。它路由到 OpenProse 虚拟机指令，底层使用 OpenClaw 工具。
+
+常用命令：
+
+```
+/prose help
+/prose run <file.prose>
+/prose run <handle/slug>
+/prose run <https://example.com/file.prose>
+/prose compile <file.prose>
+/prose examples
+/prose update
+```
+
+## 示例：一个简单的 `.prose` 文件
+
+```prose
+# Research + synthesis with two agents running in parallel.
+
+input topic: "What should we research?"
+
+agent researcher:
+  model: sonnet
+  prompt: "You research thoroughly and cite sources."
+
+agent writer:
+  model: opus
+  prompt: "You write a concise summary."
+
+parallel:
+  findings = session: researcher
+    prompt: "Research {topic}."
+  draft = session: writer
+    prompt: "Summarize {topic}."
+
+session "Merge the findings + draft into a final answer."
+context: { findings, draft }
+```
+
+## 文件位置
+
+OpenProse 将状态保存在工作区的 `.prose/` 目录下：
+
+```
+.prose/
+├── .env
+├── runs/
+│   └── {YYYYMMDD}-{HHMMSS}-{random}/
+│       ├── program.prose
+│       ├── state.md
+│       ├── bindings/
+│       └── agents/
+└── agents/
+```
+
+用户级别的持久化智能体存放在：
+
+```
+~/.prose/agents/
+```
+
+## 状态模式
+
+OpenProse 支持多种状态后端：
+
+- **filesystem**（默认）：`.prose/runs/...`
+- **in-context**：瞬态，适用于小型程序
+- **sqlite**（实验性）：需要 `sqlite3` 二进制文件
+- **postgres**（实验性）：需要 `psql` 和连接字符串
+
+注意事项：
+
+- sqlite/postgres 为可选启用，属于实验性功能。
+- postgres 凭据会流入子智能体日志；请使用专用的最小权限数据库。
+
+## 远程程序
+
+`/prose run <handle/slug>` 解析为 `https://p.prose.md/<handle>/<slug>`。
+直接 URL 按原样获取。此功能使用 `web_fetch` 工具（POST 请求使用 `exec`）。
+
+## OpenClaw 运行时映射
+
+OpenProse 程序映射到 OpenClaw 原语：
+
+| OpenProse 概念       | OpenClaw 工具    |
+| -------------------- | ---------------- |
+| 生成会话 / Task 工具 | `sessions_spawn` |
+| 文件读写             | `read` / `write` |
+| Web 获取             | `web_fetch`      |
+
+如果你的工具允许列表阻止了这些工具，OpenProse 程序将无法运行。参阅[Skills配置](/tools/skills-config)。
+
+## 安全与审批
+
+请像对待代码一样对待 `.prose` 文件。运行前请先审查。使用 OpenClaw 工具允许列表和审批门控来控制副作用。
+
+如需确定性的、带审批门控的工作流，可参考 [Lobster](/tools/lobster) 进行比较。