mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-02 15:58:26 +00:00
Docs: add zh-CN translations
This commit is contained in:
Josh Palmer
60
docs/zh-CN/tools/agent-send.md
Normal file
60
docs/zh-CN/tools/agent-send.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改智能体 CLI 入口点
|
||||
summary: 直接通过 `openclaw agent` CLI 运行（支持可选的消息投递）
|
||||
title: 智能体发送
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:39:16Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a84d6a304333eebe155da2bf24cf5fc0482022a0a48ab34aa1465cd6e667022d
|
||||
source_path: tools/agent-send.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw agent`（直接运行智能体）
|
||||
|
||||
`openclaw agent` 无需入站聊天消息即可运行单次智能体轮次。
|
||||
默认情况下它**通过 Gateway** 运行；添加 `--local` 可强制使用当前机器上的嵌入式
|
||||
运行时。
|
||||
|
||||
## 行为
|
||||
|
||||
- 必需：`--message <text>`
|
||||
- 会话选择：
|
||||
- `--to <dest>` 推导会话密钥（群组/渠道目标保持隔离；直接聊天合并为 `main`），**或**
|
||||
- `--session-id <id>` 通过 id 复用现有会话，**或**
|
||||
- `--agent <id>` 直接指向已配置的智能体（使用该智能体的 `main` 会话密钥）
|
||||
- 运行与正常入站回复相同的嵌入式智能体运行时。
|
||||
- thinking/verbose 标志会持久化到会话存储中。
|
||||
- 输出：
|
||||
- 默认：打印回复文本（加上 `MEDIA:<url>` 行）
|
||||
- `--json`：打印结构化载荷 + 元数据
|
||||
- 可选通过 `--deliver` + `--channel` 将回复投递回渠道（目标格式与 `openclaw message --target` 一致）。
|
||||
- 使用 `--reply-channel`/`--reply-to`/`--reply-account` 可在不改变会话的情况下覆盖投递设置。
|
||||
|
||||
如果 Gateway 不可达，CLI 会**回退**到嵌入式本地运行。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
openclaw agent --to +15555550123 --message "status update"
|
||||
openclaw agent --agent ops --message "Summarize logs"
|
||||
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
|
||||
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
|
||||
openclaw agent --to +15555550123 --message "Summon reply" --deliver
|
||||
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
|
||||
```
|
||||
|
||||
## 标志
|
||||
|
||||
- `--local`：本地运行（需要在你的 shell 中配置模型提供商 API 密钥）
|
||||
- `--deliver`：将回复发送到所选渠道
|
||||
- `--channel`：投递渠道（`whatsapp|telegram|discord|googlechat|slack|signal|imessage`，默认：`whatsapp`）
|
||||
- `--reply-to`：投递目标覆盖
|
||||
- `--reply-channel`：投递渠道覆盖
|
||||
- `--reply-account`：投递账户 id 覆盖
|
||||
- `--thinking <off|minimal|low|medium|high|xhigh>`：持久化思考级别（仅限 GPT-5.2 + Codex 模型）
|
||||
- `--verbose <on|full|off>`：持久化详细级别
|
||||
- `--timeout <seconds>`：覆盖智能体超时时间
|
||||
- `--json`：输出结构化 JSON
|
||||
57
docs/zh-CN/tools/apply-patch.md
Normal file
57
docs/zh-CN/tools/apply-patch.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要跨多个文件进行结构化编辑
|
||||
- 你想要记录或调试基于补丁的编辑
|
||||
summary: 使用 apply_patch 工具应用多文件补丁
|
||||
title: apply_patch 工具
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:39:24Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 8cec2b4ee3afa9105fc3dd1bc28a338917df129afc634ac83620a3347c46bcec
|
||||
source_path: tools/apply-patch.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# apply_patch 工具
|
||||
|
||||
使用结构化补丁格式应用文件更改。这非常适合多文件
|
||||
或多段编辑，在这些场景下单次 `edit` 调用会很脆弱。
|
||||
|
||||
该工具接受一个 `input` 字符串，其中包含一个或多个文件操作：
|
||||
|
||||
```
|
||||
*** Begin Patch
|
||||
*** Add File: path/to/file.txt
|
||||
+line 1
|
||||
+line 2
|
||||
*** Update File: src/app.ts
|
||||
@@
|
||||
-old line
|
||||
+new line
|
||||
*** Delete File: obsolete.txt
|
||||
*** End Patch
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
- `input`（必需）：完整的补丁内容，包括 `*** Begin Patch` 和 `*** End Patch`。
|
||||
|
||||
## 说明
|
||||
|
||||
- 路径相对于工作区根目录解析。
|
||||
- 在 `*** Update File:` 段中使用 `*** Move to:` 可重命名文件。
|
||||
- 需要时使用 `*** End of File` 标记仅在文件末尾的插入。
|
||||
- 实验性功能，默认禁用。通过 `tools.exec.applyPatch.enabled` 启用。
|
||||
- 仅限 OpenAI（包括 OpenAI Codex）。可选通过
|
||||
`tools.exec.applyPatch.allowModels` 按模型进行限制。
|
||||
- 配置仅在 `tools.exec` 下。
|
||||
|
||||
## 示例
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "apply_patch",
|
||||
"input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
|
||||
}
|
||||
```
|
||||
146
docs/zh-CN/tools/browser-linux-troubleshooting.md
Normal file
146
docs/zh-CN/tools/browser-linux-troubleshooting.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
read_when: Browser control fails on Linux, especially with snap Chromium
|
||||
summary: 修复 Linux 上 OpenClaw 浏览器控制的 Chrome/Brave/Edge/Chromium CDP 启动问题
|
||||
title: 浏览器故障排除
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:39:41Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: bac2301022511a0bf8ebe1309606cc03e8a979ff74866c894f89d280ca3e514e
|
||||
source_path: tools/browser-linux-troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 浏览器故障排除（Linux）
|
||||
|
||||
## 问题："Failed to start Chrome CDP on port 18800"
|
||||
|
||||
OpenClaw 的浏览器控制服务器无法启动 Chrome/Brave/Edge/Chromium，报错如下：
|
||||
|
||||
```
|
||||
{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}
|
||||
```
|
||||
|
||||
### 根本原因
|
||||
|
||||
在 Ubuntu（以及许多 Linux 发行版）上，默认的 Chromium 安装是一个 **snap 包**。Snap 的 AppArmor 沙箱限制会干扰 OpenClaw 生成和监控浏览器进程的方式。
|
||||
|
||||
`apt install chromium` 命令安装的是一个重定向到 snap 的占位包：
|
||||
|
||||
```
|
||||
Note, selecting 'chromium-browser' instead of 'chromium'
|
||||
chromium-browser is already the newest version (2:1snap1-0ubuntu2).
|
||||
```
|
||||
|
||||
这不是一个真正的浏览器——它只是一个包装器。
|
||||
|
||||
### 方案 1：安装 Google Chrome（推荐）
|
||||
|
||||
安装官方的 Google Chrome `.deb` 包，它不受 snap 沙箱限制：
|
||||
|
||||
```bash
|
||||
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
|
||||
sudo dpkg -i google-chrome-stable_current_amd64.deb
|
||||
sudo apt --fix-broken install -y # 如果有依赖错误
|
||||
```
|
||||
|
||||
然后更新你的 OpenClaw 配置（`~/.openclaw/openclaw.json`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"browser": {
|
||||
"enabled": true,
|
||||
"executablePath": "/usr/bin/google-chrome-stable",
|
||||
"headless": true,
|
||||
"noSandbox": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方案 2：使用 Snap Chromium 的仅附加模式
|
||||
|
||||
如果你必须使用 snap Chromium，请配置 OpenClaw 附加到手动启动的浏览器：
|
||||
|
||||
1. 更新配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"browser": {
|
||||
"enabled": true,
|
||||
"attachOnly": true,
|
||||
"headless": true,
|
||||
"noSandbox": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 手动启动 Chromium：
|
||||
|
||||
```bash
|
||||
chromium-browser --headless --no-sandbox --disable-gpu \
|
||||
--remote-debugging-port=18800 \
|
||||
--user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
|
||||
about:blank &
|
||||
```
|
||||
|
||||
3. 可选创建一个 systemd 用户服务来自动启动 Chrome：
|
||||
|
||||
```ini
|
||||
# ~/.config/systemd/user/openclaw-browser.service
|
||||
[Unit]
|
||||
Description=OpenClaw Browser (Chrome CDP)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
启用命令：`systemctl --user enable --now openclaw-browser.service`
|
||||
|
||||
### 验证浏览器是否正常工作
|
||||
|
||||
检查状态：
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
|
||||
```
|
||||
|
||||
测试浏览：
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:18791/start
|
||||
curl -s http://127.0.0.1:18791/tabs
|
||||
```
|
||||
|
||||
### 配置参考
|
||||
|
||||
| 选项 | 描述 | 默认值 |
|
||||
| ------------------------ | ------------------------------------------------------------- | ------------------------------------------------ |
|
||||
| `browser.enabled` | 启用浏览器控制 | `true` |
|
||||
| `browser.executablePath` | Chromium 系浏览器二进制文件路径（Chrome/Brave/Edge/Chromium） | 自动检测（当默认浏览器为 Chromium 系时优先使用） |
|
||||
| `browser.headless` | 无界面运行 | `false` |
|
||||
| `browser.noSandbox` | 添加 `--no-sandbox` 标志（某些 Linux 环境需要） | `false` |
|
||||
| `browser.attachOnly` | 不启动浏览器，仅附加到现有实例 | `false` |
|
||||
| `browser.cdpPort` | Chrome DevTools Protocol 端口 | `18800` |
|
||||
|
||||
### 问题："Chrome extension relay is running, but no tab is connected"
|
||||
|
||||
你正在使用 `chrome` 配置文件（扩展中继）。它需要 OpenClaw
|
||||
浏览器扩展附加到一个活动标签页。
|
||||
|
||||
修复方案：
|
||||
|
||||
1. **使用托管浏览器：** `openclaw browser start --browser-profile openclaw`
|
||||
（或设置 `browser.defaultProfile: "openclaw"`）。
|
||||
2. **使用扩展中继：** 安装扩展，打开一个标签页，然后点击
|
||||
OpenClaw 扩展图标进行附加。
|
||||
|
||||
说明：
|
||||
|
||||
- `chrome` 配置文件会尽可能使用你的**系统默认 Chromium 浏览器**。
|
||||
- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；仅在远程 CDP 时需要手动设置。
|
||||
75
docs/zh-CN/tools/browser-login.md
Normal file
75
docs/zh-CN/tools/browser-login.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要登录网站以进行浏览器自动化
|
||||
- 你想要在 X/Twitter 上发布更新
|
||||
summary: 浏览器自动化的手动登录 + X/Twitter 发帖
|
||||
title: 浏览器登录
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:39:37Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 8ceea2d5258836e3db10f858ee122b5832a40f83a72ba18de140671091eef5a8
|
||||
source_path: tools/browser-login.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 浏览器登录 + X/Twitter 发帖
|
||||
|
||||
## 手动登录（推荐）
|
||||
|
||||
当网站需要登录时，请在**宿主**浏览器配置文件（openclaw 浏览器）中**手动登录**。
|
||||
|
||||
**不要**将你的凭据交给模型。自动登录往往会触发反机器人防御，并可能导致账号被锁定。
|
||||
|
||||
返回浏览器主文档：[浏览器](/tools/browser)。
|
||||
|
||||
## 使用哪个 Chrome 配置文件？
|
||||
|
||||
OpenClaw 控制一个**专用 Chrome 配置文件**（名为 `openclaw`，橙色调界面）。它与你的日常浏览器配置文件是分开的。
|
||||
|
||||
两种简单的访问方式：
|
||||
|
||||
1. **让智能体打开浏览器**，然后自己登录。
|
||||
2. **通过 CLI 打开**：
|
||||
|
||||
```bash
|
||||
openclaw browser start
|
||||
openclaw browser open https://x.com
|
||||
```
|
||||
|
||||
如果你有多个配置文件，传入 `--browser-profile <name>`（默认值为 `openclaw`）。
|
||||
|
||||
## X/Twitter：推荐流程
|
||||
|
||||
- **阅读/搜索/话题串：** 使用 **bird** CLI 技能（无需浏览器，稳定可靠）。
|
||||
- 仓库：https://github.com/steipete/bird
|
||||
- **发布更新：** 使用**宿主**浏览器（手动登录）。
|
||||
|
||||
## 沙箱 + 宿主浏览器访问
|
||||
|
||||
沙箱化的浏览器会话**更容易**触发机器人检测。对于 X/Twitter（及其他严格的网站），建议使用**宿主**浏览器。
|
||||
|
||||
如果智能体处于沙箱中，浏览器工具默认使用沙箱。要允许宿主控制：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
browser: {
|
||||
allowHostControl: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
然后指定宿主浏览器：
|
||||
|
||||
```bash
|
||||
openclaw browser open https://x.com --browser-profile openclaw --target host
|
||||
```
|
||||
|
||||
或者为发布更新的智能体禁用沙箱。
|
||||
542
docs/zh-CN/tools/browser.md
Normal file
542
docs/zh-CN/tools/browser.md
Normal file
@@ -0,0 +1,542 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加智能体控制的浏览器自动化
|
||||
- 调试 openclaw 为何干扰了你自己的 Chrome
|
||||
- 在 macOS 应用中实现浏览器设置 + 生命周期
|
||||
summary: 集成浏览器控制服务 + 操作命令
|
||||
title: 浏览器（OpenClaw 托管）
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:00Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 9f182ea9701becdd710a2d9ed0f481f6556c8e2611aab60ead27693924e4b8ca
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 浏览器（openclaw 托管）
|
||||
|
||||
OpenClaw 可以运行一个由智能体控制的**专用 Chrome/Brave/Edge/Chromium 配置文件**。
|
||||
它与你的个人浏览器隔离，通过 Gateway 内部的一个小型本地控制服务进行管理（仅限回环地址）。
|
||||
|
||||
初学者视角：
|
||||
|
||||
- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。
|
||||
- `openclaw` 配置文件**不会**影响你的个人浏览器配置文件。
|
||||
- 智能体可以在安全的通道中**打开标签页、读取页面、点击和输入**。
|
||||
- 默认的 `chrome` 配置文件通过扩展中继使用**系统默认的 Chromium 浏览器**；切换到 `openclaw` 以使用隔离的托管浏览器。
|
||||
|
||||
## 你能获得什么
|
||||
|
||||
- 一个名为 **openclaw** 的独立浏览器配置文件（默认为橙色主题）。
|
||||
- 确定性标签页控制（列出/打开/聚焦/关闭）。
|
||||
- 智能体操作（点击/输入/拖拽/选择）、快照、截图、PDF。
|
||||
- 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。
|
||||
|
||||
此浏览器**不是**你的日常浏览器。它是用于智能体自动化和验证的安全、隔离界面。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw status
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
如果出现 "Browser disabled"，请在配置中启用它（见下文）并重启 Gateway。
|
||||
|
||||
## 配置文件：`openclaw` 与 `chrome`
|
||||
|
||||
- `openclaw`：托管的隔离浏览器（无需扩展）。
|
||||
- `chrome`：通过本地中继连接到你的**系统浏览器**的扩展中继（需要将 OpenClaw 扩展附加到标签页）。
|
||||
|
||||
如果你希望默认使用托管模式，请设置 `browser.defaultProfile: "openclaw"`。
|
||||
|
||||
## 配置
|
||||
|
||||
浏览器设置位于 `~/.openclaw/openclaw.json`。
|
||||
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true, // 默认值：true
|
||||
// cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖
|
||||
remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒）
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
|
||||
defaultProfile: "chrome",
|
||||
color: "#FF4500",
|
||||
headless: false,
|
||||
noSandbox: false,
|
||||
attachOnly: false,
|
||||
executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
|
||||
profiles: {
|
||||
openclaw: { cdpPort: 18800, color: "#FF4500" },
|
||||
work: { cdpPort: 18801, color: "#0066CC" },
|
||||
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 浏览器控制服务绑定到回环地址的端口，该端口由 `gateway.port` 派生（默认值：`18791`，即 gateway + 2）。中继使用下一个端口（`18792`）。
|
||||
- 如果你覆盖了 Gateway 端口（`gateway.port` 或 `OPENCLAW_GATEWAY_PORT`），派生的浏览器端口会相应偏移以保持在同一"族"内。
|
||||
- `cdpUrl` 未设置时默认为中继端口。
|
||||
- `remoteCdpTimeoutMs` 适用于远程（非回环）CDP 可达性检查。
|
||||
- `remoteCdpHandshakeTimeoutMs` 适用于远程 CDP WebSocket 可达性检查。
|
||||
- `attachOnly: true` 表示"永远不启动本地浏览器；仅在已运行时附加"。
|
||||
- `color` + 每个配置文件的 `color` 为浏览器 UI 着色，以便你识别当前活动的配置文件。
|
||||
- 默认配置文件为 `chrome`（扩展中继）。使用 `defaultProfile: "openclaw"` 切换到托管浏览器。
|
||||
- 自动检测顺序：如果系统默认浏览器是基于 Chromium 的则使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 顺序查找。
|
||||
- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`——仅在远程 CDP 时才需要手动设置。
|
||||
|
||||
## 使用 Brave（或其他基于 Chromium 的浏览器）
|
||||
|
||||
如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），OpenClaw 会自动使用它。设置 `browser.executablePath` 来覆盖自动检测：
|
||||
|
||||
CLI 示例：
|
||||
|
||||
```bash
|
||||
openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
```
|
||||
|
||||
```json5
|
||||
// macOS
|
||||
{
|
||||
browser: {
|
||||
executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
|
||||
}
|
||||
}
|
||||
|
||||
// Windows
|
||||
{
|
||||
browser: {
|
||||
executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
|
||||
}
|
||||
}
|
||||
|
||||
// Linux
|
||||
{
|
||||
browser: {
|
||||
executablePath: "/usr/bin/brave-browser"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 本地控制与远程控制
|
||||
|
||||
- **本地控制（默认）：** Gateway 启动回环控制服务，并可启动本地浏览器。
|
||||
- **远程控制（节点主机）：** 在拥有浏览器的机器上运行节点主机；Gateway 将浏览器操作代理到该节点。
|
||||
- **远程 CDP：** 设置 `browser.profiles.<name>.cdpUrl`（或 `browser.cdpUrl`）以附加到远程基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。
|
||||
|
||||
远程 CDP URL 可以包含认证信息：
|
||||
|
||||
- 查询令牌（例如 `https://provider.example?token=<token>`）
|
||||
- HTTP Basic 认证（例如 `https://user:pass@provider.example`）
|
||||
|
||||
OpenClaw 在调用 `/json/*` 端点和连接 CDP WebSocket 时会保留认证信息。建议使用环境变量或密钥管理器存储令牌，而不是将其提交到配置文件中。
|
||||
|
||||
## 节点浏览器代理（零配置默认）
|
||||
|
||||
如果你在拥有浏览器的机器上运行了**节点主机**，OpenClaw 可以自动将浏览器工具调用路由到该节点，无需额外的浏览器配置。这是远程 Gateway 的默认路径。
|
||||
|
||||
说明：
|
||||
|
||||
- 节点主机通过**代理命令**暴露其本地浏览器控制服务。
|
||||
- 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。
|
||||
- 如果不需要可以禁用：
|
||||
- 在节点上：`nodeHost.browserProxy.enabled=false`
|
||||
- 在 Gateway 上：`gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless（托管远程 CDP）
|
||||
|
||||
[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。你可以将 OpenClaw 浏览器配置文件指向 Browserless 的区域端点，并使用 API 密钥进行认证。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true,
|
||||
defaultProfile: "browserless",
|
||||
remoteCdpTimeoutMs: 2000,
|
||||
remoteCdpHandshakeTimeoutMs: 4000,
|
||||
profiles: {
|
||||
browserless: {
|
||||
cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
|
||||
color: "#00AA00",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 将 `<BROWSERLESS_API_KEY>` 替换为你的真实 Browserless 令牌。
|
||||
- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。
|
||||
|
||||
## 安全性
|
||||
|
||||
核心要点：
|
||||
|
||||
- 浏览器控制仅限回环地址；访问通过 Gateway 的认证或节点配对进行。
|
||||
- 保持 Gateway 和所有节点主机在私有网络上（Tailscale）；避免公开暴露。
|
||||
- 将远程 CDP URL/令牌视为敏感信息；建议使用环境变量或密钥管理器。
|
||||
|
||||
远程 CDP 建议：
|
||||
|
||||
- 尽可能使用 HTTPS 端点和短期令牌。
|
||||
- 避免将长期有效的令牌直接嵌入配置文件中。
|
||||
|
||||
## 配置文件（多浏览器）
|
||||
|
||||
OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是：
|
||||
|
||||
- **openclaw 托管**：专用的基于 Chromium 的浏览器实例，拥有独立的用户数据目录 + CDP 端口
|
||||
- **远程**：显式的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
|
||||
- **扩展中继**：通过本地中继 + Chrome 扩展连接你现有的 Chrome 标签页
|
||||
|
||||
默认值：
|
||||
|
||||
- 如果缺少 `openclaw` 配置文件，会自动创建。
|
||||
- `chrome` 配置文件是内置的 Chrome 扩展中继（默认指向 `http://127.0.0.1:18792`）。
|
||||
- 本地 CDP 端口默认从 **18800–18899** 分配。
|
||||
- 删除配置文件会将其本地数据目录移至废纸篓。
|
||||
|
||||
所有控制端点接受 `?profile=<name>`；CLI 使用 `--browser-profile`。
|
||||
|
||||
## Chrome 扩展中继（使用你现有的 Chrome）
|
||||
|
||||
OpenClaw 也可以通过本地 CDP 中继 + Chrome 扩展驱动**你现有的 Chrome 标签页**（无需单独的 "openclaw" Chrome 实例）。
|
||||
|
||||
完整指南：[Chrome 扩展](/tools/chrome-extension)
|
||||
|
||||
流程：
|
||||
|
||||
- Gateway 在本地运行（同一台机器）或节点主机在浏览器所在机器上运行。
|
||||
- 本地**中继服务器**在回环 `cdpUrl` 上监听（默认：`http://127.0.0.1:18792`）。
|
||||
- 你点击标签页上的 **OpenClaw Browser Relay** 扩展图标以附加（不会自动附加）。
|
||||
- 智能体通过普通的 `browser` 工具控制该标签页，选择正确的配置文件即可。
|
||||
|
||||
如果 Gateway 在其他地方运行，请在浏览器所在机器上运行节点主机，以便 Gateway 可以代理浏览器操作。
|
||||
|
||||
### 沙箱会话
|
||||
|
||||
如果智能体会话处于沙箱中，`browser` 工具可能默认使用 `target="sandbox"`（沙箱浏览器）。
|
||||
Chrome 扩展中继接管需要宿主浏览器控制权，因此：
|
||||
|
||||
- 以非沙箱模式运行会话，或者
|
||||
- 设置 `agents.defaults.sandbox.browser.allowHostControl: true` 并在调用工具时使用 `target="host"`。
|
||||
|
||||
### 设置
|
||||
|
||||
1. 加载扩展（开发者/未打包模式）：
|
||||
|
||||
```bash
|
||||
openclaw browser extension install
|
||||
```
|
||||
|
||||
- Chrome → `chrome://extensions` → 启用"开发者模式"
|
||||
- "加载已解压的扩展程序" → 选择 `openclaw browser extension path` 输出的目录
|
||||
- 固定该扩展，然后在你想要控制的标签页上点击它（徽章显示 `ON`）。
|
||||
|
||||
2. 使用：
|
||||
|
||||
- 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"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 此模式依赖 Playwright-on-CDP 进行大部分操作（截图/快照/操作）。
|
||||
- 再次点击扩展图标即可断开。
|
||||
|
||||
## 隔离保证
|
||||
|
||||
- **专用用户数据目录**：绝不接触你的个人浏览器配置文件。
|
||||
- **专用端口**：避免使用 `9222` 以防止与开发工作流冲突。
|
||||
- **确定性标签页控制**：通过 `targetId` 定位标签页，而非"最后一个标签页"。
|
||||
|
||||
## 浏览器选择
|
||||
|
||||
在本地启动时，OpenClaw 按以下顺序选择第一个可用的：
|
||||
|
||||
1. Chrome
|
||||
2. Brave
|
||||
3. Edge
|
||||
4. Chromium
|
||||
5. Chrome Canary
|
||||
|
||||
你可以通过 `browser.executablePath` 覆盖。
|
||||
|
||||
各平台：
|
||||
|
||||
- macOS：检查 `/Applications` 和 `~/Applications`。
|
||||
- Linux：查找 `google-chrome`、`brave`、`microsoft-edge`、`chromium` 等。
|
||||
- Windows：检查常见安装位置。
|
||||
|
||||
## 控制 API（可选）
|
||||
|
||||
仅用于本地集成，Gateway 暴露一个小型回环 HTTP API：
|
||||
|
||||
- 状态/启动/停止：`GET /`、`POST /start`、`POST /stop`
|
||||
- 标签页：`GET /tabs`、`POST /tabs/open`、`POST /tabs/focus`、`DELETE /tabs/:targetId`
|
||||
- 快照/截图：`GET /snapshot`、`POST /screenshot`
|
||||
- 操作：`POST /navigate`、`POST /act`
|
||||
- 钩子：`POST /hooks/file-chooser`、`POST /hooks/dialog`
|
||||
- 下载：`POST /download`、`POST /wait/download`
|
||||
- 调试：`GET /console`、`POST /pdf`
|
||||
- 调试：`GET /errors`、`GET /requests`、`POST /trace/start`、`POST /trace/stop`、`POST /highlight`
|
||||
- 网络：`POST /response/body`
|
||||
- 状态：`GET /cookies`、`POST /cookies/set`、`POST /cookies/clear`
|
||||
- 状态：`GET /storage/:kind`、`POST /storage/:kind/set`、`POST /storage/:kind/clear`
|
||||
- 设置：`POST /set/offline`、`POST /set/headers`、`POST /set/credentials`、`POST /set/geolocation`、`POST /set/media`、`POST /set/timezone`、`POST /set/locale`、`POST /set/device`
|
||||
|
||||
所有端点接受 `?profile=<name>`。
|
||||
|
||||
### Playwright 要求
|
||||
|
||||
部分功能（导航/操作/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。ARIA 快照和基本截图在 openclaw 托管的 Chrome 上仍然可用。对于 Chrome 扩展中继驱动，ARIA 快照和截图需要 Playwright。
|
||||
|
||||
如果你看到 `Playwright is not available in this gateway build`，请安装完整的 Playwright 包（而非 `playwright-core`）并重启 Gateway，或者重新安装带浏览器支持的 OpenClaw。
|
||||
|
||||
## 工作原理（内部）
|
||||
|
||||
高层流程：
|
||||
|
||||
- 一个小型**控制服务器**接受 HTTP 请求。
|
||||
- 它通过 **CDP** 连接到基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）。
|
||||
- 对于高级操作（点击/输入/快照/PDF），它在 CDP 之上使用 **Playwright**。
|
||||
- 当缺少 Playwright 时，仅非 Playwright 操作可用。
|
||||
|
||||
这种设计使智能体保持在稳定、确定性的接口上，同时允许你切换本地/远程浏览器和配置文件。
|
||||
|
||||
## CLI 快速参考
|
||||
|
||||
所有命令接受 `--browser-profile <name>` 来指定配置文件。
|
||||
所有命令也接受 `--json` 来获取机器可读的输出（稳定的负载格式）。
|
||||
|
||||
基础操作：
|
||||
|
||||
- `openclaw browser status`
|
||||
- `openclaw browser start`
|
||||
- `openclaw browser stop`
|
||||
- `openclaw browser tabs`
|
||||
- `openclaw browser tab`
|
||||
- `openclaw browser tab new`
|
||||
- `openclaw browser tab select 2`
|
||||
- `openclaw browser tab close 2`
|
||||
- `openclaw browser open https://example.com`
|
||||
- `openclaw browser focus abcd1234`
|
||||
- `openclaw browser close abcd1234`
|
||||
|
||||
检查：
|
||||
|
||||
- `openclaw browser screenshot`
|
||||
- `openclaw browser screenshot --full-page`
|
||||
- `openclaw browser screenshot --ref 12`
|
||||
- `openclaw browser screenshot --ref e12`
|
||||
- `openclaw browser snapshot`
|
||||
- `openclaw browser snapshot --format aria --limit 200`
|
||||
- `openclaw browser snapshot --interactive --compact --depth 6`
|
||||
- `openclaw browser snapshot --efficient`
|
||||
- `openclaw browser snapshot --labels`
|
||||
- `openclaw browser snapshot --selector "#main" --interactive`
|
||||
- `openclaw browser snapshot --frame "iframe#main" --interactive`
|
||||
- `openclaw browser console --level error`
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
- `openclaw browser pdf`
|
||||
- `openclaw browser responsebody "**/api" --max-chars 5000`
|
||||
|
||||
操作：
|
||||
|
||||
- `openclaw browser navigate https://example.com`
|
||||
- `openclaw browser resize 1280 720`
|
||||
- `openclaw browser click 12 --double`
|
||||
- `openclaw browser click e12 --double`
|
||||
- `openclaw browser type 23 "hello" --submit`
|
||||
- `openclaw browser press Enter`
|
||||
- `openclaw browser hover 44`
|
||||
- `openclaw browser scrollintoview e12`
|
||||
- `openclaw browser drag 10 11`
|
||||
- `openclaw browser select 9 OptionA OptionB`
|
||||
- `openclaw browser download e12 /tmp/report.pdf`
|
||||
- `openclaw browser waitfordownload /tmp/report.pdf`
|
||||
- `openclaw browser upload /tmp/file.pdf`
|
||||
- `openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'`
|
||||
- `openclaw browser dialog --accept`
|
||||
- `openclaw browser wait --text "Done"`
|
||||
- `openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"`
|
||||
- `openclaw browser evaluate --fn '(el) => el.textContent' --ref 7`
|
||||
- `openclaw browser highlight e12`
|
||||
- `openclaw browser trace start`
|
||||
- `openclaw browser trace stop`
|
||||
|
||||
状态：
|
||||
|
||||
- `openclaw browser cookies`
|
||||
- `openclaw browser cookies set session abc123 --url "https://example.com"`
|
||||
- `openclaw browser cookies clear`
|
||||
- `openclaw browser storage local get`
|
||||
- `openclaw browser storage local set theme dark`
|
||||
- `openclaw browser storage session clear`
|
||||
- `openclaw browser set offline on`
|
||||
- `openclaw browser set headers --json '{"X-Debug":"1"}'`
|
||||
- `openclaw browser set credentials user pass`
|
||||
- `openclaw browser set credentials --clear`
|
||||
- `openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"`
|
||||
- `openclaw browser set geo --clear`
|
||||
- `openclaw browser set media dark`
|
||||
- `openclaw browser set timezone America/New_York`
|
||||
- `openclaw browser set locale en-US`
|
||||
- `openclaw browser set device "iPhone 14"`
|
||||
|
||||
说明：
|
||||
|
||||
- `upload` 和 `dialog` 是**预设**调用；在触发选择器/对话框的点击/按键之前运行它们。
|
||||
- `upload` 还可以通过 `--input-ref` 或 `--element` 直接设置文件输入。
|
||||
- `snapshot`：
|
||||
- `--format ai`（安装 Playwright 时的默认值）：返回带有数字引用（`aria-ref="<n>"`）的 AI 快照。
|
||||
- `--format aria`：返回无障碍树（无引用；仅供检查）。
|
||||
- `--efficient`（或 `--mode efficient`）：紧凑角色快照预设（交互式 + 紧凑 + 深度 + 更低的 maxChars）。
|
||||
- 配置默认值（仅限工具/CLI）：设置 `browser.snapshotDefaults.mode: "efficient"` 以在调用者未传递模式时使用高效快照（参见 [Gateway 配置](/gateway/configuration#browser-openclaw-managed-browser)）。
|
||||
- 角色快照选项（`--interactive`、`--compact`、`--depth`、`--selector`）强制使用基于角色的快照，引用格式如 `ref=e12`。
|
||||
- `--frame "<iframe 选择器>"` 将角色快照限定在 iframe 范围内（配合角色引用如 `e12` 使用）。
|
||||
- `--interactive` 输出扁平的、易于选取的交互式元素列表（最适合驱动操作）。
|
||||
- `--labels` 添加一个带有叠加引用标签的视口截图（输出 `MEDIA:<path>`）。
|
||||
- `click`/`type` 等需要来自 `snapshot` 的 `ref`（数字 `12` 或角色引用 `e12`）。
|
||||
操作有意不支持 CSS 选择器。
|
||||
|
||||
## 快照和引用
|
||||
|
||||
OpenClaw 支持两种"快照"风格：
|
||||
|
||||
- **AI 快照（数字引用）**：`openclaw browser snapshot`（默认；`--format ai`）
|
||||
- 输出：包含数字引用的文本快照。
|
||||
- 操作：`openclaw browser click 12`、`openclaw browser type 23 "hello"`。
|
||||
- 内部通过 Playwright 的 `aria-ref` 解析引用。
|
||||
|
||||
- **角色快照（角色引用如 `e12`）**：`openclaw browser snapshot --interactive`（或 `--compact`、`--depth`、`--selector`、`--frame`）
|
||||
- 输出：带有 `[ref=e12]`（以及可选的 `[nth=1]`）的基于角色的列表/树。
|
||||
- 操作：`openclaw browser click e12`、`openclaw browser highlight e12`。
|
||||
- 内部通过 `getByRole(...)` 解析引用（重复时加上 `nth()`）。
|
||||
- 添加 `--labels` 可包含带有叠加 `e12` 标签的视口截图。
|
||||
|
||||
引用行为：
|
||||
|
||||
- 引用在**页面导航后不稳定**；如果操作失败，重新运行 `snapshot` 并使用新的引用。
|
||||
- 如果角色快照使用了 `--frame`，角色引用将限定在该 iframe 范围内，直到下一次角色快照。
|
||||
|
||||
## 等待增强功能
|
||||
|
||||
你可以等待的不仅仅是时间/文本：
|
||||
|
||||
- 等待 URL（Playwright 支持通配符）：
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- 等待加载状态：
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- 等待 JS 谓词：
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- 等待选择器变为可见：
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
这些可以组合使用：
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
--url "**/dash" \
|
||||
--load networkidle \
|
||||
--fn "window.ready===true" \
|
||||
--timeout-ms 15000
|
||||
```
|
||||
|
||||
## 调试工作流
|
||||
|
||||
当操作失败时（例如 "not visible"、"strict mode violation"、"covered"）：
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. 使用 `click <ref>` / `type <ref>`（在交互模式下优先使用角色引用）
|
||||
3. 如果仍然失败：`openclaw browser highlight <ref>` 查看 Playwright 的定位目标
|
||||
4. 如果页面行为异常：
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. 深度调试：录制追踪：
|
||||
- `openclaw browser trace start`
|
||||
- 重现问题
|
||||
- `openclaw browser trace stop`（输出 `TRACE:<path>`）
|
||||
|
||||
## JSON 输出
|
||||
|
||||
`--json` 用于脚本和结构化工具。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
openclaw browser status --json
|
||||
openclaw browser snapshot --interactive --json
|
||||
openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
JSON 格式的角色快照包含 `refs` 以及一个小型 `stats` 块（行数/字符数/引用数/交互元素数），以便工具可以推理负载大小和密度。
|
||||
|
||||
## 状态和环境调节
|
||||
|
||||
这些对于"让网站表现得像 X"的工作流很有用：
|
||||
|
||||
- Cookies：`cookies`、`cookies set`、`cookies clear`
|
||||
- 存储：`storage local|session get|set|clear`
|
||||
- 离线：`set offline on|off`
|
||||
- 请求头：`set headers --json '{"X-Debug":"1"}'`（或 `--clear`）
|
||||
- HTTP 基本认证：`set credentials user pass`（或 `--clear`）
|
||||
- 地理位置：`set geo <lat> <lon> --origin "https://example.com"`（或 `--clear`）
|
||||
- 媒体：`set media dark|light|no-preference|none`
|
||||
- 时区 / 语言区域：`set timezone ...`、`set locale ...`
|
||||
- 设备 / 视口：
|
||||
- `set device "iPhone 14"`（Playwright 设备预设）
|
||||
- `set viewport 1280 720`
|
||||
|
||||
## 安全与隐私
|
||||
|
||||
- openclaw 浏览器配置文件可能包含已登录的会话；请将其视为敏感数据。
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` 和 `wait --fn` 在页面上下文中执行任意 JavaScript。提示注入可能操纵此功能。如果不需要，请通过 `browser.evaluateEnabled=false` 禁用。
|
||||
- 有关登录和反机器人注意事项（X/Twitter 等），请参阅[浏览器登录 + X/Twitter 发帖](/tools/browser-login)。
|
||||
- 保持 Gateway/节点主机为私有（仅限回环地址或 tailnet）。
|
||||
- 远程 CDP 端点功能强大；请通过隧道保护它们。
|
||||
|
||||
## 故障排除
|
||||
|
||||
有关 Linux 特定问题（特别是 snap 版 Chromium），请参阅[浏览器故障排除](/tools/browser-linux-troubleshooting)。
|
||||
|
||||
## 智能体工具 + 控制工作原理
|
||||
|
||||
智能体获得**一个工具**用于浏览器自动化：
|
||||
|
||||
- `browser` — 状态/启动/停止/标签页/打开/聚焦/关闭/快照/截图/导航/操作
|
||||
|
||||
映射方式：
|
||||
|
||||
- `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。
|
||||
- `browser act` 使用快照 `ref` ID 来点击/输入/拖拽/选择。
|
||||
- `browser screenshot` 捕获像素（整页或元素）。
|
||||
- `browser` 接受：
|
||||
- `profile` 来选择命名的浏览器配置文件（openclaw、chrome 或远程 CDP）。
|
||||
- `target`（`sandbox` | `host` | `node`）来选择浏览器所在位置。
|
||||
- 在沙箱会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。
|
||||
- 如果省略 `target`：沙箱会话默认为 `sandbox`，非沙箱会话默认为 `host`。
|
||||
- 如果连接了支持浏览器的节点，工具可能会自动路由到该节点，除非你指定 `target="host"` 或 `target="node"`。
|
||||
|
||||
这使智能体保持确定性，避免脆弱的选择器。
|
||||
185
docs/zh-CN/tools/chrome-extension.md
Normal file
185
docs/zh-CN/tools/chrome-extension.md
Normal file
@@ -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）
|
||||
- **本地中继服务器**（回环 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 在同一台机器上运行，它会在回环地址上启动浏览器控制服务
|
||||
并自动启动中继服务器。扩展与本地中继通信；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)
|
||||
209
docs/zh-CN/tools/clawhub.md
Normal file
209
docs/zh-CN/tools/clawhub.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
read_when:
|
||||
- 向新用户介绍 ClawHub
|
||||
- 安装、搜索或发布技能
|
||||
- 说明 ClawHub CLI 标志和同步行为
|
||||
summary: ClawHub 指南：公共技能注册中心 + 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 的公共技能注册中心**。它是一项免费服务：所有技能都是公开的、开放的，所有人都可以查看、共享和复用。技能就是一个包含 `SKILL.md` 文件（以及辅助文本文件）的文件夹。你可以在网页应用中浏览技能，也可以使用 CLI 来搜索、安装、更新和发布技能。
|
||||
|
||||
网站：[clawhub.com](https://clawhub.com)
|
||||
|
||||
## 适用人群（新手友好）
|
||||
|
||||
如果你想为 OpenClaw 智能体添加新功能，ClawHub 是查找和安装技能的最简单方式。你不需要了解后端的工作原理。你可以：
|
||||
|
||||
- 使用自然语言搜索技能。
|
||||
- 将技能安装到你的工作区。
|
||||
- 之后使用一条命令更新技能。
|
||||
- 通过发布技能来备份你自己的技能。
|
||||
|
||||
## 快速入门（非技术人员）
|
||||
|
||||
1. 安装 CLI（参见下一节）。
|
||||
2. 搜索你需要的内容：
|
||||
- `clawhub search "calendar"`
|
||||
3. 安装一个技能：
|
||||
- `clawhub install <skill-slug>`
|
||||
4. 启动一个新的 OpenClaw 会话，以加载新技能。
|
||||
|
||||
## 安装 CLI
|
||||
|
||||
任选其一：
|
||||
|
||||
```bash
|
||||
npm i -g clawhub
|
||||
```
|
||||
|
||||
```bash
|
||||
pnpm add -g clawhub
|
||||
```
|
||||
|
||||
## 在 OpenClaw 中的定位
|
||||
|
||||
默认情况下，CLI 会将技能安装到当前工作目录下的 `./skills`。如果已配置 OpenClaw 工作区，`clawhub` 会回退到该工作区，除非你通过 `--workdir`（或 `CLAWHUB_WORKDIR`）进行覆盖。OpenClaw 从 `<workspace>/skills` 加载工作区技能，并会在**下一个**会话中生效。如果你已经在使用 `~/.openclaw/skills` 或内置技能，工作区技能优先级更高。
|
||||
|
||||
有关技能加载、共享和权限控制的更多详情，请参阅
|
||||
[技能](/tools/skills)。
|
||||
|
||||
## 服务功能
|
||||
|
||||
- **公开浏览**技能及其 `SKILL.md` 内容。
|
||||
- 基于嵌入向量（向量搜索）的**搜索**，而不仅仅是关键词匹配。
|
||||
- 支持语义化版本号、变更日志和标签（包括 `latest`）的**版本管理**。
|
||||
- 每个版本以 zip 格式**下载**。
|
||||
- **星标和评论**，支持社区反馈。
|
||||
- **审核**钩子，用于审批和审计。
|
||||
- **CLI 友好的 API**，支持自动化和脚本编写。
|
||||
|
||||
## CLI 命令和参数
|
||||
|
||||
全局选项（适用于所有命令）：
|
||||
|
||||
- `--workdir <dir>`：工作目录（默认：当前目录；回退到 OpenClaw 工作区）。
|
||||
- `--dir <dir>`：技能目录，相对于工作目录（默认：`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>`：技能标识符。
|
||||
- `--name <name>`：显示名称。
|
||||
- `--version <version>`：语义化版本号。
|
||||
- `--changelog <text>`：变更日志文本（可以为空）。
|
||||
- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
|
||||
|
||||
删除/恢复（仅所有者/管理员）：
|
||||
|
||||
- `clawhub delete <slug> --yes`
|
||||
- `clawhub undelete <slug> --yes`
|
||||
|
||||
同步（扫描本地技能 + 发布新增/更新的技能）：
|
||||
|
||||
- `clawhub sync`
|
||||
- `--root <dir...>`：额外的扫描根目录。
|
||||
- `--all`：无提示上传所有内容。
|
||||
- `--dry-run`：显示将要上传的内容。
|
||||
- `--bump <type>`：更新的版本号递增类型 `patch|minor|major`（默认：`patch`）。
|
||||
- `--changelog <text>`：非交互更新的变更日志。
|
||||
- `--tags <tags>`：逗号分隔的标签（默认：`latest`）。
|
||||
- `--concurrency <n>`：注册中心检查并发数（默认：4）。
|
||||
|
||||
## 智能体常用工作流
|
||||
|
||||
### 搜索技能
|
||||
|
||||
```bash
|
||||
clawhub search "postgres backups"
|
||||
```
|
||||
|
||||
### 下载新技能
|
||||
|
||||
```bash
|
||||
clawhub install my-skill-pack
|
||||
```
|
||||
|
||||
### 更新已安装的技能
|
||||
|
||||
```bash
|
||||
clawhub update --all
|
||||
```
|
||||
|
||||
### 备份你的技能（发布或同步）
|
||||
|
||||
对于单个技能文件夹：
|
||||
|
||||
```bash
|
||||
clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
|
||||
```
|
||||
|
||||
一次扫描并备份多个技能：
|
||||
|
||||
```bash
|
||||
clawhub sync --all
|
||||
```
|
||||
|
||||
## 高级详情（技术性）
|
||||
|
||||
### 版本管理和标签
|
||||
|
||||
- 每次发布都会创建一个新的**语义化版本** `SkillVersion`。
|
||||
- 标签（如 `latest`）指向某个版本；移动标签可以实现回滚。
|
||||
- 变更日志附加在每个版本上，在同步或发布更新时可以为空。
|
||||
|
||||
### 本地更改与注册中心版本
|
||||
|
||||
更新时会使用内容哈希将本地技能内容与注册中心版本进行比较。如果本地文件与任何已发布版本不匹配，CLI 会在覆盖前询问确认（或在非交互模式下需要 `--force`）。
|
||||
|
||||
### 同步扫描和回退根目录
|
||||
|
||||
`clawhub sync` 首先扫描当前工作目录。如果未找到技能，它会回退到已知的旧版位置（例如 `~/openclaw/skills` 和 `~/.openclaw/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` 的遥测功能。
|
||||
61
docs/zh-CN/tools/creating-skills.md
Normal file
61
docs/zh-CN/tools/creating-skills.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: 创建技能
|
||||
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
|
||||
---
|
||||
|
||||
# 创建自定义技能 🛠
|
||||
|
||||
OpenClaw 的设计易于扩展。"技能"是为你的助手添加新功能的主要方式。
|
||||
|
||||
## 什么是技能？
|
||||
|
||||
技能是一个包含 `SKILL.md` 文件（为 LLM 提供指令和工具定义）的目录，还可以选择性地包含一些脚本或资源。
|
||||
|
||||
## 分步指南：你的第一个技能
|
||||
|
||||
### 1. 创建目录
|
||||
|
||||
技能存放在你的工作区中，通常位于 `~/.openclaw/workspace/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
|
||||
|
||||
让你的智能体"刷新技能"或重启 Gateway。OpenClaw 将发现新目录并索引 `SKILL.md`。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **保持简洁**：指示模型应该做*什么*，而不是如何成为一个 AI。
|
||||
- **安全第一**：如果你的技能使用 `bash`，请确保提示不会允许来自不受信任用户输入的任意命令注入。
|
||||
- **本地测试**：使用 `openclaw agent --message "use my new skill"` 进行测试。
|
||||
|
||||
## 共享技能
|
||||
|
||||
你还可以在 [ClawHub](https://clawhub.com) 上浏览和贡献技能。
|
||||
64
docs/zh-CN/tools/elevated.md
Normal file
64
docs/zh-CN/tools/elevated.md
Normal file
@@ -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`）。
|
||||
233
docs/zh-CN/tools/exec-approvals.md
Normal file
233
docs/zh-CN/tools/exec-approvals.md
Normal file
@@ -0,0 +1,233 @@
|
||||
---
|
||||
read_when:
|
||||
- 配置执行审批或允许列表
|
||||
- 在 macOS 应用中实现执行审批用户体验
|
||||
- 审查沙箱逃逸提示及其影响
|
||||
summary: 执行审批、允许列表和沙箱逃逸提示
|
||||
title: 执行审批
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:40Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: ed17aab60b1f9c797ea8e9143d39d3a500c7b8cad4ea4b7903fedbf799339d28
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 执行审批
|
||||
|
||||
执行审批是**伴侣应用 / 节点主机的安全护栏**，用于允许沙箱化的智能体在真实主机（`gateway` 或 `node`）上运行命令。可以将其理解为一种安全联锁机制：只有当策略 + 允许列表 +（可选的）用户审批全部通过时，命令才会被允许执行。
|
||||
执行审批是在工具策略和提权网关**之上**的额外检查（除非提权设置为 `full`，此时会跳过审批）。
|
||||
生效策略取 `tools.exec.*` 和审批默认值中**更严格**的一个；如果审批字段被省略，则使用 `tools.exec` 的值。
|
||||
|
||||
如果伴侣应用 UI **不可用**，任何需要提示的请求将由 **ask 回退策略**（默认：deny）来决定。
|
||||
|
||||
## 适用范围
|
||||
|
||||
执行审批在执行主机上本地强制执行：
|
||||
|
||||
- **Gateway 主机** → Gateway 机器上的 `openclaw` 进程
|
||||
- **节点主机** → 节点运行器（macOS 伴侣应用或无头节点主机）
|
||||
|
||||
macOS 拆分：
|
||||
|
||||
- **节点主机服务**通过本地 IPC 将 `system.run` 转发至 **macOS 应用**。
|
||||
- **macOS 应用**强制执行审批并在 UI 上下文中执行命令。
|
||||
|
||||
## 设置与存储
|
||||
|
||||
审批配置存储在执行主机上的本地 JSON 文件中：
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
|
||||
示例结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"socket": {
|
||||
"path": "~/.openclaw/exec-approvals.sock",
|
||||
"token": "base64url-token"
|
||||
},
|
||||
"defaults": {
|
||||
"security": "deny",
|
||||
"ask": "on-miss",
|
||||
"askFallback": "deny",
|
||||
"autoAllowSkills": false
|
||||
},
|
||||
"agents": {
|
||||
"main": {
|
||||
"security": "allowlist",
|
||||
"ask": "on-miss",
|
||||
"askFallback": "deny",
|
||||
"autoAllowSkills": true,
|
||||
"allowlist": [
|
||||
{
|
||||
"id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
|
||||
"pattern": "~/Projects/**/bin/rg",
|
||||
"lastUsedAt": 1737150000000,
|
||||
"lastUsedCommand": "rg -n TODO",
|
||||
"lastResolvedPath": "/Users/user/Projects/.../bin/rg"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 策略选项
|
||||
|
||||
### 安全级别（`exec.security`）
|
||||
|
||||
- **deny**：阻止所有主机执行请求。
|
||||
- **allowlist**：仅允许在允许列表中的命令。
|
||||
- **full**：允许所有命令（等同于提权模式）。
|
||||
|
||||
### 询问（`exec.ask`）
|
||||
|
||||
- **off**：从不提示。
|
||||
- **on-miss**：仅在允许列表未匹配时提示。
|
||||
- **always**：每次命令都提示。
|
||||
|
||||
### 询问回退（`askFallback`）
|
||||
|
||||
如果需要提示但无法连接到 UI，则由回退策略决定：
|
||||
|
||||
- **deny**：阻止。
|
||||
- **allowlist**：仅在允许列表匹配时放行。
|
||||
- **full**：放行。
|
||||
|
||||
## 允许列表（按智能体）
|
||||
|
||||
允许列表是**按智能体**配置的。如果存在多个智能体，可以在 macOS 应用中切换要编辑的智能体。匹配模式为**不区分大小写的 glob 匹配**。
|
||||
模式应解析为**二进制路径**（仅包含基础名的条目会被忽略）。
|
||||
旧版 `agents.default` 条目在加载时会被迁移到 `agents.main`。
|
||||
|
||||
示例：
|
||||
|
||||
- `~/Projects/**/bin/bird`
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
每个允许列表条目跟踪以下信息：
|
||||
|
||||
- **id** 用于 UI 标识的稳定 UUID（可选）
|
||||
- **最近使用**时间戳
|
||||
- **最近使用的命令**
|
||||
- **最近解析的路径**
|
||||
|
||||
## 自动允许技能 CLI
|
||||
|
||||
启用**自动允许技能 CLI** 后，已知技能引用的可执行文件在节点上（macOS 节点或无头节点主机）会被视为已列入允许列表。此功能通过 Gateway RPC 的 `skills.bins` 获取技能二进制列表。如果需要严格的手动允许列表，请禁用此选项。
|
||||
|
||||
## 安全二进制（仅限标准输入）
|
||||
|
||||
`tools.exec.safeBins` 定义了一小组**仅限标准输入**的二进制文件（例如 `jq`），它们可以在允许列表模式下运行，**无需**显式添加到允许列表中。安全二进制会拒绝位置文件参数和类路径标记，因此只能操作传入的数据流。
|
||||
Shell 链式调用和重定向在允许列表模式下不会被自动允许。
|
||||
|
||||
当每个顶层段都满足允许列表（包括安全二进制或技能自动允许）时，Shell 链式调用（`&&`、`||`、`;`）是被允许的。重定向在允许列表模式下仍不受支持。
|
||||
|
||||
默认安全二进制：`jq`、`grep`、`cut`、`sort`、`uniq`、`head`、`tail`、`tr`、`wc`。
|
||||
|
||||
## 控制 UI 编辑
|
||||
|
||||
使用**控制 UI → 节点 → 执行审批**卡片来编辑默认值、按智能体的覆盖配置和允许列表。选择一个范围（默认值或某个智能体），调整策略，添加/删除允许列表模式，然后点击**保存**。UI 会显示每个模式的**最近使用**元数据，方便你保持列表整洁。
|
||||
|
||||
目标选择器可选择 **Gateway**（本地审批）或**节点**。节点必须广播 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
|
||||
如果某个节点尚未广播执行审批功能，请直接编辑其本地的 `~/.openclaw/exec-approvals.json` 文件。
|
||||
|
||||
CLI：`openclaw approvals` 支持 Gateway 或节点编辑（参见 [审批 CLI](/cli/approvals)）。
|
||||
|
||||
## 审批流程
|
||||
|
||||
当需要提示时，Gateway 向操作员客户端广播 `exec.approval.requested`。
|
||||
控制 UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 Gateway 将已批准的请求转发至节点主机。
|
||||
|
||||
当需要审批时，执行工具会立即返回一个审批 ID。使用该 ID 来关联后续的系统事件（`Exec finished` / `Exec denied`）。如果在超时前未收到决定，该请求将被视为审批超时并以拒绝原因呈现。
|
||||
|
||||
确认对话框包含：
|
||||
|
||||
- 命令 + 参数
|
||||
- 工作目录
|
||||
- 智能体 ID
|
||||
- 解析后的可执行文件路径
|
||||
- 主机 + 策略元数据
|
||||
|
||||
操作：
|
||||
|
||||
- **允许一次** → 立即运行
|
||||
- **始终允许** → 添加到允许列表并运行
|
||||
- **拒绝** → 阻止
|
||||
|
||||
## 审批转发至聊天渠道
|
||||
|
||||
你可以将执行审批提示转发到任何聊天渠道（包括插件渠道），并通过 `/approve` 进行审批。此功能使用常规的出站投递管道。
|
||||
|
||||
配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
approvals: {
|
||||
exec: {
|
||||
enabled: true,
|
||||
mode: "session", // "session" | "targets" | "both"
|
||||
agentFilter: ["main"],
|
||||
sessionFilter: ["discord"], // 子串或正则表达式
|
||||
targets: [
|
||||
{ channel: "slack", to: "U12345678" },
|
||||
{ channel: "telegram", to: "123456789" },
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
在聊天中回复：
|
||||
|
||||
```
|
||||
/approve <id> allow-once
|
||||
/approve <id> allow-always
|
||||
/approve <id> deny
|
||||
```
|
||||
|
||||
### macOS IPC 流程
|
||||
|
||||
```
|
||||
Gateway -> Node Service (WS)
|
||||
| IPC (UDS + token + HMAC + TTL)
|
||||
v
|
||||
Mac App (UI + approvals + system.run)
|
||||
```
|
||||
|
||||
安全说明：
|
||||
|
||||
- Unix 套接字模式 `0600`，令牌存储在 `exec-approvals.json` 中。
|
||||
- 同 UID 对端检查。
|
||||
- 质询/响应（nonce + HMAC 令牌 + 请求哈希）+ 短 TTL。
|
||||
|
||||
## 系统事件
|
||||
|
||||
执行生命周期以系统消息形式呈现：
|
||||
|
||||
- `Exec running`（仅当命令超过运行通知阈值时）
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
这些消息在节点报告事件后发布到智能体的会话中。
|
||||
Gateway 主机执行审批在命令完成时（以及可选地在运行时间超过阈值时）发出相同的生命周期事件。
|
||||
经过审批网关的执行会复用审批 ID 作为这些消息中的 `runId`，便于关联。
|
||||
|
||||
## 影响
|
||||
|
||||
- **full** 权限很大；尽可能使用允许列表。
|
||||
- **ask** 让你保持知情，同时仍允许快速审批。
|
||||
- 按智能体的允许列表可防止一个智能体的审批泄漏到其他智能体。
|
||||
- 审批仅适用于来自**授权发送者**的主机执行请求。未授权的发送者无法发出 `/exec`。
|
||||
- `/exec security=full` 是面向授权操作员的会话级便捷功能，设计上会跳过审批。
|
||||
要彻底阻止主机执行，请将审批安全级别设为 `deny`，或通过工具策略拒绝 `exec` 工具。
|
||||
|
||||
相关内容：
|
||||
|
||||
- [执行工具](/tools/exec)
|
||||
- [提权模式](/tools/elevated)
|
||||
- [技能](/tools/skills)
|
||||
168
docs/zh-CN/tools/exec.md
Normal file
168
docs/zh-CN/tools/exec.md
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
read_when:
|
||||
- 使用或修改 exec 工具时
|
||||
- 调试标准输入或 TTY 行为时
|
||||
summary: Exec 工具用法、标准输入模式与 TTY 支持
|
||||
title: Exec 工具
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:35Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 0d515b6039b43f7923b8cc6cd63717e3d029128e523b06c78003ca8077c20a21
|
||||
source_path: tools/exec.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Exec 工具
|
||||
|
||||
在工作区中运行 shell 命令。通过 `process` 支持前台和后台执行。
|
||||
如果 `process` 被禁用，`exec` 将同步运行并忽略 `yieldMs`/`background`。
|
||||
后台会话按智能体隔离；`process` 只能查看同一智能体的会话。
|
||||
|
||||
## 参数
|
||||
|
||||
- `command`（必填）
|
||||
- `workdir`（默认为当前工作目录）
|
||||
- `env`（键/值覆盖）
|
||||
- `yieldMs`（默认 10000）：延迟后自动转为后台运行
|
||||
- `background`（布尔值）：立即转为后台运行
|
||||
- `timeout`（秒，默认 1800）：超时后终止
|
||||
- `pty`（布尔值）：在可用时使用伪终端运行（仅 TTY 的 CLI、编程智能体、终端 UI）
|
||||
- `host`（`sandbox | gateway | node`）：执行位置
|
||||
- `security`（`deny | allowlist | full`）：`gateway`/`node` 的执行策略模式
|
||||
- `ask`（`off | on-miss | always`）：`gateway`/`node` 的审批提示
|
||||
- `node`（字符串）：`host=node` 时的节点 ID/名称
|
||||
- `elevated`（布尔值）：请求提权模式（gateway 主机）；仅当提权解析为 `full` 时才强制 `security=full`
|
||||
|
||||
说明：
|
||||
|
||||
- `host` 默认为 `sandbox`。
|
||||
- 当沙箱关闭时，`elevated` 被忽略（exec 已直接在主机上运行）。
|
||||
- `gateway`/`node` 的审批由 `~/.openclaw/exec-approvals.json` 控制。
|
||||
- `node` 需要已配对的节点（伴侣应用或无头节点主机）。
|
||||
- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择一个。
|
||||
- 在非 Windows 主机上，exec 在设置了 `SHELL` 时使用该 shell；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免 fish 不兼容的脚本，如果两者都不存在则回退到 `SHELL`。
|
||||
- 重要：沙箱**默认关闭**。如果沙箱关闭，`host=sandbox` 将直接在 Gateway 主机上运行（无容器）且**不需要审批**。要启用审批，请使用 `host=gateway` 并配置 exec 审批（或启用沙箱）。
|
||||
|
||||
## 配置
|
||||
|
||||
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，后台 exec 会话在退出时会排入系统事件并请求心跳。
|
||||
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行超过此时间时，发出一条"运行中"通知（设为 0 禁用）。
|
||||
- `tools.exec.host`（默认：`sandbox`）
|
||||
- `tools.exec.security`（默认：sandbox 为 `deny`，未设置时 gateway + node 为 `allowlist`）
|
||||
- `tools.exec.ask`（默认：`on-miss`）
|
||||
- `tools.exec.node`（默认：未设置）
|
||||
- `tools.exec.pathPrepend`：exec 运行时要添加到 `PATH` 前面的目录列表。
|
||||
- `tools.exec.safeBins`：仅通过标准输入的安全二进制文件，无需显式添加到允许列表即可运行。
|
||||
|
||||
示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
exec: {
|
||||
pathPrepend: ["~/bin", "/opt/oss/bin"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### PATH 处理
|
||||
|
||||
- `host=gateway`：将您的登录 shell `PATH` 合并到 exec 环境中（除非 exec 调用已设置 `env.PATH`）。守护进程本身仍使用最小 `PATH` 运行：
|
||||
- macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。OpenClaw 在 profile 加载后通过内部环境变量添加 `env.PATH`（无 shell 插值）；`tools.exec.pathPrepend` 在此同样适用。
|
||||
- `host=node`：仅发送您传递的 env 覆盖到节点。`tools.exec.pathPrepend` 仅在 exec 调用已设置 `env.PATH` 时适用。无头节点主机仅在 `PATH` 为节点主机 PATH 前缀时接受 `PATH` 覆盖（不支持替换）。macOS 节点完全忽略 `PATH` 覆盖。
|
||||
|
||||
按智能体绑定节点（在配置中使用智能体列表索引）：
|
||||
|
||||
```bash
|
||||
openclaw config get agents.list
|
||||
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
```
|
||||
|
||||
控制界面：节点选项卡包含一个"Exec 节点绑定"面板，用于相同的设置。
|
||||
|
||||
## 会话覆盖（`/exec`）
|
||||
|
||||
使用 `/exec` 设置 `host`、`security`、`ask` 和 `node` 的**按会话**默认值。
|
||||
不带参数发送 `/exec` 可查看当前值。
|
||||
|
||||
示例：
|
||||
|
||||
```
|
||||
/exec host=gateway security=allowlist ask=on-miss node=mac-1
|
||||
```
|
||||
|
||||
## 授权模型
|
||||
|
||||
`/exec` 仅对**已授权的发送者**生效（渠道允许列表/配对加 `commands.useAccessGroups`）。
|
||||
它仅更新**会话状态**，不会写入配置。要彻底禁用 exec，请通过工具策略拒绝它（`tools.deny: ["exec"]` 或按智能体设置）。除非您显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。
|
||||
|
||||
## Exec 审批（伴侣应用 / 节点主机）
|
||||
|
||||
沙箱化的智能体可以要求在 `exec` 于 Gateway 或节点主机上运行前进行逐次审批。
|
||||
请参阅 [Exec 审批](/tools/exec-approvals) 了解策略、允许列表和 UI 流程。
|
||||
|
||||
当需要审批时，exec 工具会立即返回 `status: "approval-pending"` 和一个审批 ID。一旦被批准（或拒绝/超时），Gateway 会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 `tools.exec.approvalRunningNoticeMs` 之后仍在运行，会发出一条 `Exec running` 通知。
|
||||
|
||||
## 允许列表与安全二进制文件
|
||||
|
||||
允许列表执行仅匹配**已解析的二进制文件路径**（不匹配基本名称）。当 `security=allowlist` 时，shell 命令仅在每个管道段都在允许列表中或属于安全二进制文件时才会自动放行。在允许列表模式下，链式操作（`;`、`&&`、`||`）和重定向会被拒绝。
|
||||
|
||||
## 示例
|
||||
|
||||
前台：
|
||||
|
||||
```json
|
||||
{ "tool": "exec", "command": "ls -la" }
|
||||
```
|
||||
|
||||
后台 + 轮询：
|
||||
|
||||
```json
|
||||
{"tool":"exec","command":"npm run build","yieldMs":1000}
|
||||
{"tool":"process","action":"poll","sessionId":"<id>"}
|
||||
```
|
||||
|
||||
发送按键（tmux 风格）：
|
||||
|
||||
```json
|
||||
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
|
||||
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
|
||||
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
|
||||
```
|
||||
|
||||
提交（仅发送回车）：
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
|
||||
```
|
||||
|
||||
粘贴（默认带括号标记）：
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
|
||||
```
|
||||
|
||||
## apply_patch（实验性）
|
||||
|
||||
`apply_patch` 是 `exec` 的子工具，用于结构化的多文件编辑。
|
||||
需显式启用：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
exec: {
|
||||
applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 仅适用于 OpenAI/OpenAI Codex 模型。
|
||||
- 工具策略仍然适用；`allow: ["exec"]` 隐式允许 `apply_patch`。
|
||||
- 配置位于 `tools.exec.applyPatch` 下。
|
||||
65
docs/zh-CN/tools/firecrawl.md
Normal file
65
docs/zh-CN/tools/firecrawl.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要基于 Firecrawl 的网页提取
|
||||
- 你需要 Firecrawl API 密钥
|
||||
- 你需要为 web_fetch 提供反爬虫提取功能
|
||||
summary: Firecrawl 作为 web_fetch 的备用方案（反爬虫 + 缓存提取）
|
||||
title: Firecrawl
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:22Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 08a7ad45b41af41204e44d2b0be0f980b7184d80d2fa3977339e42a47beb2851
|
||||
source_path: tools/firecrawl.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Firecrawl
|
||||
|
||||
OpenClaw 可以使用 **Firecrawl** 作为 `web_fetch` 的备用提取器。它是一个托管的内容提取服务，支持反爬虫绕过和缓存，有助于处理 JS 密集型网站或阻止普通 HTTP 请求的页面。
|
||||
|
||||
## 获取 API 密钥
|
||||
|
||||
1. 创建 Firecrawl 账户并生成 API 密钥。
|
||||
2. 将其存储在配置中，或在 Gateway 环境中设置 `FIRECRAWL_API_KEY`。
|
||||
|
||||
## 配置 Firecrawl
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
web: {
|
||||
fetch: {
|
||||
firecrawl: {
|
||||
apiKey: "FIRECRAWL_API_KEY_HERE",
|
||||
baseUrl: "https://api.firecrawl.dev",
|
||||
onlyMainContent: true,
|
||||
maxAgeMs: 172800000,
|
||||
timeoutSeconds: 60,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意事项：
|
||||
|
||||
- 当存在 API 密钥时，`firecrawl.enabled` 默认为 true。
|
||||
- `maxAgeMs` 控制缓存结果的最大有效时长（毫秒）。默认为 2 天。
|
||||
|
||||
## 隐身/反爬虫绕过
|
||||
|
||||
Firecrawl 提供了一个用于反爬虫绕过的**代理模式**参数（`basic`、`stealth` 或 `auto`）。
|
||||
OpenClaw 对 Firecrawl 请求始终使用 `proxy: "auto"` 加上 `storeInCache: true`。
|
||||
如果省略 proxy，Firecrawl 默认使用 `auto`。`auto` 模式在基本尝试失败后会使用隐身代理重试，这可能比仅使用基本模式的抓取消耗更多积分。
|
||||
|
||||
## `web_fetch` 如何使用 Firecrawl
|
||||
|
||||
`web_fetch` 提取顺序：
|
||||
|
||||
1. Readability（本地）
|
||||
2. Firecrawl（如已配置）
|
||||
3. 基本 HTML 清理（最终备用方案）
|
||||
|
||||
参阅[网页工具](/tools/web)了解完整的网页工具设置。
|
||||
513
docs/zh-CN/tools/index.md
Normal file
513
docs/zh-CN/tools/index.md
Normal file
@@ -0,0 +1,513 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改智能体工具
|
||||
- 停用或更改 `openclaw-*` 技能
|
||||
summary: OpenClaw 的智能体工具集（browser、canvas、nodes、message、cron），替代旧版 `openclaw-*` 技能
|
||||
title: 工具
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:44:06Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: a1ec62a9c9bea4c1d2cebfb88509739a3b48b451ab3e378193c620832e2aa07b
|
||||
source_path: tools/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 工具（OpenClaw）
|
||||
|
||||
OpenClaw 提供**一等智能体工具**，涵盖 browser、canvas、nodes 和 cron。
|
||||
这些工具替代了旧的 `openclaw-*` 技能：工具是类型化的，无需 shell 调用，
|
||||
智能体应直接依赖这些工具。
|
||||
|
||||
## 禁用工具
|
||||
|
||||
你可以通过 `openclaw.json` 中的 `tools.allow` / `tools.deny` 全局允许/拒绝工具
|
||||
（deny 优先）。这会阻止被拒绝的工具发送给模型提供商。
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: { deny: ["browser"] },
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 匹配不区分大小写。
|
||||
- 支持 `*` 通配符（`"*"` 表示所有工具）。
|
||||
- 如果 `tools.allow` 仅引用了未知或未加载的插件工具名称，OpenClaw 会记录警告并忽略允许列表，以确保核心工具保持可用。
|
||||
|
||||
## 工具配置文件（基础允许列表）
|
||||
|
||||
`tools.profile` 在 `tools.allow`/`tools.deny` 之前设置**基础工具允许列表**。
|
||||
每智能体覆盖：`agents.list[].tools.profile`。
|
||||
|
||||
配置文件：
|
||||
|
||||
- `minimal`：仅 `session_status`
|
||||
- `coding`：`group:fs`、`group:runtime`、`group:sessions`、`group:memory`、`image`
|
||||
- `messaging`：`group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status`
|
||||
- `full`：无限制（与未设置相同）
|
||||
|
||||
示例（默认仅消息，同时允许 Slack + Discord 工具）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
profile: "messaging",
|
||||
allow: ["slack", "discord"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
示例（coding 配置文件，但全局拒绝 exec/process）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
profile: "coding",
|
||||
deny: ["group:runtime"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
示例（全局 coding 配置文件，仅消息的支持智能体）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: { profile: "coding" },
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "support",
|
||||
tools: { profile: "messaging", allow: ["slack"] },
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 按提供商的工具策略
|
||||
|
||||
使用 `tools.byProvider` 为特定提供商（或单个 `provider/model`）**进一步限制**工具，
|
||||
而不更改全局默认值。
|
||||
每智能体覆盖：`agents.list[].tools.byProvider`。
|
||||
|
||||
此策略在基础工具配置文件**之后**、allow/deny 列表**之前**应用，
|
||||
因此只能缩小工具集。
|
||||
提供商键接受 `provider`（例如 `google-antigravity`）或
|
||||
`provider/model`（例如 `openai/gpt-5.2`）。
|
||||
|
||||
示例（保持全局 coding 配置文件，但对 Google Antigravity 使用 minimal 工具）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
profile: "coding",
|
||||
byProvider: {
|
||||
"google-antigravity": { profile: "minimal" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
示例（针对不稳定端点的 provider/model 特定允许列表）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
allow: ["group:fs", "group:runtime", "sessions_list"],
|
||||
byProvider: {
|
||||
"openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
示例（针对单个提供商的智能体特定覆盖）：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "support",
|
||||
tools: {
|
||||
byProvider: {
|
||||
"google-antigravity": { allow: ["message", "sessions_list"] },
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 工具组（简写）
|
||||
|
||||
工具策略（全局、智能体、沙箱）支持 `group:*` 条目，可展开为多个工具。
|
||||
在 `tools.allow` / `tools.deny` 中使用。
|
||||
|
||||
可用组：
|
||||
|
||||
- `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:web`：`web_search`、`web_fetch`
|
||||
- `group:ui`：`browser`、`canvas`
|
||||
- `group:automation`：`cron`、`gateway`
|
||||
- `group:messaging`：`message`
|
||||
- `group:nodes`：`nodes`
|
||||
- `group:openclaw`：所有内置 OpenClaw 工具（不包括提供商插件）
|
||||
|
||||
示例（仅允许文件工具 + browser）：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
allow: ["group:fs", "browser"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 插件 + 工具
|
||||
|
||||
插件可以在核心工具集之外注册**额外的工具**（和 CLI 命令）。
|
||||
参见[插件](/plugin)了解安装和配置，以及[技能](/tools/skills)了解工具使用指导如何注入到提示词中。某些插件会随工具一起提供自己的技能（例如语音通话插件）。
|
||||
|
||||
可选插件工具：
|
||||
|
||||
- [Lobster](/tools/lobster)：类型化工作流运行时，支持可恢复的审批（需要 Gateway 主机上安装 Lobster CLI）。
|
||||
- [LLM Task](/tools/llm-task)：用于结构化工作流输出的纯 JSON LLM 步骤（可选 schema 验证）。
|
||||
|
||||
## 工具清单
|
||||
|
||||
### `apply_patch`
|
||||
|
||||
跨一个或多个文件应用结构化补丁。用于多段编辑。
|
||||
实验性功能：通过 `tools.exec.applyPatch.enabled` 启用（仅限 OpenAI 模型）。
|
||||
|
||||
### `exec`
|
||||
|
||||
在工作区中运行 shell 命令。
|
||||
|
||||
核心参数：
|
||||
|
||||
- `command`（必需）
|
||||
- `yieldMs`（超时后自动后台运行，默认 10000）
|
||||
- `background`（立即后台运行）
|
||||
- `timeout`（秒；超时后终止进程，默认 1800）
|
||||
- `elevated`（布尔值；如果提升模式已启用/允许，则在主机上运行；仅在智能体处于沙箱时改变行为）
|
||||
- `host`（`sandbox | gateway | node`）
|
||||
- `security`（`deny | allowlist | full`）
|
||||
- `ask`（`off | on-miss | always`）
|
||||
- `node`（用于 `host=node` 的节点 id/名称）
|
||||
- 需要真正的 TTY？设置 `pty: true`。
|
||||
|
||||
说明：
|
||||
|
||||
- 后台运行时返回 `status: "running"` 及 `sessionId`。
|
||||
- 使用 `process` 来轮询/查看日志/写入/终止/清除后台会话。
|
||||
- 如果 `process` 被禁止，`exec` 将同步运行并忽略 `yieldMs`/`background`。
|
||||
- `elevated` 受 `tools.elevated` 以及任何 `agents.list[].tools.elevated` 覆盖的门控（两者都必须允许），且是 `host=gateway` + `security=full` 的别名。
|
||||
- `elevated` 仅在智能体处于沙箱时改变行为（否则为空操作）。
|
||||
- `host=node` 可以指向 macOS 伴侣应用或无头节点主机（`openclaw node run`）。
|
||||
- Gateway/节点审批和允许列表：[Exec 审批](/tools/exec-approvals)。
|
||||
|
||||
### `process`
|
||||
|
||||
管理后台 exec 会话。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `list`、`poll`、`log`、`write`、`kill`、`clear`、`remove`
|
||||
|
||||
说明：
|
||||
|
||||
- `poll` 返回新输出，完成时返回退出状态。
|
||||
- `log` 支持基于行的 `offset`/`limit`（省略 `offset` 可获取最后 N 行）。
|
||||
- `process` 按智能体隔离；其他智能体的会话不可见。
|
||||
|
||||
### `web_search`
|
||||
|
||||
使用 Brave Search API 搜索网页。
|
||||
|
||||
核心参数：
|
||||
|
||||
- `query`（必需）
|
||||
- `count`（1–10；默认取自 `tools.web.search.maxResults`）
|
||||
|
||||
说明：
|
||||
|
||||
- 需要 Brave API 密钥（推荐：`openclaw configure --section web`，或设置 `BRAVE_API_KEY`）。
|
||||
- 通过 `tools.web.search.enabled` 启用。
|
||||
- 响应会被缓存（默认 15 分钟）。
|
||||
- 参见 [Web 工具](/tools/web)了解设置方法。
|
||||
|
||||
### `web_fetch`
|
||||
|
||||
从 URL 获取并提取可读内容（HTML → markdown/text）。
|
||||
|
||||
核心参数：
|
||||
|
||||
- `url`（必需）
|
||||
- `extractMode`（`markdown` | `text`）
|
||||
- `maxChars`（截断长页面）
|
||||
|
||||
说明：
|
||||
|
||||
- 通过 `tools.web.fetch.enabled` 启用。
|
||||
- 响应会被缓存（默认 15 分钟）。
|
||||
- 对于 JS 密集型网站，建议使用 browser 工具。
|
||||
- 参见 [Web 工具](/tools/web)了解设置方法。
|
||||
- 参见 [Firecrawl](/tools/firecrawl) 了解可选的反机器人回退方案。
|
||||
|
||||
### `browser`
|
||||
|
||||
控制 OpenClaw 管理的专用浏览器。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `status`、`start`、`stop`、`tabs`、`open`、`focus`、`close`
|
||||
- `snapshot`（aria/ai）
|
||||
- `screenshot`（返回图像块 + `MEDIA:<path>`）
|
||||
- `act`（UI 操作：click/type/press/hover/drag/select/fill/resize/wait/evaluate）
|
||||
- `navigate`、`console`、`pdf`、`upload`、`dialog`
|
||||
|
||||
配置文件管理：
|
||||
|
||||
- `profiles` — 列出所有浏览器配置文件及状态
|
||||
- `create-profile` — 创建新配置文件并自动分配端口（或 `cdpUrl`）
|
||||
- `delete-profile` — 停止浏览器、删除用户数据、从配置中移除（仅限本地）
|
||||
- `reset-profile` — 终止配置文件端口上的孤立进程（仅限本地）
|
||||
|
||||
常用参数：
|
||||
|
||||
- `profile`（可选；默认为 `browser.defaultProfile`）
|
||||
- `target`（`sandbox` | `host` | `node`）
|
||||
- `node`（可选；指定特定的节点 id/名称）
|
||||
说明：
|
||||
- 需要 `browser.enabled=true`（默认为 `true`；设为 `false` 可禁用）。
|
||||
- 所有操作接受可选的 `profile` 参数以支持多实例。
|
||||
- 省略 `profile` 时，使用 `browser.defaultProfile`（默认为 "chrome"）。
|
||||
- 配置文件名称：仅限小写字母数字 + 连字符（最多 64 个字符）。
|
||||
- 端口范围：18800-18899（最多约 100 个配置文件）。
|
||||
- 远程配置文件仅支持附加（不支持 start/stop/reset）。
|
||||
- 如果连接了支持浏览器的节点，工具可能会自动路由到该节点（除非你固定了 `target`）。
|
||||
- `snapshot` 在安装了 Playwright 时默认为 `ai`；使用 `aria` 获取无障碍树。
|
||||
- `snapshot` 还支持角色快照选项（`interactive`、`compact`、`depth`、`selector`），返回如 `e12` 的引用。
|
||||
- `act` 需要来自 `snapshot` 的 `ref`（AI 快照中的数字 `12`，或角色快照中的 `e12`）；对于少见的 CSS 选择器需求使用 `evaluate`。
|
||||
- 默认避免 `act` → `wait`；仅在特殊情况下使用（没有可靠的 UI 状态可等待时）。
|
||||
- `upload` 可以选择传递 `ref` 以在准备后自动点击。
|
||||
- `upload` 还支持 `inputRef`（aria 引用）或 `element`（CSS 选择器）以直接设置 `<input type="file">`。
|
||||
|
||||
### `canvas`
|
||||
|
||||
驱动节点 Canvas（展示、执行、快照、A2UI）。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `present`、`hide`、`navigate`、`eval`
|
||||
- `snapshot`（返回图像块 + `MEDIA:<path>`）
|
||||
- `a2ui_push`、`a2ui_reset`
|
||||
|
||||
说明：
|
||||
|
||||
- 底层使用 Gateway 的 `node.invoke`。
|
||||
- 如果未提供 `node`，工具会选择默认值（单个已连接节点或本地 mac 节点）。
|
||||
- A2UI 仅支持 v0.8（无 `createSurface`）；CLI 会拒绝 v0.9 JSONL 并报告行错误。
|
||||
- 快速测试：`openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"`。
|
||||
|
||||
### `nodes`
|
||||
|
||||
发现和定位已配对的节点；发送通知；捕获摄像头/屏幕。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `status`、`describe`
|
||||
- `pending`、`approve`、`reject`（配对）
|
||||
- `notify`（macOS `system.notify`）
|
||||
- `run`（macOS `system.run`）
|
||||
- `camera_snap`、`camera_clip`、`screen_record`
|
||||
- `location_get`
|
||||
|
||||
说明：
|
||||
|
||||
- 摄像头/屏幕命令需要节点应用处于前台。
|
||||
- 图像返回图像块 + `MEDIA:<path>`。
|
||||
- 视频返回 `FILE:<path>`（mp4）。
|
||||
- 位置返回 JSON 数据（lat/lon/accuracy/timestamp）。
|
||||
- `run` 参数：`command` argv 数组；可选 `cwd`、`env`（`KEY=VAL`）、`commandTimeoutMs`、`invokeTimeoutMs`、`needsScreenRecording`。
|
||||
|
||||
示例（`run`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"node": "office-mac",
|
||||
"command": ["echo", "Hello"],
|
||||
"env": ["FOO=bar"],
|
||||
"commandTimeoutMs": 12000,
|
||||
"invokeTimeoutMs": 45000,
|
||||
"needsScreenRecording": false
|
||||
}
|
||||
```
|
||||
|
||||
### `image`
|
||||
|
||||
使用配置的图像模型分析图像。
|
||||
|
||||
核心参数：
|
||||
|
||||
- `image`（必需，路径或 URL）
|
||||
- `prompt`（可选；默认为 "Describe the image."）
|
||||
- `model`（可选覆盖）
|
||||
- `maxBytesMb`（可选大小上限）
|
||||
|
||||
说明：
|
||||
|
||||
- 仅在配置了 `agents.defaults.imageModel`（主模型或后备模型）时可用，或者当可以从默认模型 + 已配置的认证信息推断出隐式图像模型时可用（尽力匹配）。
|
||||
- 直接使用图像模型（独立于主聊天模型）。
|
||||
|
||||
### `message`
|
||||
|
||||
跨 Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams 发送消息和渠道操作。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `send`（文本 + 可选媒体；MS Teams 还支持 `card` 用于 Adaptive Cards）
|
||||
- `poll`（WhatsApp/Discord/MS Teams 投票）
|
||||
- `react` / `reactions` / `read` / `edit` / `delete`
|
||||
- `pin` / `unpin` / `list-pins`
|
||||
- `permissions`
|
||||
- `thread-create` / `thread-list` / `thread-reply`
|
||||
- `search`
|
||||
- `sticker`
|
||||
- `member-info` / `role-info`
|
||||
- `emoji-list` / `emoji-upload` / `sticker-upload`
|
||||
- `role-add` / `role-remove`
|
||||
- `channel-info` / `channel-list`
|
||||
- `voice-status`
|
||||
- `event-list` / `event-create`
|
||||
- `timeout` / `kick` / `ban`
|
||||
|
||||
说明：
|
||||
|
||||
- `send` 通过 Gateway 路由 WhatsApp；其他渠道直接发送。
|
||||
- `poll` 对 WhatsApp 和 MS Teams 使用 Gateway；Discord 投票直接发送。
|
||||
- 当消息工具调用绑定到活跃的聊天会话时，发送将被限制在该会话的目标范围内，以避免跨上下文泄露。
|
||||
|
||||
### `cron`
|
||||
|
||||
管理 Gateway 定时任务和唤醒。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `status`、`list`
|
||||
- `add`、`update`、`remove`、`run`、`runs`
|
||||
- `wake`（入队系统事件 + 可选立即心跳）
|
||||
|
||||
说明：
|
||||
|
||||
- `add` 需要完整的 cron 任务对象（与 `cron.add` RPC 相同的 schema）。
|
||||
- `update` 使用 `{ id, patch }`。
|
||||
|
||||
### `gateway`
|
||||
|
||||
重启或向正在运行的 Gateway 进程应用更新（原地更新）。
|
||||
|
||||
核心操作：
|
||||
|
||||
- `restart`（授权 + 发送 `SIGUSR1` 进行进程内重启；`openclaw gateway` 原地重启）
|
||||
- `config.get` / `config.schema`
|
||||
- `config.apply`（验证 + 写入配置 + 重启 + 唤醒）
|
||||
- `config.patch`（合并部分更新 + 重启 + 唤醒）
|
||||
- `update.run`（运行更新 + 重启 + 唤醒）
|
||||
|
||||
说明：
|
||||
|
||||
- 使用 `delayMs`（默认 2000）以避免中断正在进行的回复。
|
||||
- `restart` 默认禁用；通过 `commands.restart: true` 启用。
|
||||
|
||||
### `sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`
|
||||
|
||||
列出会话、查看对话历史或向另一个会话发送消息。
|
||||
|
||||
核心参数：
|
||||
|
||||
- `sessions_list`：`kinds?`、`limit?`、`activeMinutes?`、`messageLimit?`（0 = 无）
|
||||
- `sessions_history`：`sessionKey`（或 `sessionId`）、`limit?`、`includeTools?`
|
||||
- `sessions_send`：`sessionKey`（或 `sessionId`）、`message`、`timeoutSeconds?`（0 = 即发即忘）
|
||||
- `sessions_spawn`：`task`、`label?`、`agentId?`、`model?`、`runTimeoutSeconds?`、`cleanup?`
|
||||
- `session_status`：`sessionKey?`（默认当前；接受 `sessionId`）、`model?`（`default` 清除覆盖）
|
||||
|
||||
说明：
|
||||
|
||||
- `main` 是规范的直接聊天键；global/unknown 被隐藏。
|
||||
- `messageLimit > 0` 获取每个会话的最后 N 条消息（工具消息被过滤）。
|
||||
- 当 `timeoutSeconds > 0` 时，`sessions_send` 会等待最终完成。
|
||||
- 投递/通告在完成后发生，且为尽力而为；`status: "ok"` 确认智能体运行已完成，而非通告已送达。
|
||||
- `sessions_spawn` 启动子智能体运行并向请求者聊天发送通告回复。
|
||||
- `sessions_spawn` 是非阻塞的，立即返回 `status: "accepted"`。
|
||||
- `sessions_send` 运行回复往返乒乓（回复 `REPLY_SKIP` 停止；最大轮次通过 `session.agentToAgent.maxPingPongTurns` 设置，0–5）。
|
||||
- 乒乓结束后，目标智能体运行一个**通告步骤**；回复 `ANNOUNCE_SKIP` 可抑制通告。
|
||||
|
||||
### `agents_list`
|
||||
|
||||
列出当前会话可通过 `sessions_spawn` 指向的智能体 id。
|
||||
|
||||
说明：
|
||||
|
||||
- 结果受每智能体允许列表限制（`agents.list[].subagents.allowAgents`）。
|
||||
- 配置为 `["*"]` 时，工具包含所有已配置的智能体并标记 `allowAny: true`。
|
||||
|
||||
## 参数（通用）
|
||||
|
||||
Gateway 支持的工具（`canvas`、`nodes`、`cron`）：
|
||||
|
||||
- `gatewayUrl`（默认 `ws://127.0.0.1:18789`）
|
||||
- `gatewayToken`（如果启用了认证）
|
||||
- `timeoutMs`
|
||||
|
||||
Browser 工具：
|
||||
|
||||
- `profile`（可选；默认为 `browser.defaultProfile`）
|
||||
- `target`（`sandbox` | `host` | `node`）
|
||||
- `node`（可选；固定特定的节点 id/名称）
|
||||
|
||||
## 推荐的智能体流程
|
||||
|
||||
浏览器自动化：
|
||||
|
||||
1. `browser` → `status` / `start`
|
||||
2. `snapshot`（ai 或 aria）
|
||||
3. `act`（click/type/press）
|
||||
4. 如需视觉确认则 `screenshot`
|
||||
|
||||
Canvas 渲染：
|
||||
|
||||
1. `canvas` → `present`
|
||||
2. `a2ui_push`（可选）
|
||||
3. `snapshot`
|
||||
|
||||
节点定位：
|
||||
|
||||
1. `nodes` → `status`
|
||||
2. 对选定节点执行 `describe`
|
||||
3. `notify` / `run` / `camera_snap` / `screen_record`
|
||||
|
||||
## 安全
|
||||
|
||||
- 避免直接使用 `system.run`；仅在获得用户明确同意后使用 `nodes` → `run`。
|
||||
- 尊重用户对摄像头/屏幕捕获的同意。
|
||||
- 在调用媒体命令前使用 `status/describe` 确认权限。
|
||||
|
||||
## 工具如何呈现给智能体
|
||||
|
||||
工具通过两个并行渠道暴露：
|
||||
|
||||
1. **系统提示词文本**：人类可读的列表 + 指导。
|
||||
2. **工具 schema**：发送给模型 API 的结构化函数定义。
|
||||
|
||||
这意味着智能体同时看到"存在哪些工具"和"如何调用它们"。如果某个工具
|
||||
未出现在系统提示词或 schema 中，模型将无法调用它。
|
||||
117
docs/zh-CN/tools/llm-task.md
Normal file
117
docs/zh-CN/tools/llm-task.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要在工作流中添加纯 JSON 的 LLM 步骤
|
||||
- 你需要经过 Schema 验证的 LLM 输出用于自动化
|
||||
summary: 用于工作流的纯 JSON LLM 任务（可选插件工具）
|
||||
title: LLM 任务
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:34Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: d81b74fcfd5491a9edb4bfadb47d404067020990b1f6d6d8fed652fbc860f646
|
||||
source_path: tools/llm-task.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# LLM 任务
|
||||
|
||||
`llm-task` 是一个**可选插件工具**，用于运行纯 JSON 的 LLM 任务并返回结构化输出（可选择根据 JSON Schema 进行验证）。
|
||||
|
||||
这非常适合像 Lobster 这样的工作流引擎：你可以添加单个 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。
|
||||
|
||||
## 启用插件
|
||||
|
||||
1. 启用插件：
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"llm-task": { "enabled": true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 将工具加入允许列表（它以 `optional: true` 注册）：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"tools": { "allow": ["llm-task"] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 配置（可选）
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"llm-task": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"defaultProvider": "openai-codex",
|
||||
"defaultModel": "gpt-5.2",
|
||||
"defaultAuthProfileId": "main",
|
||||
"allowedModels": ["openai-codex/gpt-5.2"],
|
||||
"maxTokens": 800,
|
||||
"timeoutMs": 30000
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`allowedModels` 是 `provider/model` 字符串的允许列表。如果设置了该项，任何不在列表中的请求都会被拒绝。
|
||||
|
||||
## 工具参数
|
||||
|
||||
- `prompt`（字符串，必填）
|
||||
- `input`（任意类型，可选）
|
||||
- `schema`（对象，可选 JSON Schema）
|
||||
- `provider`（字符串，可选）
|
||||
- `model`（字符串，可选）
|
||||
- `authProfileId`（字符串，可选）
|
||||
- `temperature`（数字，可选）
|
||||
- `maxTokens`（数字，可选）
|
||||
- `timeoutMs`（数字，可选）
|
||||
|
||||
## 输出
|
||||
|
||||
返回 `details.json`，包含解析后的 JSON（如果提供了 `schema`，则会进行验证）。
|
||||
|
||||
## 示例：Lobster 工作流步骤
|
||||
|
||||
```lobster
|
||||
openclaw.invoke --tool llm-task --action json --args-json '{
|
||||
"prompt": "Given the input email, return intent and draft.",
|
||||
"input": {
|
||||
"subject": "Hello",
|
||||
"body": "Can you help?"
|
||||
},
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"intent": { "type": "string" },
|
||||
"draft": { "type": "string" }
|
||||
},
|
||||
"required": ["intent", "draft"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 该工具为**纯 JSON 模式**，指示模型仅输出 JSON（无代码围栏、无注释说明）。
|
||||
- 此次运行不会向模型暴露任何工具。
|
||||
- 除非使用 `schema` 进行验证，否则应将输出视为不可信。
|
||||
- 在任何有副作用的步骤（发送、发布、执行）之前设置审批流程。
|
||||
348
docs/zh-CN/tools/lobster.md
Normal file
348
docs/zh-CN/tools/lobster.md
Normal file
@@ -0,0 +1,348 @@
|
||||
---
|
||||
description: Typed workflow runtime for OpenClaw — composable pipelines with approval gates.
|
||||
read_when:
|
||||
- 你需要具有显式审批的确定性多步骤工作流
|
||||
- 你需要恢复工作流而无需重新运行之前的步骤
|
||||
summary: OpenClaw 的类型化工作流运行时，支持可恢复的审批门控。
|
||||
title: Lobster
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:43:19Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: ff84e65f4be162ad98f16ddf0882f23b3198f05b4d9e8dc03d07e9b2bf0fd5ad
|
||||
source_path: tools/lobster.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Lobster
|
||||
|
||||
Lobster 是一个工作流外壳，让 OpenClaw 能够将多步骤工具序列作为单个确定性操作运行，并带有显式审批检查点。
|
||||
|
||||
## 亮点
|
||||
|
||||
你的助手可以构建管理自身的工具。请求一个工作流，30 分钟后你就能得到一个 CLI 加上作为单次调用运行的流水线。Lobster 就是缺失的那块拼图：确定性流水线、显式审批和可恢复状态。
|
||||
|
||||
## 为什么需要 Lobster
|
||||
|
||||
如今，复杂的工作流需要大量来回的工具调用。每次调用都消耗 token，而 LLM 必须编排每一个步骤。Lobster 将这种编排移入类型化运行时：
|
||||
|
||||
- **一次调用代替多次**：OpenClaw 运行一次 Lobster 工具调用即可获得结构化结果。
|
||||
- **内置审批**：副作用（发送邮件、发布评论）会暂停工作流，直到获得显式批准。
|
||||
- **可恢复**：暂停的工作流返回一个令牌；批准后可恢复执行，无需重新运行所有步骤。
|
||||
|
||||
## 为什么用 DSL 而不是普通程序？
|
||||
|
||||
Lobster 刻意保持小巧。目标不是"一门新语言"，而是一个可预测的、AI 友好的流水线规范，内置一等公民级别的审批和恢复令牌。
|
||||
|
||||
- **审批/恢复是内置的**：普通程序可以提示用户，但如果不自行发明运行时，它无法*暂停并通过持久令牌恢复*。
|
||||
- **确定性 + 可审计性**：流水线就是数据，因此易于记录、比较、重放和审查。
|
||||
- **为 AI 限定的表面积**：精简的语法 + JSON 管道减少了"创造性"代码路径，使验证更加可行。
|
||||
- **安全策略内置**：超时、输出上限、沙箱检查和允许列表由运行时强制执行，而非每个脚本自行处理。
|
||||
- **依然可编程**：每个步骤可以调用任何 CLI 或脚本。如果你想用 JS/TS，可以从代码生成 `.lobster` 文件。
|
||||
|
||||
## 工作原理
|
||||
|
||||
OpenClaw 以**工具模式**启动本地 `lobster` CLI，并从 stdout 解析 JSON 信封。
|
||||
如果流水线因需要审批而暂停，工具会返回一个 `resumeToken`，以便你稍后继续。
|
||||
|
||||
## 模式：小型 CLI + JSON 管道 + 审批
|
||||
|
||||
构建输出 JSON 的小型命令，然后将它们串联成单个 Lobster 调用。（以下为示例命令名称——替换为你自己的。）
|
||||
|
||||
```bash
|
||||
inbox list --json
|
||||
inbox categorize --json
|
||||
inbox apply --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'",
|
||||
"timeoutMs": 30000
|
||||
}
|
||||
```
|
||||
|
||||
如果流水线请求审批，使用令牌恢复：
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "resume",
|
||||
"token": "<resumeToken>",
|
||||
"approve": true
|
||||
}
|
||||
```
|
||||
|
||||
AI 触发工作流；Lobster 执行步骤。审批门控保持副作用的显式性和可审计性。
|
||||
|
||||
示例：将输入项映射为工具调用：
|
||||
|
||||
```bash
|
||||
gog.gmail.search --query 'newer_than:1d' \
|
||||
| openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
|
||||
```
|
||||
|
||||
## 纯 JSON 的 LLM 步骤（llm-task）
|
||||
|
||||
对于需要**结构化 LLM 步骤**的工作流，启用可选的
|
||||
`llm-task` 插件工具并从 Lobster 中调用它。这样既能保持工作流的确定性，又能利用模型进行分类/摘要/起草。
|
||||
|
||||
启用该工具：
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"llm-task": { "enabled": true }
|
||||
}
|
||||
},
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"tools": { "allow": ["llm-task"] }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在流水线中使用：
|
||||
|
||||
```lobster
|
||||
openclaw.invoke --tool llm-task --action json --args-json '{
|
||||
"prompt": "Given the input email, return intent and draft.",
|
||||
"input": { "subject": "Hello", "body": "Can you help?" },
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"intent": { "type": "string" },
|
||||
"draft": { "type": "string" }
|
||||
},
|
||||
"required": ["intent", "draft"],
|
||||
"additionalProperties": false
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
详情和配置选项请参阅 [LLM Task](/tools/llm-task)。
|
||||
|
||||
## 工作流文件（.lobster）
|
||||
|
||||
Lobster 可以运行包含 `name`、`args`、`steps`、`env`、`condition` 和 `approval` 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 `pipeline` 设置为文件路径。
|
||||
|
||||
```yaml
|
||||
name: inbox-triage
|
||||
args:
|
||||
tag:
|
||||
default: "family"
|
||||
steps:
|
||||
- id: collect
|
||||
command: inbox list --json
|
||||
- id: categorize
|
||||
command: inbox categorize --json
|
||||
stdin: $collect.stdout
|
||||
- id: approve
|
||||
command: inbox apply --approve
|
||||
stdin: $categorize.stdout
|
||||
approval: required
|
||||
- id: execute
|
||||
command: inbox apply --execute
|
||||
stdin: $categorize.stdout
|
||||
condition: $approve.approved
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `stdin: $step.stdout` 和 `stdin: $step.json` 传递前一步骤的输出。
|
||||
- `condition`（或 `when`）可以基于 `$step.approved` 来控制步骤执行。
|
||||
|
||||
## 安装 Lobster
|
||||
|
||||
在运行 OpenClaw Gateway 的**同一主机**上安装 Lobster CLI（参见 [Lobster 仓库](https://github.com/openclaw/lobster)），并确保 `lobster` 在 `PATH` 中。
|
||||
如果你想使用自定义二进制文件位置，请在工具调用中传入**绝对路径** `lobsterPath`。
|
||||
|
||||
## 启用工具
|
||||
|
||||
Lobster 是一个**可选**插件工具（默认未启用）。
|
||||
|
||||
推荐方式（增量添加，安全）：
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"alsoAllow": ["lobster"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
或按智能体配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"tools": {
|
||||
"alsoAllow": ["lobster"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
避免使用 `tools.allow: ["lobster"]`，除非你打算以严格允许列表模式运行。
|
||||
|
||||
注意：允许列表对可选插件是选择性加入的。如果你的允许列表只包含
|
||||
插件工具（如 `lobster`），OpenClaw 会保持核心工具启用。要限制核心
|
||||
工具，请在允许列表中同时包含你需要的核心工具或工具组。
|
||||
|
||||
## 示例：邮件分类
|
||||
|
||||
不使用 Lobster：
|
||||
|
||||
```
|
||||
用户："检查我的邮件并起草回复"
|
||||
→ openclaw 调用 gmail.list
|
||||
→ LLM 进行摘要
|
||||
→ 用户："给 #2 和 #5 起草回复"
|
||||
→ LLM 起草
|
||||
→ 用户："发送 #2"
|
||||
→ openclaw 调用 gmail.send
|
||||
（每天重复，不记得之前分类了什么）
|
||||
```
|
||||
|
||||
使用 Lobster：
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"pipeline": "email.triage --limit 20",
|
||||
"timeoutMs": 30000
|
||||
}
|
||||
```
|
||||
|
||||
返回 JSON 信封（已截断）：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"status": "needs_approval",
|
||||
"output": [{ "summary": "5 need replies, 2 need action" }],
|
||||
"requiresApproval": {
|
||||
"type": "approval_request",
|
||||
"prompt": "Send 2 draft replies?",
|
||||
"items": [],
|
||||
"resumeToken": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
用户批准 → 恢复：
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "resume",
|
||||
"token": "<resumeToken>",
|
||||
"approve": true
|
||||
}
|
||||
```
|
||||
|
||||
一个工作流。确定性。安全。
|
||||
|
||||
## 工具参数
|
||||
|
||||
### `run`
|
||||
|
||||
以工具模式运行流水线。
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
|
||||
"cwd": "/path/to/workspace",
|
||||
"timeoutMs": 30000,
|
||||
"maxStdoutBytes": 512000
|
||||
}
|
||||
```
|
||||
|
||||
使用参数运行工作流文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"pipeline": "/path/to/inbox-triage.lobster",
|
||||
"argsJson": "{\"tag\":\"family\"}"
|
||||
}
|
||||
```
|
||||
|
||||
### `resume`
|
||||
|
||||
审批后继续暂停的工作流。
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "resume",
|
||||
"token": "<resumeToken>",
|
||||
"approve": true
|
||||
}
|
||||
```
|
||||
|
||||
### 可选输入
|
||||
|
||||
- `lobsterPath`：Lobster 二进制文件的绝对路径（省略则使用 `PATH`）。
|
||||
- `cwd`：流水线的工作目录（默认为当前进程工作目录）。
|
||||
- `timeoutMs`：如果子进程超过此时长则终止（默认：20000）。
|
||||
- `maxStdoutBytes`：如果 stdout 超过此大小则终止子进程（默认：512000）。
|
||||
- `argsJson`：传递给 `lobster run --args-json` 的 JSON 字符串（仅限工作流文件）。
|
||||
|
||||
## 输出信封
|
||||
|
||||
Lobster 返回一个 JSON 信封，包含以下三种状态之一：
|
||||
|
||||
- `ok` → 成功完成
|
||||
- `needs_approval` → 已暂停；需要 `requiresApproval.resumeToken` 来恢复
|
||||
- `cancelled` → 被显式拒绝或取消
|
||||
|
||||
该工具在 `content`（格式化 JSON）和 `details`（原始对象）中都会展示信封内容。
|
||||
|
||||
## 审批
|
||||
|
||||
如果存在 `requiresApproval`，检查提示并决定：
|
||||
|
||||
- `approve: true` → 恢复并继续执行副作用
|
||||
- `approve: false` → 取消并终结工作流
|
||||
|
||||
使用 `approve --preview-from-stdin --limit N` 将 JSON 预览附加到审批请求中，无需自定义 jq/heredoc 粘合代码。恢复令牌现在更加紧凑：Lobster 将工作流恢复状态存储在其状态目录下，并返回一个小型令牌密钥。
|
||||
|
||||
## OpenProse
|
||||
|
||||
OpenProse 与 Lobster 配合良好：使用 `/prose` 编排多智能体准备工作，然后运行 Lobster 流水线进行确定性审批。如果 Prose 程序需要 Lobster，可通过 `tools.subagents.tools` 为子智能体允许 `lobster` 工具。参见 [OpenProse](/prose)。
|
||||
|
||||
## 安全性
|
||||
|
||||
- **仅限本地子进程** — 插件本身不发起网络调用。
|
||||
- **无密钥** — Lobster 不管理 OAuth；它调用处理 OAuth 的 OpenClaw 工具。
|
||||
- **沙箱感知** — 当工具上下文处于沙箱中时自动禁用。
|
||||
- **加固** — 如果指定了 `lobsterPath` 则必须为绝对路径；超时和输出上限强制执行。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- **`lobster subprocess timed out`** → 增加 `timeoutMs`，或拆分长流水线。
|
||||
- **`lobster output exceeded maxStdoutBytes`** → 提高 `maxStdoutBytes` 或减少输出大小。
|
||||
- **`lobster returned invalid JSON`** → 确保流水线以工具模式运行且仅输出 JSON。
|
||||
- **`lobster failed (code …)`** → 在终端中运行相同的流水线以检查 stderr。
|
||||
|
||||
## 了解更多
|
||||
|
||||
- [插件](/plugin)
|
||||
- [插件工具开发](/plugins/agent-tools)
|
||||
|
||||
## 案例研究：社区工作流
|
||||
|
||||
一个公开示例：一个"第二大脑" CLI + Lobster 流水线，管理三个 Markdown 库（个人、伴侣、共享）。CLI 输出 JSON 格式的统计数据、收件箱列表和过期扫描；Lobster 将这些命令串联成工作流，如 `weekly-review`、`inbox-triage`、`memory-consolidation` 和 `shared-task-sync`，每个都带有审批门控。AI 在可用时处理判断（分类），不可用时回退到确定性规则。
|
||||
|
||||
- 帖子：https://x.com/plattenschieber/status/2014508656335770033
|
||||
- 仓库：https://github.com/bloomedai/brain-cli
|
||||
29
docs/zh-CN/tools/reactions.md
Normal file
29
docs/zh-CN/tools/reactions.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 在任何渠道中处理表情回应相关工作
|
||||
summary: 跨渠道共享的表情回应语义
|
||||
title: 表情回应
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:41Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 0f11bff9adb4bd02604f96ebe2573a623702796732b6e17dfeda399cb7be0fa6
|
||||
source_path: tools/reactions.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 表情回应工具
|
||||
|
||||
跨渠道共享的表情回应语义：
|
||||
|
||||
- 添加表情回应时，`emoji` 为必填项。
|
||||
- `emoji=""` 在支持的情况下移除机器人的表情回应。
|
||||
- `remove: true` 在支持的情况下移除指定的表情（需要提供 `emoji`）。
|
||||
|
||||
渠道说明：
|
||||
|
||||
- **Discord/Slack**：空 `emoji` 移除机器人在该消息上的所有表情回应；`remove: true` 仅移除指定的表情。
|
||||
- **Google Chat**：空 `emoji` 移除应用在该消息上的表情回应；`remove: true` 仅移除指定的表情。
|
||||
- **Telegram**：空 `emoji` 移除机器人的表情回应；`remove: true` 同样移除表情回应，但工具验证仍要求 `emoji` 为非空值。
|
||||
- **WhatsApp**：空 `emoji` 移除机器人的表情回应；`remove: true` 映射为空 emoji（仍需提供 `emoji`）。
|
||||
- **Signal**：当启用 `channels.signal.reactionNotifications` 时，收到的表情回应通知会触发系统事件。
|
||||
78
docs/zh-CN/tools/skills-config.md
Normal file
78
docs/zh-CN/tools/skills-config.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改技能配置时
|
||||
- 调整内置允许列表或安装行为时
|
||||
summary: 技能配置结构与示例
|
||||
title: 技能配置
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:42:49Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: e265c93da7856887c11abd92b379349181549e1a02164184d61a8d1f6b2feed5
|
||||
source_path: tools/skills-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 技能配置
|
||||
|
||||
所有技能相关配置位于 `~/.openclaw/openclaw.json` 的 `skills` 下。
|
||||
|
||||
```json5
|
||||
{
|
||||
skills: {
|
||||
allowBundled: ["gemini", "peekaboo"],
|
||||
load: {
|
||||
extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
|
||||
watch: true,
|
||||
watchDebounceMs: 250,
|
||||
},
|
||||
install: {
|
||||
preferBrew: true,
|
||||
nodeManager: "npm", // npm | pnpm | yarn | bun（Gateway 运行时仍为 Node；不推荐 bun）
|
||||
},
|
||||
entries: {
|
||||
"nano-banana-pro": {
|
||||
enabled: true,
|
||||
apiKey: "GEMINI_KEY_HERE",
|
||||
env: {
|
||||
GEMINI_API_KEY: "GEMINI_KEY_HERE",
|
||||
},
|
||||
},
|
||||
peekaboo: { enabled: true },
|
||||
sag: { enabled: false },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 字段
|
||||
|
||||
- `allowBundled`：可选的**内置**技能允许列表。设置后，只有列表中的内置技能可用（托管/工作区技能不受影响）。
|
||||
- `load.extraDirs`：要扫描的额外技能目录（优先级最低）。
|
||||
- `load.watch`：监视技能文件夹并刷新技能快照（默认：true）。
|
||||
- `load.watchDebounceMs`：技能监视器事件的防抖时间（毫秒，默认：250）。
|
||||
- `install.preferBrew`：可用时优先使用 brew 安装器（默认：true）。
|
||||
- `install.nodeManager`：Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`，默认：npm）。此选项仅影响**技能安装**；Gateway 运行时应仍使用 Node（不推荐在 WhatsApp/Telegram 中使用 Bun）。
|
||||
- `entries.<skillKey>`：按技能的覆盖配置。
|
||||
|
||||
按技能字段：
|
||||
|
||||
- `enabled`：设为 `false` 可禁用技能，即使它是内置/已安装的。
|
||||
- `env`：为智能体运行注入的环境变量（仅在尚未设置时生效）。
|
||||
- `apiKey`：可选的便捷字段，用于声明了主要环境变量的技能。
|
||||
|
||||
## 说明
|
||||
|
||||
- `entries` 下的键默认映射到技能名称。如果技能定义了 `metadata.openclaw.skillKey`，请使用该键。
|
||||
- 启用监视器时，技能的更改会在下一个智能体回合时生效。
|
||||
|
||||
### 沙箱化技能与环境变量
|
||||
|
||||
当会话处于**沙箱**模式时，技能进程在 Docker 内运行。沙箱**不会**继承主机的 `process.env`。
|
||||
|
||||
请使用以下方式之一：
|
||||
|
||||
- `agents.defaults.sandbox.docker.env`（或按智能体 `agents.list[].sandbox.docker.env`）
|
||||
- 将环境变量烘焙到您的自定义沙箱镜像中
|
||||
|
||||
全局 `env` 和 `skills.entries.<skill>.env/apiKey` 仅适用于**主机**运行。
|
||||
284
docs/zh-CN/tools/skills.md
Normal file
284
docs/zh-CN/tools/skills.md
Normal file
@@ -0,0 +1,284 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改技能
|
||||
- 更改技能门控或加载规则
|
||||
summary: 技能：托管型与工作区型、门控规则，以及配置/环境变量连接
|
||||
title: 技能
|
||||
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
|
||||
---
|
||||
|
||||
# 技能（OpenClaw）
|
||||
|
||||
OpenClaw 使用与 **[AgentSkills](https://agentskills.io) 兼容**的技能文件夹来教智能体如何使用工具。每个技能是一个目录，包含带有 YAML frontmatter 和说明的 `SKILL.md` 文件。OpenClaw 加载**内置技能**以及可选的本地覆盖，并在加载时根据环境、配置和二进制文件是否存在进行过滤。
|
||||
|
||||
## 位置和优先级
|
||||
|
||||
技能从**三个**位置加载：
|
||||
|
||||
1. **内置技能**：随安装包一起分发（npm 包或 OpenClaw.app）
|
||||
2. **托管/本地技能**：`~/.openclaw/skills`
|
||||
3. **工作区技能**：`<workspace>/skills`
|
||||
|
||||
如果技能名称冲突，优先级为：
|
||||
|
||||
`<workspace>/skills`（最高）→ `~/.openclaw/skills` → 内置技能（最低）
|
||||
|
||||
此外，你可以通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 配置额外的技能文件夹（最低优先级）。
|
||||
|
||||
## 按智能体与共享技能
|
||||
|
||||
在**多智能体**设置中，每个智能体拥有自己的工作区。这意味着：
|
||||
|
||||
- **按智能体技能**位于该智能体专属的 `<workspace>/skills` 中。
|
||||
- **共享技能**位于 `~/.openclaw/skills`（托管/本地），对同一机器上的**所有智能体**可见。
|
||||
- **共享文件夹**也可以通过 `skills.load.extraDirs`（最低优先级）添加，如果你希望多个智能体使用同一套技能包。
|
||||
|
||||
如果同一技能名称存在于多个位置，适用通常的优先级规则：工作区优先，然后是托管/本地，最后是内置。
|
||||
|
||||
## 插件 + 技能
|
||||
|
||||
插件可以通过在 `openclaw.plugin.json` 中列出 `skills` 目录（相对于插件根目录的路径）来附带自己的技能。插件技能在插件启用时加载，并参与正常的技能优先级规则。你可以通过插件配置项上的 `metadata.openclaw.requires.config` 进行门控。参见[插件](/plugin)了解发现/配置，参见[工具](/tools)了解这些技能教授的工具功能。
|
||||
|
||||
## ClawHub（安装 + 同步）
|
||||
|
||||
ClawHub 是 OpenClaw 的公共技能注册中心。浏览地址：https://clawhub.com。使用它来发现、安装、更新和备份技能。完整指南：[ClawHub](/tools/clawhub)。
|
||||
|
||||
常用流程：
|
||||
|
||||
- 将技能安装到你的工作区：
|
||||
- `clawhub install <skill-slug>`
|
||||
- 更新所有已安装的技能：
|
||||
- `clawhub update --all`
|
||||
- 同步（扫描 + 发布更新）：
|
||||
- `clawhub sync --all`
|
||||
|
||||
默认情况下，`clawhub` 安装到当前工作目录下的 `./skills`（或回退到已配置的 OpenClaw 工作区）。OpenClaw 在下次会话时将其作为 `<workspace>/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}` 引用技能文件夹路径。
|
||||
- 可选的 frontmatter 键：
|
||||
- `homepage` — 在 macOS 技能 UI 中显示为"网站"的 URL（也支持通过 `metadata.openclaw.homepage` 设置）。
|
||||
- `user-invocable` — `true|false`（默认：`true`）。为 `true` 时，技能作为用户斜杠命令暴露。
|
||||
- `disable-model-invocation` — `true|false`（默认：`false`）。为 `true` 时，技能从模型提示词中排除（仍可通过用户调用使用）。
|
||||
- `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）**在加载时过滤技能**：
|
||||
|
||||
```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` — 始终包含该技能（跳过其他门控）。
|
||||
- `emoji` — macOS 技能 UI 使用的可选表情符号。
|
||||
- `homepage` — macOS 技能 UI 中显示为"网站"的可选 URL。
|
||||
- `os` — 可选的平台列表（`darwin`、`linux`、`win32`）。如果设置，技能仅在这些操作系统上可用。
|
||||
- `requires.bins` — 列表；每个都必须存在于 `PATH` 中。
|
||||
- `requires.anyBins` — 列表；至少一个必须存在于 `PATH` 中。
|
||||
- `requires.env` — 列表；环境变量必须存在**或**在配置中提供。
|
||||
- `requires.config` — `openclaw.json` 路径列表，必须为真值。
|
||||
- `primaryEnv` — 与 `skills.entries.<name>.apiKey` 关联的环境变量名。
|
||||
- `install` — macOS 技能 UI 使用的可选安装器规格数组（brew/node/go/uv/download）。
|
||||
|
||||
关于沙箱的说明：
|
||||
|
||||
- `requires.bins` 在技能加载时在**宿主**上检查。
|
||||
- 如果智能体在沙箱中运行，二进制文件也必须存在于**容器内部**。
|
||||
通过 `agents.defaults.sandbox.docker.setupCommand`（或自定义镜像）安装它。
|
||||
`setupCommand` 在容器创建后运行一次。
|
||||
包安装还需要网络出站权限、可写的根文件系统以及沙箱中的 root 用户。
|
||||
示例：`summarize` 技能（`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）。
|
||||
这仅影响**技能安装**；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.allowBundled` 对内置技能进行了限制）。
|
||||
|
||||
## 配置覆盖（`~/.openclaw/openclaw.json`）
|
||||
|
||||
内置/托管技能可以切换启用状态并提供环境变量值：
|
||||
|
||||
```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 },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意：如果技能名称包含连字符，请给键加引号（JSON5 允许带引号的键）。
|
||||
|
||||
配置键默认匹配**技能名称**。如果技能定义了 `metadata.openclaw.skillKey`，请在 `skills.entries` 下使用该键。
|
||||
|
||||
规则：
|
||||
|
||||
- `enabled: false` 禁用技能，即使它是内置/已安装的。
|
||||
- `env`：仅在进程中该变量**尚未设置**时注入。
|
||||
- `apiKey`：为声明了 `metadata.openclaw.primaryEnv` 的技能提供的便捷方式。
|
||||
- `config`：用于自定义按技能字段的可选容器；自定义键必须放在此处。
|
||||
- `allowBundled`：仅针对**内置**技能的可选允许列表。如果设置，只有列表中的内置技能才可用（托管/工作区技能不受影响）。
|
||||
|
||||
## 环境注入（按智能体运行）
|
||||
|
||||
当智能体运行开始时，OpenClaw：
|
||||
|
||||
1. 读取技能元数据。
|
||||
2. 将 `skills.entries.<key>.env` 或 `skills.entries.<key>.apiKey` 应用到 `process.env`。
|
||||
3. 使用**符合条件**的技能构建系统提示词。
|
||||
4. 运行结束后恢复原始环境。
|
||||
|
||||
这是**限定在智能体运行范围内**的，而非全局 shell 环境。
|
||||
|
||||
## 会话快照（性能）
|
||||
|
||||
OpenClaw 在**会话开始时**对符合条件的技能进行快照，并在同一会话的后续轮次中复用该列表。对技能或配置的更改在下一个新会话中生效。
|
||||
|
||||
技能也可以在会话中途刷新，当技能监视器启用时或当新的符合条件的远程节点出现时（见下文）。可以将其理解为**热重载**：刷新后的列表会在下一个智能体轮次中被使用。
|
||||
|
||||
## 远程 macOS 节点（Linux Gateway）
|
||||
|
||||
如果 Gateway 运行在 Linux 上，但有一个**macOS 节点**已连接且**允许 `system.run`**（执行审批安全级别未设为 `deny`），OpenClaw 可以在该节点上存在所需二进制文件时，将仅限 macOS 的技能视为可用。智能体应通过 `nodes` 工具（通常是 `nodes.run`）执行这些技能。
|
||||
|
||||
这依赖于节点报告其命令支持情况以及通过 `system.run` 进行的二进制探测。如果 macOS 节点之后离线，技能仍然可见；在节点重新连接之前，调用可能会失败。
|
||||
|
||||
## 技能监视器（自动刷新）
|
||||
|
||||
默认情况下，OpenClaw 监视技能文件夹，并在 `SKILL.md` 文件更改时更新技能快照。在 `skills.load` 下配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
skills: {
|
||||
load: {
|
||||
watch: true,
|
||||
watchDebounceMs: 250,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Token 影响（技能列表）
|
||||
|
||||
当有符合条件的技能时，OpenClaw 会将一个紧凑的 XML 可用技能列表注入系统提示词（通过 `pi-coding-agent` 中的 `formatSkillsForPrompt`）。开销是确定性的：
|
||||
|
||||
- **基础开销（仅在有 ≥1 个技能时）：**195 个字符。
|
||||
- **每个技能：**97 个字符 + XML 转义后的 `<name>`、`<description>` 和 `<location>` 值的长度。
|
||||
|
||||
公式（字符数）：
|
||||
|
||||
```
|
||||
total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- XML 转义会将 `& < > " '` 展开为实体（`&`、`<` 等），增加长度。
|
||||
- Token 数量因模型分词器而异。粗略的 OpenAI 风格估算约为 ~4 字符/token，因此**97 字符 ≈ 24 个 token**（每个技能），加上你实际的字段长度。
|
||||
|
||||
## 托管技能生命周期
|
||||
|
||||
OpenClaw 将一组基线技能作为**内置技能**随安装包（npm 包或 OpenClaw.app）一起分发。`~/.openclaw/skills` 用于本地覆盖（例如，在不更改内置副本的情况下固定/修补某个技能）。工作区技能由用户拥有，在名称冲突时覆盖两者。
|
||||
|
||||
## 配置参考
|
||||
|
||||
参见[技能配置](/tools/skills-config)了解完整的配置模式。
|
||||
|
||||
## 想要更多技能？
|
||||
|
||||
浏览 https://clawhub.com。
|
||||
|
||||
---
|
||||
205
docs/zh-CN/tools/slash-commands.md
Normal file
205
docs/zh-CN/tools/slash-commands.md
Normal file
@@ -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"`）在支持的平台上将**技能**命令注册为原生命令。
|
||||
- Auto：Discord/Telegram 启用；Slack 关闭（Slack 需要为每个技能创建一个斜杠命令）。
|
||||
- 设置 `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]`（按名称运行技能）
|
||||
- `/status`（显示当前状态；在可用时包含当前模型提供商的用量/配额信息）
|
||||
- `/allowlist`（列出/添加/移除允许列表条目）
|
||||
- `/approve <id> allow-once|allow-always|deny`（处理执行审批提示）
|
||||
- `/context [list|detail|json]`（解释"上下文"；`detail` 显示每个文件 + 每个工具 + 每个技能 + 系统提示的大小）
|
||||
- `/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`）。
|
||||
- 未授权的纯命令消息会被静默忽略，内联的 `/...` 标记会被当作纯文本处理。
|
||||
- **技能命令：**`user-invocable` 技能会作为斜杠命令暴露。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突时会添加数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行技能（在原生命令限制阻止创建逐技能命令时很有用）。
|
||||
- 默认情况下，技能命令会作为普通请求转发给模型。
|
||||
- 技能可以选择性地声明 `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 按钮形式呈现。
|
||||
155
docs/zh-CN/tools/subagents.md
Normal file
155
docs/zh-CN/tools/subagents.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
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` 仍然优先。
|
||||
|
||||
工具参数：
|
||||
|
||||
- `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`）。
|
||||
80
docs/zh-CN/tools/thinking.md
Normal file
80
docs/zh-CN/tools/thinking.md
Normal file
@@ -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>` 指令（和之前一样）；选择器将在下次刷新后反映该设置。
|
||||
264
docs/zh-CN/tools/web.md
Normal file
264
docs/zh-CN/tools/web.md
Normal file
@@ -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` 会返回一个简短的设置提示及文档链接。
|
||||
Reference in New Issue
Block a user