@gguf/claw 2026.2.1 → 2026.2.3

package/docs/zh-CN/multi-agent-sandbox-tools.md

@@ -0,0 +1,399 @@
+---
+read_when: You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.
+status: active
+summary: 每个智能体的沙箱与工具限制、优先级及示例
+title: 多智能体沙箱与工具
+x-i18n:
+  generated_at: "2026-02-01T21:17:27Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f602cb6192b84b404cd7b6336562888a239d0fe79514edd51bd73c5b090131ef
+  source_path: multi-agent-sandbox-tools.md
+  workflow: 15
+---
+
+# 多智能体沙箱与工具配置
+
+## 概述
+
+在多智能体设置中，每个智能体现在可以拥有独立的：
+
+- **沙箱配置**（`agents.list[].sandbox` 覆盖 `agents.defaults.sandbox`）
+- **工具限制**（`tools.allow` / `tools.deny`，以及 `agents.list[].tools`）
+
+这允许你运行具有不同安全配置的多个智能体：
+
+- 拥有完全访问权限的个人助手
+- 工具受限的家庭/工作智能体
+- 在沙箱中运行的面向公众的智能体
+
+`setupCommand` 属于 `sandbox.docker`（全局或每个智能体），在容器创建时运行一次。
+
+认证是按智能体隔离的：每个智能体从其自己的 `agentDir` 认证存储中读取：
+
+```
+~/.openclaw/agents/<agentId>/agent/auth-profiles.json
+```
+
+凭据**不会**在智能体之间共享。切勿在智能体之间复用 `agentDir`。
+如果你想共享凭据，请将 `auth-profiles.json` 复制到其他智能体的 `agentDir` 中。
+
+有关沙箱在运行时的行为，请参阅[沙箱](/gateway/sandboxing)。
+有关调试"为什么被阻止了？"，请参阅[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated)和 `openclaw sandbox explain`。
+
+---
+
+## 配置示例
+
+### 示例 1：个人助手 + 受限家庭智能体
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "name": "Personal Assistant",
+        "workspace": "~/.openclaw/workspace",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "family",
+        "name": "Family Bot",
+        "workspace": "~/.openclaw/workspace-family",
+        "sandbox": {
+          "mode": "all",
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
+        }
+      }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "family",
+      "match": {
+        "provider": "whatsapp",
+        "accountId": "*",
+        "peer": {
+          "kind": "group",
+          "id": "120363424282127706@g.us"
+        }
+      }
+    }
+  ]
+}
+```
+
+**结果：**
+
+- `main` 智能体：在宿主机上运行，拥有完全工具访问权限
+- `family` 智能体：在 Docker 中运行（每个智能体一个容器），仅有 `read` 工具
+
+---
+
+### 示例 2：使用共享沙箱的工作智能体
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "personal",
+        "workspace": "~/.openclaw/workspace-personal",
+        "sandbox": { "mode": "off" }
+      },
+      {
+        "id": "work",
+        "workspace": "~/.openclaw/workspace-work",
+        "sandbox": {
+          "mode": "all",
+          "scope": "shared",
+          "workspaceRoot": "/tmp/work-sandboxes"
+        },
+        "tools": {
+          "allow": ["read", "write", "apply_patch", "exec"],
+          "deny": ["browser", "gateway", "discord"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 示例 2b：全局编程配置 + 仅消息传递的智能体
+
+```json
+{
+  "tools": { "profile": "coding" },
+  "agents": {
+    "list": [
+      {
+        "id": "support",
+        "tools": { "profile": "messaging", "allow": ["slack"] }
+      }
+    ]
+  }
+}
+```
+
+**结果：**
+
+- 默认智能体获得编程工具
+- `support` 智能体仅限消息传递（+ Slack 工具）
+
+---
+
+### 示例 3：每个智能体不同的沙箱模式
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "non-main", // 全局默认值
+        "scope": "session"
+      }
+    },
+    "list": [
+      {
+        "id": "main",
+        "workspace": "~/.openclaw/workspace",
+        "sandbox": {
+          "mode": "off" // 覆盖：main 永不沙箱隔离
+        }
+      },
+      {
+        "id": "public",
+        "workspace": "~/.openclaw/workspace-public",
+        "sandbox": {
+          "mode": "all", // 覆盖：public 始终沙箱隔离
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["exec", "write", "edit", "apply_patch"]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 配置优先级
+
+当全局配置（`agents.defaults.*`）和智能体特定配置（`agents.list[].*`）同时存在时：
+
+### 沙箱配置
+
+智能体特定设置覆盖全局设置：
+
+```
+agents.list[].sandbox.mode > agents.defaults.sandbox.mode
+agents.list[].sandbox.scope > agents.defaults.sandbox.scope
+agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
+agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
+agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
+agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
+agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
+```
+
+**注意事项：**
+
+- `agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖该智能体的 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱范围解析为 `"shared"` 时忽略）。
+
+### 工具限制
+
+过滤顺序为：
+
+1. **工具配置**（`tools.profile` 或 `agents.list[].tools.profile`）
+2. **提供商工具配置**（`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`）
+3. **全局工具策略**（`tools.allow` / `tools.deny`）
+4. **提供商工具策略**（`tools.byProvider[provider].allow/deny`）
+5. **智能体特定工具策略**（`agents.list[].tools.allow/deny`）
+6. **智能体提供商策略**（`agents.list[].tools.byProvider[provider].allow/deny`）
+7. **沙箱工具策略**（`tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`）
+8. **子智能体工具策略**（`tools.subagents.tools`，如适用）
+
+每一层可以进一步限制工具，但不能恢复在前面层级中已被拒绝的工具。
+如果设置了 `agents.list[].tools.sandbox.tools`，它会替换该智能体的 `tools.sandbox.tools`。
+如果设置了 `agents.list[].tools.profile`，它会覆盖该智能体的 `tools.profile`。
+提供商工具键接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.2`）。
+
+### 工具组（简写）
+
+工具策略（全局、智能体、沙箱）支持 `group:*` 条目，它们会展开为多个具体工具：
+
+- `group:runtime`：`exec`、`bash`、`process`
+- `group:fs`：`read`、`write`、`edit`、`apply_patch`
+- `group:sessions`：`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
+- `group:memory`：`memory_search`、`memory_get`
+- `group:ui`：`browser`、`canvas`
+- `group:automation`：`cron`、`gateway`
+- `group:messaging`：`message`
+- `group:nodes`：`nodes`
+- `group:openclaw`：所有内置 OpenClaw 工具（不包括提供商插件）
+
+### 提权模式
+
+`tools.elevated` 是全局基线（基于发送者的允许列表）。`agents.list[].tools.elevated` 可以进一步限制特定智能体的提权（两者都必须允许）。
+
+缓解模式：
+
+- 对不受信任的智能体拒绝 `exec`（`agents.list[].tools.deny: ["exec"]`）
+- 避免将发送者加入允许列表后路由到受限智能体
+- 如果你只需要沙箱隔离执行，可全局禁用提权（`tools.elevated.enabled: false`）
+- 对敏感配置按智能体禁用提权（`agents.list[].tools.elevated.enabled: false`）
+
+---
+
+## 从单智能体迁移
+
+**之前（单智能体）：**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.openclaw/workspace",
+      "sandbox": {
+        "mode": "non-main"
+      }
+    }
+  },
+  "tools": {
+    "sandbox": {
+      "tools": {
+        "allow": ["read", "write", "apply_patch", "exec"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+**之后（具有不同配置的多智能体）：**
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "workspace": "~/.openclaw/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    ]
+  }
+}
+```
+
+旧版 `agent.*` 配置会由 `openclaw doctor` 迁移；今后请优先使用 `agents.defaults` + `agents.list`。
+
+---
+
+## 工具限制示例
+
+### 只读智能体
+
+```json
+{
+  "tools": {
+    "allow": ["read"],
+    "deny": ["exec", "write", "edit", "apply_patch", "process"]
+  }
+}
+```
+
+### 安全执行智能体（无文件修改）
+
+```json
+{
+  "tools": {
+    "allow": ["read", "exec", "process"],
+    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
+  }
+}
+```
+
+### 仅通信智能体
+
+```json
+{
+  "tools": {
+    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
+    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
+  }
+}
+```
+
+---
+
+## 常见陷阱："non-main"
+
+`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认为 `"main"`），
+而不是智能体 ID。群组/渠道会话总是获得自己的键，因此它们被视为非主会话并将被沙箱隔离。如果你希望某个智能体永不沙箱隔离，请设置 `agents.list[].sandbox.mode: "off"`。
+
+---
+
+## 测试
+
+配置多智能体沙箱和工具后：
+
+1. **检查智能体路由解析：**
+
+   ```exec
+   openclaw agents list --bindings
+   ```
+
+2. **验证沙箱容器：**
+
+   ```exec
+   docker ps --filter "name=openclaw-sbx-"
+   ```
+
+3. **测试工具限制：**
+   - 发送一条需要受限工具的消息
+   - 验证智能体无法使用被拒绝的工具
+
+4. **监控日志：**
+   ```exec
+   tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
+   ```
+
+---
+
+## 故障排除
+
+### 尽管设置了 `mode: "all"`，智能体未被沙箱隔离
+
+- 检查是否有全局 `agents.defaults.sandbox.mode` 覆盖了它
+- 智能体特定配置优先级更高，因此请设置 `agents.list[].sandbox.mode: "all"`
+
+### 尽管设置了拒绝列表，工具仍然可用
+
+- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → 子智能体
+- 每一层只能进一步限制，不能恢复已拒绝的工具
+- 通过日志验证：`[tools] filtering tools for agent:${agentId}`
+
+### 容器未按智能体隔离
+
+- 在智能体特定沙箱配置中设置 `scope: "agent"`
+- 默认值为 `"session"`，即每个会话创建一个容器
+
+---
+
+## 另请参阅
+
+- [多智能体路由](/concepts/multi-agent)
+- [沙箱配置](/gateway/configuration#agentsdefaults-sandbox)
+- [会话管理](/concepts/session)

package/docs/zh-CN/network.md

@@ -0,0 +1,59 @@
+---
+read_when:
+  - 你需要了解网络架构和安全概览
+  - 你正在调试本地访问与 tailnet 访问或配对问题
+  - 你想获取网络文档的权威列表
+summary: 网络中心：Gateway网关接口、配对、发现和安全
+title: 网络
+x-i18n:
+  generated_at: "2026-02-01T21:17:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0fe4e7dbc8ddea312c8f3093af9b6bc71d9ae4007df76ae24b85889871933bc8
+  source_path: network.md
+  workflow: 15
+---
+
+# 网络中心
+
+本中心汇集了 OpenClaw 如何在 localhost、局域网和 tailnet 之间连接、配对和保护设备的核心文档。
+
+## 核心模型
+
+- [Gateway网关架构](/concepts/architecture)
+- [Gateway网关协议](/gateway/protocol)
+- [Gateway网关运维手册](/gateway)
+- [Web 接口 + 绑定模式](/web)
+
+## 配对 + 身份
+
+- [配对概览（私信 + 节点）](/start/pairing)
+- [Gateway网关拥有的节点配对](/gateway/pairing)
+- [设备 CLI（配对 + 令牌轮换）](/cli/devices)
+- [配对 CLI（私信 审批）](/cli/pairing)
+
+本地信任：
+
+- 本地连接（local loopback 或 Gateway网关主机自身的 tailnet 地址）可以自动批准配对，以保持同主机用户体验的流畅性。
+- 非本地的 tailnet/局域网客户端仍需要明确的配对审批。
+
+## 发现 + 传输
+
+- [发现与传输](/gateway/discovery)
+- [Bonjour / mDNS](/gateway/bonjour)
+- [远程访问（SSH）](/gateway/remote)
+- [Tailscale](/gateway/tailscale)
+
+## 节点 + 传输
+
+- [节点概览](/nodes)
+- [Bridge 协议（旧版节点）](/gateway/bridge-protocol)
+- [节点运维手册：iOS](/platforms/ios)
+- [节点运维手册：Android](/platforms/android)
+
+## 安全
+
+- [安全概览](/gateway/security)
+- [Gateway网关配置参考](/gateway/configuration)
+- [故障排除](/gateway/troubleshooting)
+- [Doctor](/gateway/doctor)

package/docs/zh-CN/nodes/audio.md

@@ -0,0 +1,120 @@
+---
+read_when:
+  - 更改音频转录或媒体处理方式
+summary: 入站音频/语音消息如何被下载、转录并注入回复
+title: 音频与语音消息
+x-i18n:
+  generated_at: "2026-02-01T21:17:35Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b926c47989ab0d1ee1fb8ae6372c51d27515b53d6fefe211a85856d372f14569
+  source_path: nodes/audio.md
+  workflow: 15
+---
+
+# 音频 / 语音消息 — 2026-01-17
+
+## 已支持的功能
+
+- **媒体理解（音频）**：如果音频理解已启用（或自动检测），OpenClaw 会：
+  1. 找到第一个音频附件（本地路径或 URL），如有需要则下载。
+  2. 在发送给每个模型条目之前执行 `maxBytes` 限制。
+  3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。
+  4. 如果失败或跳过（大小/超时），则尝试下一个条目。
+  5. 成功后，将 `Body` 替换为 `[Audio]` 块并设置 `{{Transcript}}`。
+- **命令解析**：转录成功时，`CommandBody`/`RawBody` 会设置为转录文本，因此斜杠命令仍然有效。
+- **详细日志**：在 `--verbose` 模式下，我们会在转录运行和替换正文时记录日志。
+
+## 自动检测（默认）
+
+如果你**未配置模型**且 `tools.media.audio.enabled` **未**设置为 `false`，OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项时停止：
+
+1. **本地 CLI**（如已安装）
+   - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
+   - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
+   - `whisper`（Python CLI；自动下载模型）
+2. **Gemini CLI**（`gemini`）使用 `read_many_files`
+3. **提供商密钥**（OpenAI → Groq → Deepgram → Google）
+
+要禁用自动检测，请设置 `tools.media.audio.enabled: false`。
+要自定义，请设置 `tools.media.audio.models`。
+注意：二进制检测在 macOS/Linux/Windows 上采用尽力而为的方式；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或通过完整命令路径设置显式 CLI 模型。
+
+## 配置示例
+
+### 提供商 + CLI 回退（OpenAI + Whisper CLI）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        maxBytes: 20971520,
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          {
+            type: "cli",
+            command: "whisper",
+            args: ["--model", "base", "{{MediaPath}}"],
+            timeoutSeconds: 45,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+### 仅提供商 + 作用域控制
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        scope: {
+          default: "allow",
+          rules: [{ action: "deny", match: { chatType: "group" } }],
+        },
+        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
+      },
+    },
+  },
+}
+```
+
+### 仅提供商（Deepgram）
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        enabled: true,
+        models: [{ provider: "deepgram", model: "nova-3" }],
+      },
+    },
+  },
+}
+```
+
+## 注意事项与限制
+
+- 提供商认证遵循标准的模型认证顺序（认证配置文件、环境变量、`models.providers.*.apiKey`）。
+- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。
+- Deepgram 设置详情：[Deepgram（音频转录）](/providers/deepgram)。
+- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。
+- 默认大小限制为 20MB（`tools.media.audio.maxBytes`）。超大音频会跳过该模型并尝试下一个条目。
+- 音频的默认 `maxChars` **未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 来裁剪输出。
+- OpenAI 自动检测默认使用 `gpt-4o-mini-transcribe`；设置 `model: "gpt-4o-transcribe"` 可获得更高准确度。
+- 使用 `tools.media.audio.attachments` 处理多条语音消息（`mode: "all"` + `maxAttachments`）。
+- 转录文本可在模板中通过 `{{Transcript}}` 使用。
+- CLI 标准输出有上限（5MB）；请保持 CLI 输出简洁。
+
+## 常见陷阱
+
+- 作用域规则采用首次匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。
+- 确保你的 CLI 以退出码 0 退出并输出纯文本；JSON 格式需要通过 `jq -r .text` 进行转换。
+- 保持合理的超时时间（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。